pubsub

Documentation

Index

• type JoinServer
• type MethodJoin
• type MethodName
• type MethodPublish
• type MethodSubscribe
• 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 MethodJoin) error
  • func (r *Server) PubSub() Router
• type Stream
  • func (s Stream) Close() error
  • func (s Stream) Publish(msg []byte) error
• 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) NewStream(ctx context.Context) Stream
  • func (t Topic) Publish(ctx context.Context, b []byte) error
  • func (t Topic) PublishAsync(ctx context.Context, b []byte) (casm.Future, capnp.ReleaseFunc)
  • func (t Topic) Release()
  • func (t Topic) Subscribe(ctx context.Context) (Subscription, capnp.ReleaseFunc)
• type TopicJoiner
• type TopicServer
• type Tracer
  • func (t Tracer) AddPeer(id peer.ID, proto protocol.ID)
  • func (t Tracer) DeliverMessage(*pubsub.Message)
  • func (t Tracer) DropRPC(r *pubsub.RPC, id peer.ID)
  • func (t Tracer) DuplicateMessage(*pubsub.Message)
  • func (t Tracer) Graft(id peer.ID, topic string)
  • func (t Tracer) Join(topic string)
  • func (t Tracer) Leave(topic string)
  • func (t Tracer) Prune(id peer.ID, topic string)
  • func (t Tracer) RecvRPC(*pubsub.RPC)
  • func (t Tracer) RejectMessage(m *pubsub.Message, reason string)
  • func (t Tracer) RemovePeer(id peer.ID)
  • func (t Tracer) SendRPC(*pubsub.RPC, peer.ID)
  • func (t Tracer) ThrottlePeer(id peer.ID)
  • func (t Tracer) UndeliverableMessage(m *pubsub.Message)
  • func (t Tracer) ValidateMessage(*pubsub.Message)

Types

type JoinServer

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

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

type MethodJoin

type MethodJoin = api.Router_join

MethodJoin is the server-side method parameter for JoinServer's Join method. See: NewJoiner.

type MethodName

type MethodName = api.Topic_name

MethodName is the server-side method parameter for TopicServer's Join method. See: NewJoiner.

type MethodPublish

type MethodPublish = api.Topic_publish

MethodPublish is the server-side method parameter for TopicServer's Join method. See: NewJoiner.

type MethodSubscribe

type MethodSubscribe = api.Topic_subscribe

MethodSubscribe is the server-side method parameter for TopicServer's Join method. 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 MethodJoin) error

func (*Server) PubSub

func (r *Server) PubSub() Router

type Stream

type Stream struct {
	// contains filtered or unexported fields
}

func (Stream) Close

func (s Stream) Close() error

func (Stream) Publish

func (s Stream) Publish(msg []byte) error

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) NewStream

func (t Topic) NewStream(ctx context.Context) Stream

NewStream provides an interface for publishing large volumes of data through a flow-controlled channel. This will override the existing FlowLimiter.

func (Topic) Publish

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

Publish a message synchronously. This is a convenience function that is equivalent to calling PublishAsync() and blocking on the future it returns. The drawback is that each call will block until it completes a round-trip. It is safe to call Publish concurrently.

func (Topic) PublishAsync

func (t Topic) PublishAsync(ctx context.Context, b []byte) (casm.Future, capnp.ReleaseFunc)

PublishAsync submits a message for broadcast over the topic. Unlike Publish, it returns a future. This is useful when applications must publish a large volume of messages, and callers do not wish to spawn a goroutine for each call. PublishAsync is nevertheless thread-safe.

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, MethodName) error
	Publish(context.Context, MethodPublish) error
	Subscribe(context.Context, MethodSubscribe) error
}

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

type Tracer

type Tracer struct {
	Log     log.Logger
	Metrics interface {
		Incr(string)
		Decr(string)
	}
}

func (Tracer) AddPeer

func (t Tracer) AddPeer(id peer.ID, proto protocol.ID)

AddPeer is invoked when a new peer is added.

func (Tracer) DeliverMessage

func (t Tracer) DeliverMessage(*pubsub.Message)

DeliverMessage is invoked when a message is delivered

func (Tracer) DropRPC

func (t Tracer) DropRPC(r *pubsub.RPC, id peer.ID)

DropRPC is invoked when an outbound RPC is dropped, typically because of a queue full.

func (Tracer) DuplicateMessage

func (t Tracer) DuplicateMessage(*pubsub.Message)

DuplicateMessage is invoked when a duplicate message is dropped.

func (Tracer) Graft

func (t Tracer) Graft(id peer.ID, topic string)

Graft is invoked when a new peer is grafted on the mesh (gossipsub)

func (Tracer) Join

func (t Tracer) Join(topic string)

Join is invoked when a new topic is joined

func (Tracer) Leave

func (t Tracer) Leave(topic string)

Leave is invoked when a topic is abandoned

func (Tracer) Prune

func (t Tracer) Prune(id peer.ID, topic string)

Prune is invoked when a peer is pruned from the message (gossipsub)

func (Tracer) RecvRPC

func (t Tracer) RecvRPC(*pubsub.RPC)

RecvRPC is invoked when an incoming RPC is received.

func (Tracer) RejectMessage

func (t Tracer) RejectMessage(m *pubsub.Message, reason string)

RejectMessage is invoked when a message is Rejected or Ignored. The reason argument can be one of the named strings Reject*.

func (Tracer) RemovePeer

func (t Tracer) RemovePeer(id peer.ID)

RemovePeer is invoked when a peer is removed.

func (Tracer) SendRPC

func (t Tracer) SendRPC(*pubsub.RPC, peer.ID)

SendRPC is invoked when a RPC is sent.

func (Tracer) ThrottlePeer

func (t Tracer) ThrottlePeer(id peer.ID)

ThrottlePeer is invoked when a peer is throttled by the peer gater.

func (Tracer) UndeliverableMessage

func (t Tracer) UndeliverableMessage(m *pubsub.Message)

UndeliverableMessage is invoked when the consumer of Subscribe is not reading messages fast enough and the pressure release mechanism trigger, dropping messages.

func (Tracer) ValidateMessage

func (t Tracer) ValidateMessage(*pubsub.Message)

ValidateMessage is invoked when a message first enters the validation pipeline.