statedb

package
v0.10.0-dev.49 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 9, 2026 License: AGPL-3.0 Imports: 31 Imported by: 0

Documentation

Overview

Package statedb is subflux's one store: the core namespace of a bolttable file holding source facts, ownership, coverage, locks, the write protocol's rows, history, work, jobs and credentials (the storage spec's design sections 3 to 10).

Index

Constants

View Source
const (
	// MarkHistory: a download attempt was recorded.
	MarkHistory = "history"
	// MarkAccounts: a user, invite, session, passkey or API key changed.
	MarkAccounts = "accounts"
	// MarkUnidentified: an unidentified sighting appeared, changed or went.
	MarkUnidentified = "unidentified"
	// MarkConfig: the activation changed; every reader re-reads in full.
	MarkConfig = "config"
)

The marks a Delta carries. Every writer and BeforeCommit sets a mark only through these, so a rename is a compile error at every reader.

Variables

View Source
var (
	ErrSourceInactive = errors.New("statedb: source is not in the activation")
	ErrPassUnknown    = errors.New("statedb: not the source's open pass")
)

The refusals of a pass call.

View Source
var Codes = []struct {
	Err  error
	Code string
}{
	{ErrCursorInvalid, "cursor_invalid"},
	{ErrNotLockable, "not_lockable"},
}

Codes is every sentinel the store's reads and SetLock return, with the code api answers for it. The pass calls' ErrPassUnknown and ErrSourceInactive and Open's ErrLocked stay outside, since no endpoint makes those calls. The element type is unnamed, so statedb never imports api's wirespec.

View Source
var ErrCursorInvalid = errors.New("statedb: cursor names no position of this list")

ErrCursorInvalid refuses a cursor that does not decode to a position of the list and scope it is given to.

View Source
var ErrLocked = errors.New("statedb: the store is held by another process")

ErrLocked is Open's failure while another process holds the store.

View Source
var ErrNotLockable = errors.New("statedb: nothing to lock")

ErrNotLockable is SetLock's refusal: an unknown or ownerless instance, a pair none of its items configures, or locking a pair none can serve.

Functions

This section is empty.

Types

type AccountStore

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

AccountStore is v7's account.Store over the store's auth namespace (design section 9). Every single-call write and every Update runs through db.Batch, so concurrent sign-ins share one commit; reads run in one View.

func (*AccountStore) APIKeyByHash

func (a *AccountStore) APIKeyByHash(ctx context.Context, hash access.Hash) (*access.Key, bool, error)

APIKeyByHash reads the key holding hash, its use stamp merged.

func (*AccountStore) AuthFailure

AuthFailure reads one failure record.

func (*AccountStore) CleanupExpiredOneTimeTokens

func (a *AccountStore) CleanupExpiredOneTimeTokens(ctx context.Context, now time.Time) (int64, error)

CleanupExpiredOneTimeTokens deletes every token whose ExpiresAt is not after now and returns how many it deleted.

func (*AccountStore) CleanupExpiredSessions

func (a *AccountStore) CleanupExpiredSessions(ctx context.Context, now time.Time, timeouts access.SessionTimeouts, limit int) ([]access.SessionRef, error)

CleanupExpiredSessions deletes, in one db.Batch, at most limit of the sessions access.ValidateSession refuses at now, in key order, and returns the ref of each it deleted (rule 14).

func (*AccountStore) ConsumeOneTimeToken

func (a *AccountStore) ConsumeOneTimeToken(ctx context.Context, hash access.Hash, now time.Time) (access.OneTimeToken, bool, error)

ConsumeOneTimeToken deletes hash's token and answers it when live at now (rule 7).

func (*AccountStore) CreateAPIKey

func (a *AccountStore) CreateAPIKey(ctx context.Context, key *access.Key) error

CreateAPIKey assigns key.ID and appends it to key.LineageIDs once the key is stored.

func (*AccountStore) CreateInitialUser

func (a *AccountStore) CreateInitialUser(ctx context.Context, user *access.User) error

CreateInitialUser creates user while no user exists, else account.ErrSetupComplete.

func (*AccountStore) CreateKeyAttribution

func (a *AccountStore) CreateKeyAttribution(ctx context.Context, rec *access.KeyAttribution) error

CreateKeyAttribution assigns a.ID once the record is stored.

func (*AccountStore) CreateOneTimeToken

func (a *AccountStore) CreateOneTimeToken(ctx context.Context, tok access.OneTimeToken) error

CreateOneTimeToken stores tok, refusing a stored token of its hash.

func (*AccountStore) CreatePasskey

func (a *AccountStore) CreatePasskey(ctx context.Context, cred *access.PasskeyCredential) error

CreatePasskey assigns cred.ID once the credential is stored.

func (*AccountStore) CreateSession

func (a *AccountStore) CreateSession(ctx context.Context, sess *access.Session) error

CreateSession stores sess with its activity.

func (*AccountStore) CreateUser

func (a *AccountStore) CreateUser(ctx context.Context, user *access.User) error

CreateUser assigns user.ID once the user is stored.

func (*AccountStore) DeleteAPIKey

func (a *AccountStore) DeleteAPIKey(ctx context.Context, ref access.KeyRef) error

DeleteAPIKey deletes ref's key, or answers account.ErrNotFound.

func (*AccountStore) DeleteAuthFailures

func (a *AccountStore) DeleteAuthFailures(ctx context.Context, name string, methods []access.Method) error

DeleteAuthFailures deletes name's records of each listed method in both trust contexts.

func (*AccountStore) DeleteOneTimeTokens

func (a *AccountStore) DeleteOneTimeTokens(ctx context.Context, purpose access.TokenPurpose, subject int64) (int, error)

DeleteOneTimeTokens deletes subject's tokens of purpose and returns how many.

func (*AccountStore) DeleteOneTimeTokensIssuedBy

func (a *AccountStore) DeleteOneTimeTokensIssuedBy(ctx context.Context, keyIDs []int64) (int, error)

DeleteOneTimeTokensIssuedBy deletes the tokens a listed key issued and returns how many.

func (*AccountStore) DeletePasskey

func (a *AccountStore) DeletePasskey(ctx context.Context, ref access.PasskeyRef) error

DeletePasskey deletes ref's passkey, or answers account.ErrNotFound.

func (*AccountStore) DeleteSession

func (a *AccountStore) DeleteSession(ctx context.Context, ref access.SessionRef) error

DeleteSession deletes ref's session, or answers account.ErrNotFound.

func (*AccountStore) DeleteSessionByHash

func (a *AccountStore) DeleteSessionByHash(ctx context.Context, tokenHash access.Hash) error

DeleteSessionByHash deletes the session holding tokenHash, if any.

func (*AccountStore) DeleteUser

func (a *AccountStore) DeleteUser(ctx context.Context, id int64) error

DeleteUser deletes the user with its cascades in one write, or answers account.ErrNotFound.

func (*AccountStore) DeleteUserAPIKeys

func (a *AccountStore) DeleteUserAPIKeys(ctx context.Context, userID int64) ([]int64, error)

DeleteUserAPIKeys deletes userID's keys and returns their IDs.

func (*AccountStore) DeleteUserPasskeys

func (a *AccountStore) DeleteUserPasskeys(ctx context.Context, userID int64) ([]int64, error)

DeleteUserPasskeys deletes userID's passkeys and returns their IDs.

func (*AccountStore) DeleteUserSessions

func (a *AccountStore) DeleteUserSessions(ctx context.Context, userID int64, exceptID string) ([]string, error)

DeleteUserSessions deletes userID's sessions but exceptID and returns their IDs.

func (*AccountStore) ListAPIKeys

func (a *AccountStore) ListAPIKeys(ctx context.Context) ([]access.Key, error)

ListAPIKeys lists every user's keys in ID order.

func (*AccountStore) ListAPIKeysByUserID

func (a *AccountStore) ListAPIKeysByUserID(ctx context.Context, userID int64) ([]access.Key, error)

ListAPIKeysByUserID lists userID's keys in ID order.

func (*AccountStore) ListKeyAttributions

func (a *AccountStore) ListKeyAttributions(ctx context.Context) ([]access.KeyAttribution, error)

ListKeyAttributions returns every record in ascending ID order.

func (*AccountStore) ListUsers

func (a *AccountStore) ListUsers(ctx context.Context) ([]access.User, error)

ListUsers lists every user in ID order.

func (*AccountStore) LiveOneTimeTokens

func (a *AccountStore) LiveOneTimeTokens(ctx context.Context, purposes []access.TokenPurpose, now time.Time) ([]access.OneTimeToken, error)

LiveOneTimeTokens lists, in one View, every token of a listed purpose whose ExpiresAt is after now.

func (*AccountStore) OneTimeTokenByHash

func (a *AccountStore) OneTimeTokenByHash(ctx context.Context, hash access.Hash) (access.OneTimeToken, bool, error)

OneTimeTokenByHash reads the token stored under hash.

func (*AccountStore) PasskeysByUserID

func (a *AccountStore) PasskeysByUserID(ctx context.Context, userID int64) ([]access.PasskeyCredential, error)

PasskeysByUserID lists userID's passkeys, their login stamps merged.

func (*AccountStore) PruneAuthFailures

func (a *AccountStore) PruneAuthFailures(ctx context.Context, keep []string) (int64, error)

PruneAuthFailures deletes every record whose Name is not in keep and returns how many.

func (*AccountStore) PutAuthFailure

func (a *AccountStore) PutAuthFailure(ctx context.Context, f account.FailureCount) error

PutAuthFailure upserts f's record.

func (*AccountStore) RenamePasskey

func (a *AccountStore) RenamePasskey(ctx context.Context, ref access.PasskeyRef, name string) error

RenamePasskey renames ref's passkey, or answers account.ErrNotFound.

func (*AccountStore) RotateSession

func (a *AccountStore) RotateSession(ctx context.Context, rot account.Rotation) error

RotateSession writes rot.Next over the session it names (rule 7).

func (*AccountStore) SessionByHash

func (a *AccountStore) SessionByHash(ctx context.Context, tokenHash access.Hash) (*access.Session, bool, error)

SessionByHash reads the session holding tokenHash, its activity merged.

func (*AccountStore) SessionsByUserID

func (a *AccountStore) SessionsByUserID(ctx context.Context, userID int64) ([]access.Session, error)

SessionsByUserID lists userID's sessions, their activity merged.

func (*AccountStore) TouchAPIKey

func (a *AccountStore) TouchAPIKey(ctx context.Context, keyID int64, at time.Time) error

TouchAPIKey raises keyID's LastUsedAt to at when at is later (rule 21).

func (*AccountStore) UnreportedLocks

func (a *AccountStore) UnreportedLocks(ctx context.Context) ([]account.FailureCount, error)

UnreportedLocks lists the records with Unreported set.

func (*AccountStore) Update

func (a *AccountStore) Update(ctx context.Context, fn func(tx account.Tx) error) error

Update runs fn in one db.Batch transaction. db.Batch may run fn more than once; only its last run's writes commit, and only the committed run's assignments into the records fn passes to tx stay (rule 5).

func (*AccountStore) UpdatePasskeyAfterLogin

func (a *AccountStore) UpdatePasskeyAfterLogin(ctx context.Context, userID int64, credID []byte, upd access.PasskeyLoginUpdate) error

UpdatePasskeyAfterLogin writes a login's custody fields for userID's credential (rule 8).

func (*AccountStore) UpdateSessionActivity

func (a *AccountStore) UpdateSessionActivity(ctx context.Context, tokenHash access.Hash, act access.SessionActivity) error

UpdateSessionActivity raises a session's activity to act when act.At is later (rule 21).

func (*AccountStore) UpdateSessionLabel

func (a *AccountStore) UpdateSessionLabel(ctx context.Context, ref access.SessionRef, label string) error

UpdateSessionLabel relabels ref's session, or answers account.ErrNotFound.

func (*AccountStore) UpdateUser

func (a *AccountStore) UpdateUser(ctx context.Context, user *access.User) error

UpdateUser rewrites a stored user, or answers account.ErrNotFound.

func (*AccountStore) UserByID

func (a *AccountStore) UserByID(ctx context.Context, id int64) (*access.User, bool, error)

UserByID reads one user in its own View.

func (*AccountStore) UserByOIDC

func (a *AccountStore) UserByOIDC(ctx context.Context, id access.OIDCIdentity) (*access.User, bool, error)

UserByOIDC reads the user linked to id; the zero identity matches no user.

func (*AccountStore) UserByUsername

func (a *AccountStore) UserByUsername(ctx context.Context, canonical string) (*access.User, bool, error)

UserByUsername reads the user holding canonical exactly (rule 3).

func (*AccountStore) UserByWebAuthnHandle

func (a *AccountStore) UserByWebAuthnHandle(ctx context.Context, handle []byte) (*access.User, bool, error)

UserByWebAuthnHandle reads the user holding handle; an unknown and an empty handle answer alike (rule 9).

func (*AccountStore) UserCount

func (a *AccountStore) UserCount(ctx context.Context) (int, error)

UserCount reads the users counter.

type Activation

type Activation struct {
	Auth          *AuthMethodState
	Guard         MethodGuard
	Languages     language.Policy
	Sources       []media.SourceID
	IgnoredCodecs []string
}

Activation is the configuration every source fact is judged under: the sources in force, the language policy and the embedded codecs coverage ignores. Auth, when set, is the sign-in configuration table 2B records, and Guard judges a change to it (design 5.4).

type AuthMethodState

type AuthMethodState struct {
	OIDCIssuer, RPID string
	SignIn           SignInKeys
	PasswordLogin    bool
}

AuthMethodState is table 2B's one row: the sign-in configuration the committed settings publish. The method guard judges PasswordLogin, OIDCIssuer and RPID; OIDCIssuer is empty while OIDC is off, RPID while passkeys are off.

func MethodStateOf

func MethodStateOf(ctx context.Context, tx account.Tx) (AuthMethodState, bool, error)

MethodStateOf reads table 2B's row through tx, which must be an accountTx or the AccountStore of this package; any other tx is an error.

type AuthSecrets

type AuthSecrets struct{ FailureKey, DeviceKey [32]byte }

AuthSecrets are the two keys account.Config needs: the failure-record HMAC key and the device-cookie key.

type Coverage

type Coverage uint8

Coverage is how well an item's files serve one configured pair. Zero is invalid.

const (
	Missing Coverage = iota + 1
	Substitute
	Exact
)

The coverages, worst first.

func (Coverage) MarshalText

func (c Coverage) MarshalText() ([]byte, error)

MarshalText is missing, substitute or exact, refusing any other value.

func (*Coverage) UnmarshalText

func (c *Coverage) UnmarshalText(b []byte) error

UnmarshalText reads exactly what MarshalText writes, leaving c unchanged on a refusal.

type CoverageCount

type CoverageCount struct {
	Target     language.Tag
	Items      int
	Exact      int
	Substitute int
	Missing    int
	Locked     int
	Variant    language.Variant
}

CoverageCount is one configured pair summed over a root's items of owned instances that are not excluded: Exact, Substitute and Missing partition Items, and Locked counts set locks whatever the coverage.

type CoverageRow

type CoverageRow struct {
	LastRefusal string
	Target      language.Tag
	Variant     language.Variant
	Coverage    Coverage
	Locked      bool
}

CoverageRow is how one configured pair of an item is covered, whether the user locked it, and the wire spelling of the last automatic run's refusal while the pair is Missing ("" otherwise).

type CredentialDisable

type CredentialDisable struct {
	At          time.Time
	Provider    string
	Fingerprint string
	Reason      string
}

CredentialDisable is a provider's disabled credential: the Argon2 fingerprint of the credential refused, why, and when.

type Delta

type Delta struct {
	Roots   []media.RootKey
	Written []media.RootKey
	Marks   []string
	Epoch   [16]byte
	Rev     uint64
	Full    bool
}

Delta is what changed after a revision. Roots are the library roots whose rows changed, Written those whose managed files changed (each also in Roots), Marks the marks set. Full means the feed cannot answer from the reader's revision, so the reader re-reads everything; it carries MarkConfig when an activation change is why.

type Download

type Download struct {
	At         time.Time
	Target     language.Tag
	Refusal    string
	Items      []media.Key
	Provenance Provenance
	Attempt    int
	Inst       InstanceID
	Run        RunID
	Candidate  [32]byte
	Variant    language.Variant
	Delivered  bool
}

Download is one attempt of a run at one target for an instance's items, delivered or not. Refusal is stored as given; Candidate tells one candidate from another with the same release name.

type EmbeddedTrack

type EmbeddedTrack struct {
	Codec, Title string
	Tag          language.Tag
	Index        int
	Flags        language.Flags
}

EmbeddedTrack is one subtitle stream inside a video file.

type FileRecord

type FileRecord struct {
	Timing     timing.Timing
	Provenance *Provenance
	Name       string
	Tag        language.Tag
	Identity   Identity
	Ordinal    int
	Inst       InstanceID
	Generation uint64
	Flags      language.Flags
	Locked     bool
}

FileRecord is one file subflux manages beside an instance's video, at the Generation its last landed write gave it. Provenance is nil for a file adopted from the user.

type HistoryScope

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

HistoryScope selects the downloads History reads; the zero value is the whole log.

func ItemHistory

func ItemHistory(k media.Key) HistoryScope

ItemHistory is every download naming k.

func RootHistory

func RootHistory(r media.RootKey) HistoryScope

RootHistory is every download naming an item of r.

type Identity

type Identity struct {
	Size, MtimeNs int64
	SHA256        [32]byte
}

Identity is a file's size, modification time and content hash as written.

type InspectOptions

type InspectOptions struct{ Verify, Repair bool }

InspectOptions selects what Inspect checks beyond counts and sizes. Repair implies Verify.

type Inspection

type Inspection struct {
	Namespaces     []NamespaceStat
	Mismatches     []Mismatch
	Rev            uint64
	OldestRetained uint64
	ConfigRev      uint64
	Commits        uint64
	FileBytes      int64
	FreeBytes      int64
	Epoch          [16]byte
	Verified       bool
}

Inspection is the store's counts and sizes, and with Verified the mismatches a rescan found. It holds no key, row value or secret.

type Instance

type Instance struct {
	Source    media.SourceID
	VideoPath string
	SceneName string
	Items     []media.Key
	ID        InstanceID
}

Instance is one video file; an empty Source is ownerless.

type InstanceID

type InstanceID uint64

InstanceID names one video file's instance. Zero is invalid.

func ParseInstanceID

func ParseInstanceID(s string) (InstanceID, error)

ParseInstanceID is String's inverse for a non-zero id, refusing every other spelling: a sign, a space, a leading zero, a base prefix, a value past 2^64-1.

func (InstanceID) MarshalText

func (id InstanceID) MarshalText() ([]byte, error)

MarshalText refuses the zero id, which ParseInstanceID would refuse.

func (InstanceID) String

func (id InstanceID) String() string

String is the canonical base-10 text ParseInstanceID reads.

func (*InstanceID) UnmarshalText

func (id *InstanceID) UnmarshalText(b []byte) error

UnmarshalText reads what ParseInstanceID reads, leaving id unchanged on a refusal.

type Intent

type Intent struct {
	Name   string
	Inst   InstanceID
	SHA256 [32]byte
	Op     Op
}

Intent is one pending write: the operation, the file it names and the content hash its outcome is judged by.

type ItemRow

type ItemRow struct {
	Coverage   []CoverageRow
	Item       mediasource.Item
	Key        media.Key
	Inst       InstanceID
	HasHistory bool
}

ItemRow is one listed item: its facts from the sighting its record names, its instance (0: no video) and its configured pairs.

type ListCursor

type ListCursor string

ListCursor is a page's position in one list: "" asks for the first page, and a returned "" means the page was the last. It is not signed: a forged cursor reaches only a position paging reaches.

type LocalFile

type LocalFile struct {
	Name  string
	Tag   language.Tag
	Flags language.Flags
}

LocalFile is a subtitle file beside the video that subflux does not manage.

type MethodGuard

type MethodGuard func(ctx context.Context, tx account.Tx, before AuthMethodState, stored bool, next AuthMethodState) error

MethodGuard runs inside Activate's or ActivateAuth's Update before the record is written: before is the stored row, the zero value when stored is false. A non-nil error aborts the Update, writing nothing, and is returned as it is.

type Mismatch

type Mismatch struct {
	Name                        string
	Missing, Extra, Undecodable int
	Repaired                    bool
}

Mismatch is one table, index or counter, named namespace.name, or the derived coverage or counts rows, named statedb.coverage and statedb.counts, whose stored state differs from a rescan. For derived rows, Missing counts keys whose row is absent or differs and Extra keys whose row is present but unwanted or differs.

type NamespaceStat

type NamespaceStat struct {
	Name   string
	Tables []TableStat
	Format [32]byte
}

NamespaceStat is one namespace's stored format digest and its tables.

type NoResult

type NoResult struct {
	Next     time.Time
	Provider string
	Tag      language.Tag
	Key      media.Key
	Count    int
}

NoResult is how many searches of Provider for Key at target Tag found nothing, and when the next may run.

type Op

type Op uint8

Op is a pending write-protocol operation. Zero is invalid.

const (
	Deliver Op = iota + 1
	Retime
	Delete
)

The operations.

type OrdinalKey

type OrdinalKey struct {
	Tag   language.Tag
	Inst  InstanceID
	Flags language.Flags
}

OrdinalKey names one sequence of numbered files of an instance: the files of one tag and flags.

type PassID

type PassID uint64

PassID names one pass of one source. Zero is none.

type PassScope

type PassScope struct{ Roots []mediasource.NativeRef }

PassScope is what a pass covers: Roots nil is the whole source; any other value, empty included, is a change batch over those roots.

type PendingDeliver

type PendingDeliver struct {
	Baseline timing.Cues
	Attempts []Download
	Removes  []Removal
	Record   FileRecord
}

PendingDeliver is what a delivery stages: the record, its baseline cues, its attempts (the delivered one first) and the files it supersedes.

type Provenance

type Provenance struct {
	Provider, Release string
	Timing            timing.Outcome
	Facts             rank.Facts
	MatchedBy         rank.MatchedBy
	Fit               rank.Fit
	Manual            bool
	Uploaded          bool
	MachineTranslated bool
}

Provenance is where a managed file came from and how its timing was decided. A user's upload is Manual and Uploaded with no Provider, and is matched and fitted by nothing.

type Removal

type Removal struct {
	Name   string
	SHA256 [32]byte
}

Removal names a file a delivery supersedes, with the bytes it must still hold to be removed.

type RootRow

type RootRow struct {
	Source     media.SourceID
	Counts     []CoverageCount
	Root       mediasource.Root
	Key        media.RootKey
	HasHistory bool
}

RootRow is one listed root: its display facts come from the source of its lowest item that is owned or has no instance, and Counts holds one entry per pair its counted items configure, in Policy.Targets order.

type RootTarget

type RootTarget struct {
	Root       mediasource.NativeRef
	Source     media.SourceID
	VideoPaths []string
}

RootTarget is one source root owning instances under a root key, with those instances' video paths.

type RunID

type RunID [16]byte

RunID names one search run, which numbers its attempts from 1.

type SetDigest

type SetDigest struct {
	Count  int
	SHA256 [32]byte
}

SetDigest is a list setting compared as a set: Count distinct values and the SHA-256 of them sorted, each preceded by its byte length as a big-endian uint32.

type SignInKeys

type SignInKeys struct {
	OIDCClientID, OIDCRedirectURL     string
	OIDCAllowedGroups, PasskeyOrigins SetDigest
	OIDCClientSecret                  [32]byte
	OIDCAutoProvision, DisableAuth    bool
}

SignInKeys are the other sign-in settings platform-auth's security-log entries compare. OIDCClientSecret is the secret's SHA-256, zero when it is empty, never the secret.

type Store

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

Store is subflux's state store over one bolttable file.

func Open

func Open(path string) (*Store, error)

Open opens or creates the store at path, holding path.lock until Close. A format change resets the changed namespaces after keeping the whole file as path.<8 hex>.<stamp>.old; another holder of the lock fails it with ErrLocked after 5 s. Every error leaves the live file unreset.

func (*Store) Accounts

func (s *Store) Accounts() *AccountStore

Accounts returns the account store over s's auth namespace.

func (*Store) AckWork

func (s *Store) AckWork(ctx context.Context, ws []Work) error

AckWork deletes each row still at the generation its Work names.

func (*Store) Activate

func (s *Store) Activate(ctx context.Context, a Activation) error

Activate installs a. Changed sources, policy or codecs make one write that applies design 5.4's removal and marks config, so every reader re-reads in full; the first Activate after Open, and a policy or codec change, also recompute coverage there, deleting only unconfigured pairs' locks. An a.Auth that differs from table 2B's row is judged by a.Guard and recorded in that write, under an equal digest too. A failed Activate, a Guard refusal included, writes nothing and keeps the previous activation.

func (*Store) ActivateAuth

func (s *Store) ActivateAuth(ctx context.Context, auth AuthMethodState, guard MethodGuard) error

ActivateAuth is the auth half of a boot that is not Active (design 5.4): one Update that calls guard and writes auth as Activate's does with Activation.Auth set, and writes no source, coverage or digest row and installs no activation, so the first Activate after Open still recomputes coverage. An auth equal to table 2B's row commits nothing.

func (*Store) AuthSecrets

func (s *Store) AuthSecrets(ctx context.Context) (AuthSecrets, error)

AuthSecrets reads the keys, creating them from crypto/rand on the first call, inside one Update: a rerun or two concurrent first calls store one value and both return it. They live in auth, so a core reset keeps them.

func (*Store) Backup

func (s *Store) Backup(ctx context.Context, path string) error

Backup writes a compacted copy of the store to path, mode 0600, while the store stays open. It first removes every .*.bolttable-tmp file a crashed backup stranded in path's directory, and nothing else; backups run one at a time, so none of those is in use. An existing path fails it with an error matching fs.ErrExist; after the copy is published, a failed cleanup wraps bolttable.ErrPublished and path is complete.

func (*Store) Baseline

func (s *Store) Baseline(ctx context.Context, inst InstanceID, name string) (timing.Cues, bool, error)

Baseline returns the baseline cues of name's record; false when none is stored.

func (*Store) BeginDelete

func (s *Store) BeginDelete(ctx context.Context, inst InstanceID, name string, removed [32]byte) error

BeginDelete stages the removal of name, which must hold removed when the removal lands. It refuses, writing nothing, a name with a pending intent and an unknown instance.

func (*Store) BeginDeliver

func (s *Store) BeginDeliver(ctx context.Context, d PendingDeliver) error

BeginDeliver stages d under its record's name: nothing live changes until EndDeliver. It refuses, writing nothing, a name with a pending intent, an unknown instance, a Timing Validate refuses, the zero baseline, no attempt, an attempt for another instance, and a delivered attempt naming an item the instance does not hold.

func (*Store) BeginPass

func (s *Store) BeginPass(ctx context.Context, src media.SourceID, scope PassScope) (PassID, error)

BeginPass opens a pass of src over scope, abandoning any open one.

func (*Store) BeginRetime

func (s *Store) BeginRetime(ctx context.Context, rec FileRecord, adopt *timing.Cues) error

BeginRetime stages rec, the retimed record of a managed file, or with adopt the baseline of an unmanaged file rec adopts. It refuses, writing nothing, a name with a pending intent, an unknown instance, a Timing Validate refuses, a retime of a name with no record, and an adoption of one that has a record or of the zero baseline.

func (*Store) Changed

func (s *Store) Changed() <-chan struct{}

Changed returns the current generation's channel, closed by the next commit that allocates a revision. An observer reads Changed before Since and waits on the channel it read, so one revision wakes every observer.

func (*Store) Close

func (s *Store) Close() error

Close closes the file and releases its lock; a second Close returns nil.

func (*Store) Coverage

func (s *Store) Coverage(ctx context.Context, k media.Key) ([]CoverageRow, error)

Coverage returns k's configured pairs in Policy.TargetsFor order; none for a key with no item record.

func (*Store) CredentialDisable

func (s *Store) CredentialDisable(ctx context.Context, provider string) (CredentialDisable, bool, error)

CredentialDisable returns provider's record; found is false when the provider has none.

func (*Store) DeferWork

func (s *Store) DeferWork(ctx context.Context, w Work, notBefore time.Time) (first time.Time, deferred bool, err error)

DeferWork makes w's row due no earlier than notBefore when it is still at w's generation, records its first deferral the first time and returns that first deferral; at another generation, or for no row, it changes nothing and answers deferred false. Both survive a reopen.

func (*Store) DeleteCredentialDisable

func (s *Store) DeleteCredentialDisable(ctx context.Context, provider string) error

DeleteCredentialDisable deletes provider's record; none stored is nil.

func (*Store) DeleteJobsEndedBefore

func (s *Store) DeleteJobsEndedBefore(ctx context.Context, t time.Time) (int, error)

DeleteJobsEndedBefore implements status.Persister: the ended index's range stops at the first record ended at or after t.

func (*Store) Embedded

func (s *Store) Embedded(ctx context.Context, inst InstanceID) (VideoProbe, bool, error)

Embedded returns inst's stored probe; false when none is stored.

func (*Store) EndDelete

func (s *Store) EndDelete(ctx context.Context, inst InstanceID, name string, landed bool) error

EndDelete settles name's pending removal in one write. Landed, it deletes the record and baseline, or for an unmanaged name removes it from the local-file set, then recomputes the instance's coverage. With no pending removal it writes nothing and returns nil.

func (*Store) EndDeliver

func (s *Store) EndDeliver(ctx context.Context, inst InstanceID, name string, landed bool) error

EndDeliver settles name's pending delivery in one write. Landed, it writes the record one generation above the stored one (1 for none), its baseline, a lock on every item of the delivered attempt when the record is locked, every attempt, and removes each superseded name other than the record's own, then recomputes the instance's coverage. Not landed, it records the attempts undelivered. With no pending delivery it writes nothing and returns nil, so recovery may repeat it.

func (*Store) EndRetime

func (s *Store) EndRetime(ctx context.Context, inst InstanceID, name string, landed bool) error

EndRetime settles name's pending retime in one write. Landed, it writes the record one generation above the stored one and, for an adoption, its baseline and a lock on every configured pair the adopted file makes servable, then recomputes the instance's coverage. With no pending retime it writes nothing and returns nil.

func (*Store) EnqueueWork

func (s *Store) EnqueueWork(ctx context.Context, ids []InstanceID, cause WorkCause) error

EnqueueWork queues each known instance once: a new row takes the next enqueue position, an existing one keeps its position and the higher cause, becomes due at once and moves to the next generation, so an AckWork of the run that read the older one leaves it queued. Unknown instances are skipped.

func (*Store) Files

func (s *Store) Files(ctx context.Context, id InstanceID) ([]FileRecord, error)

Files returns the instance's managed file records by name; none for an unknown instance.

func (*Store) FinishPass

func (s *Store) FinishPass(ctx context.Context, src media.SourceID, pass PassID, complete bool, next mediasource.Cursor, keep []mediasource.NativeRef) ([]media.SourceID, error)

FinishPass closes src's open pass and returns the distinct owners all of src's overlap rows name (design 5.3). Incomplete, it retires nothing. Complete, in one write, it retires what in scope the pass did not stamp, except under a root in keep, stores next as the cursor, after a whole pass queues Scan work for src's instances outside keep, and expires instances ownerless for more than 30 days. keep, the roots a whole pass could not read, is refused, writing nothing, for a batch, an incomplete pass, or past 32 roots.

func (*Store) GetJob

func (s *Store) GetJob(ctx context.Context, id status.JobID) (status.Job, bool, error)

GetJob implements status.Persister.

func (*Store) History

func (s *Store) History(ctx context.Context, scope HistoryScope, c ListCursor, limit int) ([]Download, ListCursor, error)

History returns up to limit downloads of scope, newest first, and the cursor of the next page, "" after the last. limit outside 1 to 500 is an error, and a cursor of another list or scope is ErrCursorInvalid.

func (*Store) InsertJob

func (s *Store) InsertJob(ctx context.Context, j status.Job, lim status.JobLimits) (status.Job, bool, error)

InsertJob implements status.Persister in one write. A refusal or a replay writes nothing.

func (*Store) Inspect

func (s *Store) Inspect(ctx context.Context, o InspectOptions) (Inspection, error)

Inspect reports the store's revisions, commits, file space and per-table sizes. With Verify it rescans every index and counter, recomputes every owned item's coverage under the activation in force and recounts every root; with Repair it rewrites the index entries, counters, coverage and counts rows that differ, never another row. A row a recompute reads that does not decode fails Inspect with bolttable.ErrCorrupt naming its table. Verify before the first Activate is an error.

func (*Store) Instance

func (s *Store) Instance(ctx context.Context, id InstanceID) (Instance, bool, error)

Instance returns any stored instance, ownerless ones included; false for an unknown id.

func (*Store) Item

Item returns k's facts from the sighting its item record names, and that sighting's root; false when k has no record or its instance is ownerless.

func (*Store) ItemRow

func (s *Store) ItemRow(ctx context.Context, k media.Key) (ItemRow, bool, error)

ItemRow returns k's row as Items lists it; false when k has no record or its instance is ownerless.

func (*Store) Items

func (s *Store) Items(ctx context.Context, root media.RootKey, c ListCursor, limit int) ([]ItemRow, ListCursor, error)

Items returns up to limit of root's items in key order, skipping those of ownerless instances, and the cursor of the next page, "" after the last. limit outside 1 to 500 is an error; a cursor of another list or root is ErrCursorInvalid.

func (*Store) JobByKey

func (s *Store) JobByKey(ctx context.Context, owner int64, key string) (status.Job, bool, error)

JobByKey implements status.Persister.

func (*Store) NextWork

func (s *Store) NextWork(ctx context.Context, limit int) ([]Work, error)

NextWork returns up to limit due rows, every Item row before any other and each cause oldest first. limit outside 1 to 1,000 is an error.

func (*Store) NoResults

func (s *Store) NoResults(ctx context.Context, root media.RootKey, season uint16) ([]NoResult, error)

NoResults returns every row of root's season (0 for a movie) with one prefix scan, in key, tag and provider order.

func (*Store) NoteRefusal

func (s *Store) NoteRefusal(ctx context.Context, inst InstanceID, tag language.Tag, v language.Variant, refusal string) error

NoteRefusal stores refusal, search's wire spelling of why an automatic run of the pair delivered nothing, on the pair's coverage of every item of inst where it is Missing, in one write; a byte-equal value writes nothing. The next recompute leaving the pair not Missing, and a landed delivery of the pair, clear it. An unknown or ownerless instance, or an empty refusal, is refused, writing nothing.

func (*Store) ObserveItems

func (s *Store) ObserveItems(ctx context.Context, src media.SourceID, pass PassID, root mediasource.Root, items []mediasource.Item) error

ObserveItems records what src's open pass saw of root, in one write (design 5.2): the root record and its evidence (deleted when nil), then each item's sighting, claim and stamp in order. It refuses with ErrSourceInactive or ErrPassUnknown, and with a plain error for a root ref of no media kind or no id, evidence failing Validate or naming another TVDB series, an empty or duplicate item id, or a video path neither empty nor absolute and clean, writing nothing. Under a change batch it also queues Import work for every instance an observed item is attached to.

func (*Store) PendingDeliverOf

func (s *Store) PendingDeliverOf(ctx context.Context, inst InstanceID, name string) (PendingDeliver, bool, error)

PendingDeliverOf returns what name's pending delivery staged; false when name has no pending delivery.

func (*Store) PendingWrites

func (s *Store) PendingWrites(ctx context.Context) ([]Intent, error)

PendingWrites lists every pending intent, by instance and name.

func (*Store) Policy

func (s *Store) Policy() language.Policy

Policy returns the language policy of the activation in force, the zero Policy before the first Activate.

func (*Store) PutCredentialDisable

func (s *Store) PutCredentialDisable(ctx context.Context, d CredentialDisable) error

PutCredentialDisable stores d, replacing its provider's record; an empty Provider is refused, writing nothing.

func (*Store) PutEmbedded

func (s *Store) PutEmbedded(ctx context.Context, inst InstanceID, p VideoProbe) error

PutEmbedded stores inst's probe and recomputes its items' coverage in the same write; it deletes only locks on pairs no longer configured, since it runs before the local-file listing. An unknown instance is refused, writing nothing.

func (*Store) PutExternal

func (s *Store) PutExternal(ctx context.Context, inst InstanceID, files []LocalFile) error

PutExternal stores inst's local-file set, empty included, and recomputes its items' coverage in the same write, also when the set is unchanged: with a probe stored the inventory is complete, so a lock nothing serves is deleted. Files are stored by name; an empty or repeated name, or an unknown instance, is refused, writing nothing.

func (*Store) PutJob

func (s *Store) PutJob(ctx context.Context, j status.Job) error

PutJob implements status.Persister.

func (*Store) PutNoResults

func (s *Store) PutNoResults(ctx context.Context, rows []NoResult) error

PutNoResults writes rows in one write: a row with Count 0 deletes the stored one, and a row for a key with no item record is skipped, since the item record's deletion is what removes its rows. A negative Count is refused, writing nothing.

func (*Store) RecordAttempts

func (s *Store) RecordAttempts(ctx context.Context, ds []Download) error

RecordAttempts appends ds to the download log as undelivered attempts in one write. A delivered attempt is EndDeliver's to record and is refused, as is an attempt naming no item, writing nothing.

func (*Store) ReserveOrdinal

func (s *Store) ReserveOrdinal(ctx context.Context, k OrdinalKey, highestOnDisk int) (int, error)

ReserveOrdinal returns the next ordinal of k's numbered files: above highestOnDisk and above every ordinal it returned before for k, so none is ever reused while k's instance lives. It refuses a negative highestOnDisk, an unknown instance, and an ordinal past math.MaxInt, storing nothing; once math.MaxInt is returned every later call for k is refused, across restarts.

func (*Store) Root

func (s *Store) Root(ctx context.Context, root media.RootKey) (RootRow, bool, error)

Root returns root's row as Roots lists it; false when no item of root is owned or has no instance.

func (*Store) RootEvidence

RootEvidence returns the evidence src's last observation of root carried; found is false when it carried none or the root has no record.

func (*Store) RootTargets

func (s *Store) RootTargets(ctx context.Context, root media.RootKey) ([]RootTarget, error)

RootTargets returns one target per source root owning instances under root, by source and root, each with its instances' video paths sorted.

func (*Store) Roots

func (s *Store) Roots(ctx context.Context, c ListCursor, limit int) ([]RootRow, ListCursor, error)

Roots returns up to limit roots in key order that have an item owned or with no instance, and the cursor of the next page, "" after the last. limit outside 1 to 500 is an error; a cursor of another list is ErrCursorInvalid.

func (*Store) SetLock

func (s *Store) SetLock(ctx context.Context, inst InstanceID, tag language.Tag, v language.Variant, locked bool) error

SetLock sets or clears the pair's lock on every item of inst that configures it, in one write, so a double episode is pinned or resumed whole. It refuses with ErrNotLockable an unknown or ownerless instance or a pair no item configures, and, locking, a pair none of the instance's evidence can serve. Locking a locked pair or clearing an unlocked one writes nothing.

func (*Store) Since

func (s *Store) Since(ctx context.Context, epoch [16]byte, after uint64) (Delta, error)

Since answers what changed after revision after of the store opened with epoch: Full with the head revision for another epoch, an after of 0 or below the last activation change, or a range the feed no longer retains; otherwise every root, written root and mark since after, deduplicated.

func (*Store) SourceCursor

func (s *Store) SourceCursor(ctx context.Context, src media.SourceID) (mediasource.Cursor, bool, error)

SourceCursor returns the cursor src's last complete pass stored; false when none.

func (*Store) UnfinishedJobs

func (s *Store) UnfinishedJobs(ctx context.Context) ([]status.Job, error)

UnfinishedJobs implements status.Persister, scanning at most the DefaultLimits' Total plus one owner's PerOwner (SystemOwner's) records.

func (*Store) Unidentified

func (s *Store) Unidentified(ctx context.Context, c ListCursor, limit int) ([]UnidentifiedRow, ListCursor, error)

Unidentified returns up to limit sightings no key could be chosen for, by source, root and item, and the cursor of the next page, "" after the last. limit outside 1 to 500 is an error; a cursor of another list is ErrCursorInvalid.

func (*Store) WorkReady

func (s *Store) WorkReady() <-chan struct{}

WorkReady is signalled after every commit that enqueued work, and once at Open when the stored queue is not empty. It holds one wake, for one drainer, which reads NextWork until it answers none.

func (*Store) WriteHealth

func (s *Store) WriteHealth() WriteHealth

WriteHealth reports the outcomes of every write since Open. A refusal, a unique-index conflict or a context error is not a failure.

type TableStat

type TableStat struct {
	Name  string
	Rows  int
	Bytes int64
}

TableStat is one table's row count and the bytes its pages use.

type UnidentifiedRow

type UnidentifiedRow struct {
	Source media.SourceID
	Root   mediasource.Root
	Item   mediasource.Item
}

UnidentifiedRow is a sighting no key could be chosen for, with its root.

type VideoProbe

type VideoProbe struct {
	Tracks []EmbeddedTrack
	Stamp  VideoStamp
	FPS    float64
}

VideoProbe is what probing a video file found. A failed probe is stored as one with no tracks and a zero stamp, so the instance's inventory still completes.

type VideoStamp

type VideoStamp struct{ Size, MtimeNs int64 }

VideoStamp is the video file's size and modification time when probed; zero for a probe that failed.

type Work

type Work struct {
	Inst  InstanceID
	Gen   uint64
	Cause WorkCause
}

Work is one queued instance at the generation NextWork read it.

type WorkCause

type WorkCause uint8

WorkCause is why an instance is queued for work; Item outranks Import, which outranks Scan. Zero is invalid.

const (
	Scan WorkCause = iota + 1
	Import
	Item
)

The work causes.

type WriteHealth

type WriteHealth struct {
	Last               error
	LastFailed, LastOK time.Time
	Failures           uint64
}

WriteHealth is the store's write outcomes since Open: every failed commit counted, the latest kept, and when a write last failed and last committed.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL