README
¶
Ship
Ship is a go library for building efficient event driven applications. It provides protoc plugin library for efficient proto-based event generation.
Goals
- Easy to understand
- Fast
- Resilient
How to use it
Usage
To mark any message inside a proto file as an event.
- Import the
schema/ship.protoinside the proto file. - Add the
option (ship.event) = true;inside the message definition.
Example:
syntax = "proto3";
package example.v1;
option go_package = "v1/example";
import "schema/ship.proto";
message SomethingCreated {
// marking a message as an event will generate the required the files for it.
option (ship.event) = true;
string id = 1;
string name = 2;
string created_at = 3;
}
Installation
1. Get the protoc plugin
Install protoc-gen-ship from the following command
go get -u github.com/Flahmingo-Investments/ship/protoc-gen-ship/...
2. Get the proto file
Get the schema/ship.proto file
3. Compile the proto file
To compile.
protoc \
-I . \
--ship_out="some/path/" \
path/to/proto/file
Examples
You can see the examples in example folder.
To build the example files, run the following commands
make example
Development
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RegisterEvent ¶
func RegisterEvent(e Event)
RegisterEvent registers an event to be global available for serialization, and other dependents. It used to create concrete event data structs when loading from event store.
func UnregisterEvent ¶
func UnregisterEvent(event Event)
UnregisterEvent removes the event from registered events list. This is mainly useful in mainenance situations where the event data needs to be switched in a migrations or test.
Types ¶
type Event ¶
type Event interface {
// EventName returns the name of the event.
EventName() string
}
Event is a payload for a message.
type Message ¶
type Message struct {
// ID is event id.
ID string `db:"id" json:"id"`
// Metadata about the event and message.
Metadata Metadata `db:"metadata" json:"metadata"`
// Type is event name.
//
// For example: UserOnBoarded, AccountClosed, etc.
Type string `db:"type" json:"type"`
// AggregateID is domain aggregate id for which we are storing the events for.
AggregateID string `db:"aggregate_id" json:"aggregate_id"`
// AggregateType is aggregate name.
//
// For example: User, Account, etc.
AggregateType string `db:"aggregate_type" json:"aggregate_type"`
// Data is event data that we are storing.
Data Event `db:"data" json:"data"`
// At, what time the event occurred.
At time.Time `db:"at" json:"at"`
// Version of the event or message.
Version uint64 `db:"version" json:"version"`
}
Message is the fundamental unit for passing messages and events inside a ship application.
type MessageHandler ¶
type MessageHandler interface {
// HandleMessage handles a received message from Subscriber.
HandleMessage(ctx context.Context, m *Message) error
}
MessageHandler provides method to handle a received message.
type MessageHandlerFunc ¶
MessageHandlerFunc type is an adapter to allow the use of ordinary functions as Message handlers. If f is a function with the appropriate signature, MessageHandlerFunc(f) is a Handler that calls f.
func (MessageHandlerFunc) HandleMessage ¶
func (f MessageHandlerFunc) HandleMessage(ctx context.Context, m *Message) error
HandleMessage handles a received message from Subscriber.
type Metadata ¶
Metadata is an alias for map[string]string
type PubSub ¶
type PubSub interface {
Publisher
Subscriber
}
PubSub groups both Publisher and Subscriber methods together.
type Publisher ¶
type Publisher interface {
// Publish publishes provided messages to given topic.
Publish(topic string, messages *Message) error
// PublishRaw publishes provided messages to given topic.
PublishRaw(topic string, message *RawMessage) error
}
Publisher publishes message to a given topic.
type RawMessage ¶ added in v0.2.0
type RawMessage struct {
// ID identifies this message. This ID is assigned by the server and is
// populated for Messages obtained from a subscription.
//
// This field is read-only.
ID string
// Data is the actual data in the message.
Data []byte
// Attributes represents the key-value pairs the current message is
// labelled with.
Attributes map[string]string
// PublishTime is the time at which the message was published. This is
// populated by the server for Messages obtained from a subscription.
//
// This field is read-only.
PublishTime time.Time
// OrderingKey identifies related messages for which publish order should
// be respected. If empty string is used, message will be sent unordered.
OrderingKey string
}
RawMessage is the pure message and does not do any conversion.
type RawMessageHandler ¶ added in v0.2.0
type RawMessageHandler interface {
// HandleRawMessage handles a received message from Subscriber.
HandleRawMessage(ctx context.Context, m *RawMessage) error
}
RawMessageHandler provides method to handle a received message.
type Subscriber ¶
type Subscriber interface {
// Subscribe subscribe to a given subscription.
Subscribe(subscription string, handler MessageHandler) error
// SubscribeRaw subscribe to a given subscription.
SubscribeRaw(subscription string, handler RawMessageHandler) error
}
Subscriber subscribes to a given subscription.
Source Files
Directories