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.
	GetToken(ctx context.Context, identity thread.Identity) (thread.Token, error)

	// CreateThread with credentials.
	CreateThread(ctx context.Context, id thread.ID, opts ...NewThreadOption) (thread.Info, error)

	// AddThread with credentials from a multiaddress.
	AddThread(ctx context.Context, addr ma.Multiaddr, opts ...NewThreadOption) (thread.Info, error)

	// GetThread with credentials.
	GetThread(ctx context.Context, id thread.ID, opts ...ThreadOption) (thread.Info, error)

	// PullThread for new records.
	// Logs owned by this host are traversed locally.
	// Remotely addressed logs are pulled from the network.
	// Is thread-safe.
	PullThread(ctx context.Context, id thread.ID, opts ...ThreadOption) error

	// DeleteThread with credentials.
	DeleteThread(ctx context.Context, id thread.ID, opts ...ThreadOption) error

	// AddReplicator with credentials.
	// The thread service key and all records will be pushed to paddr.
	AddReplicator(ctx context.Context, id thread.ID, paddr ma.Multiaddr, opts ...ThreadOption) (peer.ID, error)

	// CreateRecord with credentials and body.
	// The resulting record will have an author signature by the thread host.
	// Use AddRecord to add a record from a different author.
	CreateRecord(ctx context.Context, id thread.ID, body format.Node, opts ...ThreadOption) (ThreadRecord, error)

	// AddRecord to the given log.
	AddRecord(ctx context.Context, id thread.ID, lid peer.ID, rec Record, opts ...ThreadOption) error

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

	// Subscribe returns a read-only channel of records.
	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.