net

Documentation

Index

• type API
• type Event
• type EventHeader
• type Net
• type NewThreadOption
  • func WithLogKey(key crypto.Key) NewThreadOption
  • func WithNewThreadToken(t thread.Token) NewThreadOption
  • func WithThreadKey(key thread.Key) NewThreadOption
• type NewThreadOptions
• type Record
• type SubOption
  • func WithSubFilter(id thread.ID) SubOption
  • func WithSubToken(t thread.Token) SubOption
• type SubOptions
• type ThreadOption
  • func WithAPIToken(t Token) ThreadOption
  • func WithThreadToken(t thread.Token) ThreadOption
• type ThreadOptions
• type ThreadRecord
• type Token
  • func (t Token) Equal(b Token) bool

Types

type API

type API interface {
	io.Closer

	// GetHostID returns the host's peer id.
	GetHostID(ctx context.Context) (peer.ID, error)

	// GetToken returns a signed token representing an identity that can be used with other API methods, e.g.,
	// CreateThread, AddThread, etc.
	GetToken(ctx context.Context, identity thread.Identity) (thread.Token, error)

	// CreateThread creates and adds a new thread with id and opts.
	CreateThread(ctx context.Context, id thread.ID, opts ...NewThreadOption) (thread.Info, error)

	// AddThread adds an existing thread from a multiaddress and opts.
	AddThread(ctx context.Context, addr ma.Multiaddr, opts ...NewThreadOption) (thread.Info, error)

	// GetThread returns thread info by id.
	GetThread(ctx context.Context, id thread.ID, opts ...ThreadOption) (thread.Info, error)

	// PullThread requests new records from each known thread host.
	// This method is called internally on an interval as part of the orchestration protocol.
	// Calling it manually can be useful when new records are known to be available.
	PullThread(ctx context.Context, id thread.ID, opts ...ThreadOption) error

	// DeleteThread removes a thread by id and opts.
	DeleteThread(ctx context.Context, id thread.ID, opts ...ThreadOption) error

	// AddReplicator replicates a thread by id on a different host.
	// All logs and records are pushed to the new host.
	AddReplicator(ctx context.Context, id thread.ID, paddr ma.Multiaddr, opts ...ThreadOption) (peer.ID, error)

	// CreateRecord creates and adds a new record with body to a thread by id.
	CreateRecord(ctx context.Context, id thread.ID, body format.Node, opts ...ThreadOption) (ThreadRecord, error)

	// AddRecord add an existing record to a thread by id and lid.
	AddRecord(ctx context.Context, id thread.ID, lid peer.ID, rec Record, opts ...ThreadOption) error

	// GetRecord returns a record by thread id and cid.
	GetRecord(ctx context.Context, id thread.ID, rid cid.Cid, opts ...ThreadOption) (Record, error)

	// Subscribe returns a read-only channel that receives newly created / added thread records.
	// Cancelling the context effectively unsubscribes and releases the resources.
	Subscribe(ctx context.Context, opts ...SubOption) (<-chan ThreadRecord, error)
}

API is the network interface for thread orchestration.

type Event

type Event interface {
	format.Node

	// HeaderID returns the cid of the event header.
	HeaderID() cid.Cid

	// GetHeader loads and optionally decrypts the event header.
	// If no key is given, the header time and key methods will return an error.
	GetHeader(context.Context, format.DAGService, crypto.DecryptionKey) (EventHeader, error)

	// BodyID returns the cid of the event body.
	BodyID() cid.Cid

	// GetBody loads and optionally decrypts the event body.
	GetBody(context.Context, format.DAGService, crypto.DecryptionKey) (format.Node, error)
}

Event is the Block format used by threads

type EventHeader

type EventHeader interface {
	format.Node

	// Key returns a single-use decryption key for the event body.
	Key() (crypto.DecryptionKey, error)
}

EventHeader is the format of the event's header object

type Net

type Net interface {
	API

	// DAGService provides a DAG API to the network.
	format.DAGService

	// Host provides a network identity.
	Host() host.Host
}

Net wraps API with a DAGService and libp2p host.

type NewThreadOption

type NewThreadOption func(*NewThreadOptions)

NewThreadOption specifies new thread options.

func WithLogKey

func WithLogKey(key crypto.Key) NewThreadOption

WithLogKey is the public or private key used to write log records. If this is just a public key, the service itself won't be able to create records. In other words, all records must be pre-created and added with AddRecord. If no log key is provided, one will be created internally.

func WithNewThreadToken

func WithNewThreadToken(t thread.Token) NewThreadOption

WithNewThreadToken provides authorization for creating a new thread.

func WithThreadKey

func WithThreadKey(key thread.Key) NewThreadOption

WithThreadKey handles log encryption.

type NewThreadOptions

type NewThreadOptions struct {
	ThreadKey thread.Key
	LogKey    crypto.Key
	Token     thread.Token
}

NewThreadOptions defines options to be used when creating / adding a thread.

type Record

type Record interface {
	format.Node

	// BlockID returns the cid of the inner block.
	BlockID() cid.Cid

	// GetBlock loads the inner block.
	GetBlock(context.Context, format.DAGService) (format.Node, error)

	// PrevID returns the cid of the previous record.
	PrevID() cid.Cid

	// Sig returns a signature from the log key.
	Sig() []byte

	// PubKey of the identity used to author this record.
	PubKey() []byte

	// Verify returns a nil error if the node signature is valid.
	Verify(key crypto.PubKey) error
}

Record is the most basic component of a log.

type SubOption

type SubOption func(*SubOptions)

SubOption is a thread subscription option.

func WithSubFilter

func WithSubFilter(id thread.ID) SubOption

WithSubFilter restricts the subscription to a given thread. Use this option multiple times to subscribe to multiple threads.

func WithSubToken

func WithSubToken(t thread.Token) SubOption

WithSubToken provides authorization for a subscription.

type SubOptions

type SubOptions struct {
	ThreadIDs thread.IDSlice
	Token     thread.Token
}

SubOptions defines options for a thread subscription.

type ThreadOption

type ThreadOption func(*ThreadOptions)

ThreadOption specifies thread options.

func WithAPIToken

func WithAPIToken(t Token) ThreadOption

WithAPIToken provides additional authorization for interacting with a thread as an application. For example, this is used by a db.DB to ensure that only it can create records or delete the underlying thread.

func WithThreadToken

func WithThreadToken(t thread.Token) ThreadOption

WithThreadToken provides authorization for interacting with a thread.

type ThreadOptions

type ThreadOptions struct {
	Token    thread.Token
	APIToken Token
}

ThreadOptions defines options for interacting with a thread.

type ThreadRecord

type ThreadRecord interface {
	// Value returns the underlying record.
	Value() Record

	// ThreadID returns the record's thread ID.
	ThreadID() thread.ID

	// LogID returns the record's log ID.
	LogID() peer.ID
}

ThreadRecord wraps Record within a thread and log context.

type Token

type Token []byte

Token is used to restrict network APIs to a single app.App. In other words, a net token protects against writes and deletes which are external to an app.

func (Token) Equal

func (t Token) Equal(b Token) bool

Equal returns whether or not the token is equal to the given value.