repo

Documentation

Overview

Implementation of atproto repository and sync APIs, built on the MST data structure.

The current package works for processing a sync firehose, including validation of "inductive firehose". It does not yet work for implementing a repository host (PDS).

Index

• Constants
• Variables
• func CheckOp(tree *mst.Tree, op *Operation) error
• func InvertOp(tree *mst.Tree, op *Operation) error
• func LoadFromCAR(ctx context.Context, r io.Reader) (*Commit, *Repo, error)
• func VerifyCommitSignature(ctx context.Context, dir identity.Directory, ...) error
• type Commit
  • func (t *Commit) MarshalCBOR(w io.Writer) error
  • func (c *Commit) Sign(privkey crypto.PrivateKey) error
  • func (t *Commit) UnmarshalCBOR(r io.Reader) (err error)
  • func (c *Commit) UnsignedBytes() ([]byte, error)
  • func (c *Commit) VerifySignature(pubkey crypto.PublicKey) error
  • func (c *Commit) VerifyStructure() error
• type Operation
  • func ApplyOp(tree *mst.Tree, path string, val *cid.Cid) (*Operation, error)
  • func NormalizeOps(list []Operation) ([]Operation, error)
  • func (op *Operation) IsCreate() bool
  • func (op *Operation) IsDelete() bool
  • func (op *Operation) IsUpdate() bool
• type Repo
  • func NewEmptyRepo(did syntax.DID) Repo
  • func VerifyCommitMessage(ctx context.Context, msg *comatproto.SyncSubscribeRepos_Commit) (*Repo, error)
  • func (repo *Repo) Commit() (*Commit, error)
  • func (repo *Repo) GetRecordBytes(ctx context.Context, collection syntax.NSID, rkey syntax.RecordKey) ([]byte, error)
  • func (repo *Repo) GetRecordCID(ctx context.Context, collection syntax.NSID, rkey syntax.RecordKey) (*cid.Cid, error)

Constants

const ATPROTO_REPO_VERSION int64 = 3

Version of the repo data format implemented in this package

Variables

var ErrNotFound = errors.New("record not found in repository")

Functions

func CheckOp

func CheckOp(tree *mst.Tree, op *Operation) error

Does a simple "forwards" (not inversion) check of operation

func InvertOp

func InvertOp(tree *mst.Tree, op *Operation) error

Applies the inversion of the `op` to the `tree`. This mutates the tree.

func LoadFromCAR

func LoadFromCAR(ctx context.Context, r io.Reader) (*Commit, *Repo, error)

func VerifyCommitSignature

func VerifyCommitSignature(ctx context.Context, dir identity.Directory, msg *comatproto.SyncSubscribeRepos_Commit) error

temporary/experimental code showing how to verify a commit signature from firehose

TODO: in real implementation, will want to merge this code with `VerifyCommitMessage` above, and have it hanging off some service struct with a configured `identity.Directory`

Types

type Commit

type Commit struct {
	DID     string   `json:"did" cborgen:"did"`
	Version int64    `json:"version" cborgen:"version"` // currently: 3
	Prev    *cid.Cid `json:"prev" cborgen:"prev"`       // NOTE: omitempty would break signature verification for repo v3
	Data    cid.Cid  `json:"data" cborgen:"data"`
	Sig     []byte   `json:"sig,omitempty" cborgen:"sig,omitempty"`
	Rev     string   `json:"rev,omitempty" cborgen:"rev,omitempty"`
}

atproto repo commit object as a struct type. Can be used for direct CBOR or JSON serialization.

func (*Commit) MarshalCBOR

func (t *Commit) MarshalCBOR(w io.Writer) error

func (*Commit) Sign

func (c *Commit) Sign(privkey crypto.PrivateKey) error

Signs the commit, storing the signature in the `Sig` field

func (*Commit) UnmarshalCBOR

func (t *Commit) UnmarshalCBOR(r io.Reader) (err error)

func (*Commit) UnsignedBytes

func (c *Commit) UnsignedBytes() ([]byte, error)

Encodes the commit object as DAG-CBOR, without the signature field. Used for signing or validating signatures.

func (*Commit) VerifySignature

func (c *Commit) VerifySignature(pubkey crypto.PublicKey) error

Verifies `Sig` field using the provided key. Returns `nil` if signature is valid.

func (*Commit) VerifyStructure

func (c *Commit) VerifyStructure() error

does basic checks that field values and syntax are correct

type Operation

type Operation struct {
	// key of the record, eg, '{collection}/{record-key}'
	Path string
	// the new record CID value (or nil if this is a deletion)
	Value *cid.Cid
	// the previous record CID value (or nil if this is a creation)
	Prev *cid.Cid
}

Metadata about update to a single record (key) in the repo.

Used as an abstraction for creating or validating "commit diffs" (eg, `#commit` firehose events)

func ApplyOp

func ApplyOp(tree *mst.Tree, path string, val *cid.Cid) (*Operation, error)

Mutates the tree, returning a full `Operation`

func NormalizeOps

func NormalizeOps(list []Operation) ([]Operation, error)

re-orders operation list, and checks for duplicates

func (*Operation) IsCreate

func (op *Operation) IsCreate() bool

func (*Operation) IsDelete

func (op *Operation) IsDelete() bool

func (*Operation) IsUpdate

func (op *Operation) IsUpdate() bool

type Repo

type Repo struct {
	DID   syntax.DID
	Clock *syntax.TIDClock

	RecordStore blockstore.Blockstore
	MST         mst.Tree
}

High-level wrapper struct for an atproto repository.

func NewEmptyRepo

func NewEmptyRepo(did syntax.DID) Repo

func VerifyCommitMessage

func VerifyCommitMessage(ctx context.Context, msg *comatproto.SyncSubscribeRepos_Commit) (*Repo, error)

temporary/experimental method to parse and verify a firehose commit message.

TODO: move to a separate 'sync' package? break up in to smaller components?

func (*Repo) Commit

func (repo *Repo) Commit() (*Commit, error)

Snapshots the current state of the repository, resulting in a new (unsigned) `Commit` struct.

func (*Repo) GetRecordBytes

func (repo *Repo) GetRecordBytes(ctx context.Context, collection syntax.NSID, rkey syntax.RecordKey) ([]byte, error)

func (*Repo) GetRecordCID

func (repo *Repo) GetRecordCID(ctx context.Context, collection syntax.NSID, rkey syntax.RecordKey) (*cid.Cid, error)