pubsub

Documentation

Index

• type JoinServer
• type Router
  • func NewJoiner(s JoinServer) Router
  • func (ps Router) AddRef() Router
  • func (ps Router) Join(ctx context.Context, topic string) (Topic, capnp.ReleaseFunc)
  • func (ps Router) Release()
• type Server
  • func (r *Server) Client() capnp.Client
  • func (r *Server) Join(ctx context.Context, call api.Router_join) error
  • func (r *Server) PubSub() Router
• type Subscription
  • func (sub Subscription) Err() error
  • func (sub Subscription) Next() []byte
• type Topic
  • func NewTopic(s TopicServer) Topic
  • func (t Topic) AddRef() Topic
  • func (t Topic) Name(ctx context.Context) (string, error)
  • func (t Topic) Publish(ctx context.Context, b []byte) error
  • func (t Topic) Release()
  • func (t Topic) Subscribe(ctx context.Context) (Subscription, capnp.ReleaseFunc)
• type TopicJoiner
• type TopicServer

Types

type JoinServer

type JoinServer interface {
	Join(context.Context, api.Router_join) error
}

JoinServer is an interface that allows alternate server implementations for Joiner. The default implementation is Router. See: NewJoiner.

type Router

type Router api.Router

Router is a client capability that confers the right to join pubsub topics. It is the dual to Router.

func NewJoiner

func NewJoiner(s JoinServer) Router

NewJoiner returns a Joiner (a capability client) from a JoinServer interface. Most users will prefer to instantiate a Joiner directly by calling the Router.PubSub method.

NewJoiner allows callers to supply alternate implementations of JoinServer. This is most commonly used in unit-testing.

func (Router) AddRef

func (ps Router) AddRef() Router

func (Router) Join

func (ps Router) Join(ctx context.Context, topic string) (Topic, capnp.ReleaseFunc)

Join topic. Callers MUST use the returned ReleaseFunc to leave the topic when finished.

func (Router) Release

func (ps Router) Release()

type Server

type Server struct {
	Log         log.Logger
	TopicJoiner TopicJoiner
	// contains filtered or unexported fields
}

Server for the pubsub capability.

func (*Server) Client

func (r *Server) Client() capnp.Client

func (*Server) Join

func (r *Server) Join(ctx context.Context, call api.Router_join) error

func (*Server) PubSub

func (r *Server) PubSub() Router

type Subscription

type Subscription casm.Iterator[[]byte]

Subscription is a stateful iterator over a stream of topic messages.

func (Subscription) Err

func (sub Subscription) Err() error

Err returns the first non-nil error encountered by the subscription. If there is no error, Err() returns nil.

func (Subscription) Next

func (sub Subscription) Next() []byte

Next blocks until the next message is received, and returns it. It returns nil when the subscription is canceled.

type Topic

type Topic api.Topic

Topic is the handle for a pubsub topic. It is used to publish to the topic, and to manage subscriptions.

func NewTopic

func NewTopic(s TopicServer) Topic

NewTopic returns a Joiner (a capability client) from a JoinServer interface. This is most commonly used in unit-testing.

func (Topic) AddRef

func (t Topic) AddRef() Topic

func (Topic) Name

func (t Topic) Name(ctx context.Context) (string, error)

Name returns the name of the pubsub topic. This is guaranteed never to change, so callers MAY cache results locally.

func (Topic) Publish

func (t Topic) Publish(ctx context.Context, b []byte) error

Publish a message asynchronously. The first error encountered will be returned by all subsequent calls to Publish().

func (Topic) Release

func (t Topic) Release()

func (Topic) Subscribe

func (t Topic) Subscribe(ctx context.Context) (Subscription, capnp.ReleaseFunc)

Subscribe to the topic. Callers MUST call the provided ReleaseFunc when finished with the subscription, or a resource leak will occur.

type TopicJoiner

type TopicJoiner interface {
	Join(string, ...pubsub.TopicOpt) (*pubsub.Topic, error)
}

TopicJoiner can join libp2p pubsub topics. It is a low- level interface provided to Router.

type TopicServer

type TopicServer interface {
	Name(context.Context, api.Topic_name) error
	Publish(context.Context, api.Topic_publish) error
	Subscribe(context.Context, api.Topic_subscribe) error
}

TopicServer is an interface that allows alternate server implementations for Topic. The default implementation is unexported. See NewTopic.