Documentation
¶
Overview ¶
Package vaultlock is the vault's write lock (encryption level 3, docs/E2E-VAULT-FORMAT.md → The write lock): at most one session writes a vault, and the server is what says which.
The rules, all decided here and nowhere else:
- a lock belongs to the key file's vault.id within its tenant (Key), not to a path: renaming the vault folder keeps it, and a copy of a vault made on the server shares it;
- it is HELD while the lease has not run out (60 seconds, renewed by the heartbeat and by every vault write) AND the holder is not idle (a vault write or an active renewal within the person's idle time, 1 to 10 minutes, 3 by default, read when the lock is taken);
- it is free again the moment it ends - released, run out, idle or broken - UNLESS an index write of its holder is still running: then it is free when that write ends, or 60 seconds after it began;
- the token is 32 random bytes, handed out once, kept only as its SHA-256.
The state lives in the database (vault_locks, migration 00096), not in this process: filex can run more than one process on one database, and every decision below reads the row and writes it back by compare-and-set on its revision. Nothing is cached. The clock and the random source can be replaced, so a test can walk a lock through a lease without waiting.
A lock that ends because time ran out has nobody to say so: its row is closed - and OnEnded told, for the audit row and the realtime event - by the next call that finds it ended (a renewal, a take, a state read).
Index ¶
- Constants
- Variables
- func HashToken(token string) (string, bool)
- type Ended
- type Finder
- type Holder
- type Key
- type Lock
- type LockedError
- type LostError
- type Place
- type Renewed
- type Service
- func (s *Service) BeginIndex(ctx context.Context, k Key, token string) error
- func (s *Service) Break(ctx context.Context, k Key, by Holder) (*Ended, error)
- func (s *Service) EndIndex(ctx context.Context, k Key, token string, gen int64, committed bool) error
- func (s *Service) IdleMinutes(ctx context.Context, userID int64) (int, error)
- func (s *Service) Now() time.Time
- func (s *Service) Release(ctx context.Context, k Key, token, reason string) error
- func (s *Service) Renew(ctx context.Context, k Key, token string, active bool) (*Renewed, error)
- func (s *Service) SetClock(now func() time.Time)
- func (s *Service) SetIdleMinutes(ctx context.Context, userID int64, minutes int) error
- func (s *Service) SetRand(r io.Reader)
- func (s *Service) State(ctx context.Context, k Key) (*Lock, error)
- func (s *Service) Take(ctx context.Context, k Key, p Place, h Holder) (*Taken, error)
- func (s *Service) Touch(ctx context.Context, k Key, token string) error
- type Store
- type Taken
Constants ¶
const ( Lease = 60 * time.Second Heartbeat = 15 * time.Second IndexWriteMax = 60 * time.Second DefaultIdleMinutes = 3 MinIdleMinutes = 1 MaxIdleMinutes = 10 // TokenBytes is the size of a lock token before encoding. TokenBytes = 32 )
The format's numbers (docs/E2E-VAULT-FORMAT.md → Lock semantics).
const ( ReasonReleased = "released" ReasonExpired = "expired" ReasonIdle = "idle" ReasonBroken = "broken" ReasonTaken = "taken" // ReasonLockedIdle is what a client adds when it locked the vault itself // after 15 minutes of nothing (docs/E2E-VAULT-FORMAT.md → The idle lock) // while it held the write lock: a release, recorded with this reason. ReasonLockedIdle = "locked_idle" )
Why a lock ended - the `reason` of VAULT_LOCK_LOST and of the vault.unlock audit row. Taken is said only to the holder of a lost lock that somebody else holds now.
Variables ¶
Clients a lock may name.
var ErrContention = errors.New("the vault's lock row kept changing; try again")
ErrContention is a row that kept changing under every attempt to write it.
var ErrIdleRange = fmt.Errorf("the idle time is %d to %d minutes", MinIdleMinutes, MaxIdleMinutes)
ErrIdleRange refuses an idle time outside 1 to 10 minutes.
var ErrIndexRunning = errors.New("an index write of this lock is still running")
ErrIndexRunning refuses a second index write while one of the holder's is still running.
var ErrLocked = errors.New("the vault is locked by another session")
ErrLocked: somebody else holds the lock (*LockedError says who).
var ErrLost = errors.New("the vault's write lock was lost")
ErrLost: the token does not hold the lock (*LostError says why).
Functions ¶
Types ¶
type Ended ¶
type Ended struct {
Key
Place
Holder Holder
// Reason: released, expired, idle, broken or locked_idle.
Reason string
// By is who broke the lock (Reason broken); zero otherwise.
By Holder
FirstGen int64
LastGen int64
Since time.Time
At time.Time
}
Ended is a lock that ended, told once to OnEnded by the call that closed its row.
type Finder ¶
type Finder struct {
// contains filtered or unexported fields
}
Finder answers which vault folder holds a path - the question every write door asks through writegate (acl.Resolver.AttachVaults): inside a vault, only the vault API writes.
A path is in a vault when the encrypted folder it sits in (e2e.FindRoot: the nearest folder whose key file is in the catalogue) has a key file that names the vault feature (e2e.ParseVaultKeyFile). The key file is read from the storage once per version of it: the answer is kept, keyed by the key file's row as the catalogue has it NOW (size, etag, modification time), so a rewritten key file is read again. What it remembers is a fact about bytes that cannot change - a vault's `v`, `req` and `vault` never do (writegate refuses a rewrite that would) - not a decision another process could have changed.
⚠ It sees what the catalogue sees, as e2e.FindRoot does: a vault whose key file has no row yet (a lazily catalogued folder nobody opened) is not recognised until it has one.
type Lock ¶
type Lock struct {
Holder Holder
Since time.Time
// ExpiresAt is when it ends if nothing more happens: the lease or the
// idle time, whichever comes first (or the end of a running index write).
ExpiresAt time.Time
// contains filtered or unexported fields
}
Lock is a lock as State shows it.
type LockedError ¶
LockedError names who holds the lock, since when, and how long until it could be free.
func (*LockedError) Error ¶
func (e *LockedError) Error() string
func (*LockedError) Unwrap ¶
func (e *LockedError) Unwrap() error
type LostError ¶
LostError says why a token no longer holds its lock: expired, idle, broken, released or taken - and, for taken and broken, who: the session that holds it now, or the person who broke it (only a name: a break names no client).
type Service ¶
type Service struct {
// OnEnded is told of every lock this service sees end, once, after the
// row that records the ending was written. Nil = nobody.
OnEnded func(ctx context.Context, e Ended)
// contains filtered or unexported fields
}
Service takes, renews, releases and breaks vault locks.
func (*Service) BeginIndex ¶
BeginIndex records that token's holder starts an index write: it must hold the lock, no other index write of it may be running (ErrIndexRunning), and the write renews the lease and counts as activity. From here until EndIndex - or 60 seconds - the lock is not free, even if it ends.
func (*Service) Break ¶
Break ends whatever lock k has now, for by (the handler decides who may). broken is the lock that was broken - nil when none was held (a lock that had already run out is closed with its own reason, not broken). Its holder's next call is told `broken`, and by whom.
func (*Service) EndIndex ¶
func (s *Service) EndIndex(ctx context.Context, k Key, token string, gen int64, committed bool) error
EndIndex records the end of token's index write: committed says whether generation gen is now in place (the first and last generation of the lock follow it). The lock it was written under may have ended meanwhile; the record is kept all the same, and a lock still held is renewed by it.
func (*Service) IdleMinutes ¶
IdleMinutes is the idle time of a person: what they set, else 3.
func (*Service) Release ¶
Release ends token's lock, if its row still records it: reason released, or locked_idle when the client says it locked the vault itself after 15 minutes of nothing (docs/E2E-VAULT-FORMAT.md → The idle lock) - recorded as said, since that client's write lock has usually ended for idle minutes before and nobody closed the row yet. Any other reason reads as released; a plain release of a lock that had already run out is recorded with the reason it ended for. Releasing a lock the token does not hold does nothing.
func (*Service) Renew ¶
Renew renews token's lock: the lease starts again, and active also counts as activity (the holder is about to write). A *LostError when the token does not hold the lock any more, with the reason.
func (*Service) SetIdleMinutes ¶
SetIdleMinutes stores a person's idle time: ErrIdleRange outside 1 to 10. A lock already held keeps the idle time it was taken with.
func (*Service) State ¶
State is k's lock as everybody may see it: nil when the vault is free. A lock found ended is closed here (OnEnded is told). A lock that ended while its holder's index write still runs is shown until that write ends.
type Store ¶
type Store interface {
GetVaultLock(ctx context.Context, tenantID int64, vaultID string) (*model.VaultLock, error)
InsertVaultLock(ctx context.Context, l *model.VaultLock) (bool, error)
UpdateVaultLock(ctx context.Context, l *model.VaultLock, rev int64) (bool, error)
GetVaultIdleMinutes(ctx context.Context, userID int64) (int, error)
SetVaultIdleMinutes(ctx context.Context, userID int64, minutes int) error
}
Store is what the service needs of the database (db.Store has it, VaultLockSQL).
Source Files