ship

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.

1. Import the schema/ship.proto inside the proto file.
2. 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

• func RegisterEvent(e Event)
• func UnregisterEvent(event Event)
• type Event
  • func GetEvent(name string) (Event, error)
• type Message
• type MessageHandler
• type MessageHandlerFunc
  • func (f MessageHandlerFunc) HandleMessage(ctx context.Context, m *Message) error
• type Metadata
  • func (m Metadata) Scan(v interface{}) error
  • func (m Metadata) Value() (driver.Value, error)
• type PubSub
• type Publisher
• type RawMessage
• type RawMessageHandler
• type Subscriber

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.

func GetEvent

func GetEvent(name string) (Event, error)

GetEvent returns a new instance of event matching it's name or an error if the event is not registered.

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

type MessageHandlerFunc func(context.Context, *Message) error

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

type Metadata map[string]string

Metadata is an alias for map[string]string

func (Metadata) Scan

func (m Metadata) Scan(v interface{}) error

Scan implements the sql Scanner interface.

func (Metadata) Value

func (m Metadata) Value() (driver.Value, error)

Value implements the driver Valuer interface.

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

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

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.