Documentation
¶
Index ¶
- func IsLive(healthData map[string]Data, owner string, ttl time.Duration, now time.Time) bool
- func Verify(bucket, key string, d SignedData) error
- type Block
- type Blockchain
- type BucketPolicy
- type Data
- type DataString
- type DiskStore
- type ExpiryKind
- type Ledger
- func (l *Ledger) Add(b string, s map[string]interface{})
- func (l *Ledger) Announce(ctx context.Context, d time.Duration, async func())
- func (l *Ledger) AnnounceDeleteBucket(ctx context.Context, interval, timeout time.Duration, bucket string)
- func (l *Ledger) AnnounceDeleteBucketKey(ctx context.Context, interval, timeout time.Duration, bucket, key string)
- func (l *Ledger) AnnounceUpdate(ctx context.Context, interval time.Duration, bucket, key string, ...)
- func (l *Ledger) CurrentData() map[string]map[string]Data
- func (l *Ledger) CurrentStorage() map[string]map[string]SignedData
- func (l *Ledger) Delete(b string, k string)
- func (l *Ledger) DeleteBucket(b string)
- func (l *Ledger) Exists(b string, f func(Data) bool) (exists bool)
- func (l *Ledger) GetKey(b, s string) (value Data, exists bool)
- func (l *Ledger) Index() int
- func (l *Ledger) IsOwnerLive(owner string) bool
- func (l *Ledger) LastBlock() Block
- func (l *Ledger) LivenessBuckets() []string
- func (l *Ledger) OwnershipEnabled() bool
- func (l *Ledger) Persist(ctx context.Context, interval, timeout time.Duration, bucket, key string, ...)
- func (l *Ledger) Reap(tombstoneTTL time.Duration)
- func (l *Ledger) SetOwnership(mode OwnershipMode, r Registry, ttl time.Duration)
- func (l *Ledger) SetSigner(s Signer)
- func (l *Ledger) String() string
- func (l *Ledger) Syncronizer(ctx context.Context, t time.Duration)
- func (l *Ledger) Update(f *Ledger, h *hub.Message, c chan *hub.Message) (err error)
- type LedgerOption
- func WithClock(f func() time.Time) LedgerOption
- func WithEnforcedOwnership(r Registry, ttl time.Duration) LedgerOption
- func WithOwnership(mode OwnershipMode, r Registry, ttl time.Duration) LedgerOption
- func WithSigner(s Signer) LedgerOption
- func WithViolationLogger(f func(string, ...interface{})) LedgerOption
- type MemoryStore
- type OwnershipMode
- type Registry
- type SignedData
- type Signer
- type Store
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsLive ¶ added in v0.35.0
IsLive reports whether owner has a heartbeat in healthData (a map of peer.ID -> RFC3339 timestamp, as written by the alive service) that is newer than ttl relative to now.
func Verify ¶ added in v0.35.0
func Verify(bucket, key string, d SignedData) error
Verify checks that an entry was signed by the peer it claims as Owner. The verifying public key is recovered directly from the Owner peer.ID (libp2p Ed25519 identities embed it), so no key distribution is needed.
Types ¶
type Block ¶
type Block struct {
Index int
Timestamp string
Storage map[string]map[string]SignedData
Hash string
PrevHash string
}
Block represents each 'item' in the blockchain
type BucketPolicy ¶ added in v0.35.0
type BucketPolicy struct {
Owned bool // signed + owner-enforced?
OwnerOf func(key string, v Data) string // who owns this entry
Expiry ExpiryKind
TTL time.Duration // only meaningful for Absolute
Reclaimable bool // may a non-owner claim the key after expiry?
}
BucketPolicy is the single source of truth for whether a bucket is authenticated and how its entries expire. Adding a new authenticated bucket is a one-line registry entry.
type DataString ¶ added in v0.2.0
type DataString string
type DiskStore ¶ added in v0.3.0
type DiskStore struct {
// contains filtered or unexported fields
}
func NewDiskStore ¶ added in v0.3.0
type ExpiryKind ¶ added in v0.35.0
type ExpiryKind int
ExpiryKind selects how a bucket's entries are aged out. See docs/design/authenticated-ledger.md.
const ( // NoExpiry: entries live forever (default for unregistered/legacy buckets). NoExpiry ExpiryKind = iota // Liveness: an entry is alive iff its owner's heartbeat is fresh. Liveness // Absolute: an entry expires TTL after its own signed UpdatedAt. Absolute )
type Ledger ¶
func New ¶
func New(w io.Writer, s Store, opts ...LedgerOption) *Ledger
New returns a new ledger which writes to the writer
func (*Ledger) Announce ¶ added in v0.1.0
Announce keeps updating async data to the blockchain. Sends a broadcast at the specified interval by making sure the async retrieved value is written to the blockchain
func (*Ledger) AnnounceDeleteBucket ¶ added in v0.2.5
func (l *Ledger) AnnounceDeleteBucket(ctx context.Context, interval, timeout time.Duration, bucket string)
AnnounceDeleteBucket Announce a deletion of a bucket. It stops when the bucket is deleted It takes an interval time and a max timeout. It is best effort, and the timeout is necessary, or we might flood network with requests if more writers are attempting to write to the same resource
func (*Ledger) AnnounceDeleteBucketKey ¶ added in v0.2.5
func (l *Ledger) AnnounceDeleteBucketKey(ctx context.Context, interval, timeout time.Duration, bucket, key string)
AnnounceDeleteBucketKey Announce a deletion of a key from a bucket. It stops when the key is deleted
func (*Ledger) AnnounceUpdate ¶ added in v0.8.4
func (l *Ledger) AnnounceUpdate(ctx context.Context, interval time.Duration, bucket, key string, value interface{})
AnnounceUpdate Keeps announcing something into the blockchain if state is differing
func (*Ledger) CurrentData ¶ added in v0.1.0
CurrentData returns the current ledger data (locking). Tombstoned entries are hidden and only the inner Value is exposed, so existing readers are unchanged.
func (*Ledger) CurrentStorage ¶ added in v0.35.0
func (l *Ledger) CurrentStorage() map[string]map[string]SignedData
CurrentStorage returns a deep copy of the raw signed storage (locking). Used by the reaper, which needs owner/version metadata.
func (*Ledger) Delete ¶ added in v0.2.4
Delete data from the ledger. With a signer this writes a signed tombstone so the deletion survives gossip reconciliation; without one it removes the key (legacy behaviour).
func (*Ledger) DeleteBucket ¶ added in v0.2.4
DeleteBucket deletes a bucket from the ledger.
func (*Ledger) Exists ¶ added in v0.1.0
Exists returns true if there is one element with a matching value
func (*Ledger) IsOwnerLive ¶ added in v0.35.0
IsOwnerLive reports whether owner currently has a fresh heartbeat. When ownership is disabled it always returns true, so existing readers behave exactly as before; under observe/enforce it lets readers skip entries whose owner has gone inactive without waiting for the reaper to tombstone them.
func (*Ledger) LivenessBuckets ¶ added in v0.35.0
LivenessBuckets returns the buckets whose entries expire with owner liveness.
func (*Ledger) OwnershipEnabled ¶ added in v0.35.0
OwnershipEnabled reports whether the ledger is running the authenticated merge (observe or enforce).
func (*Ledger) Persist ¶
func (l *Ledger) Persist(ctx context.Context, interval, timeout time.Duration, bucket, key string, value interface{})
Persist Keeps announcing something into the blockchain until it is reconciled
func (*Ledger) Reap ¶ added in v0.35.0
Reap bounds ledger growth from inactive nodes. For every Liveness-managed bucket it signs a tombstone over each entry whose owner is no longer live, and it physically prunes tombstones older than tombstoneTTL. It is a no-op unless ownership is enabled and a signer is set; callers should run it only on the elected leader to avoid redundant writes.
See docs/design/authenticated-ledger.md (section 9).
func (*Ledger) SetOwnership ¶ added in v0.35.0
func (l *Ledger) SetOwnership(mode OwnershipMode, r Registry, ttl time.Duration)
SetOwnership configures the merge mode/registry/ttl at runtime (called during node startup before the message hub is running).
func (*Ledger) SetSigner ¶ added in v0.35.0
SetSigner installs the signing key (called once the host identity exists).
func (*Ledger) Syncronizer ¶
Syncronizer starts a goroutine which writes the blockchain to the periodically
type LedgerOption ¶ added in v0.35.0
type LedgerOption func(*Ledger)
LedgerOption configures optional ledger behaviour.
func WithClock ¶ added in v0.35.0
func WithClock(f func() time.Time) LedgerOption
WithClock overrides the time source (tests).
func WithEnforcedOwnership ¶ added in v0.35.0
func WithEnforcedOwnership(r Registry, ttl time.Duration) LedgerOption
WithEnforcedOwnership is shorthand for WithOwnership(OwnershipEnforce, ...).
func WithOwnership ¶ added in v0.35.0
func WithOwnership(mode OwnershipMode, r Registry, ttl time.Duration) LedgerOption
WithOwnership switches Update to the per-key authorized merge using the given policy registry, liveness window and mode (observe = log-only, enforce = drop).
func WithSigner ¶ added in v0.35.0
func WithSigner(s Signer) LedgerOption
WithSigner makes the ledger sign every write with s. Without enforcement this only annotates entries (so a network can pre-sign before flipping enforcement on); with enforcement it is required for the local node to author entries.
func WithViolationLogger ¶ added in v0.35.0
func WithViolationLogger(f func(string, ...interface{})) LedgerOption
WithViolationLogger sets the sink for ownership-violation warnings.
type MemoryStore ¶ added in v0.3.0
func (*MemoryStore) Add ¶ added in v0.3.0
func (m *MemoryStore) Add(b Block)
func (*MemoryStore) Last ¶ added in v0.3.0
func (m *MemoryStore) Last() Block
func (*MemoryStore) Len ¶ added in v0.3.0
func (m *MemoryStore) Len() int
type OwnershipMode ¶ added in v0.35.0
type OwnershipMode int
OwnershipMode selects how the ledger handles authenticated buckets.
const ( // OwnershipOff: legacy height-wins replace; entries unsigned (default). OwnershipOff OwnershipMode = iota // OwnershipObserve: run the authorized merge but accept-and-warn on // violations instead of dropping (safe rollout / observation). OwnershipObserve // OwnershipEnforce: run the authorized merge and drop invalid writes. OwnershipEnforce )
type Registry ¶ added in v0.35.0
type Registry map[string]BucketPolicy
Registry maps bucket name -> policy. The zero BucketPolicy (returned for any unregistered bucket) is unowned/open and never expires, preserving legacy behaviour for buckets we have not opted in.
func DefaultRegistry ¶ added in v0.35.0
DefaultRegistry is the built-in policy set. ttl is the liveness window (reused as the Absolute TTL for the heartbeat bucket itself).
func (Registry) Policy ¶ added in v0.35.0
func (r Registry) Policy(bucket string) BucketPolicy
Policy returns the policy for a bucket, or the open/legacy zero value.
type SignedData ¶ added in v0.35.0
type SignedData struct {
Value Data // original JSON payload
Owner string // peer.ID (base58) of the author
Version uint64 // monotonic per (bucket,key); bumps only when Value changes
UpdatedAt int64 // unix seconds, signed; drives TTL/lease renewal
Deleted bool // signed tombstone marker
Sig []byte // signature over canonical(bucket,key,...)
}
SignedData is a ledger entry authenticated by its author. The Value is the original JSON payload (readers still call Value.Unmarshal); the remaining fields bind that value to the owning peer and a monotonic version so that only the owner can update it and an older value cannot be replayed over a newer one. See docs/design/authenticated-ledger.md.
func (SignedData) MarshalJSON ¶ added in v0.35.0
func (d SignedData) MarshalJSON() ([]byte, error)
MarshalJSON keeps unsigned entries on the legacy wire format (a bare JSON value), so nodes that predate authentication can still decode them. Signed entries are encoded as the full object.
func (*SignedData) UnmarshalJSON ¶ added in v0.35.0
func (d *SignedData) UnmarshalJSON(b []byte) error
UnmarshalJSON accepts either the legacy bare value or the full signed object.