Documentation
¶
Index ¶
- Constants
- Variables
- type Bark
- type BarkConfig
- type BlobStoreBark
- func (b *BlobStoreBark) Close() error
- func (b *BlobStoreBark) Delete(txn types.Txn, key []byte) error
- func (b *BlobStoreBark) DeleteBlock(txn types.Txn, slot uint64, hash []byte, id uint64) error
- func (b *BlobStoreBark) DeleteTx(txn types.Txn, txHash []byte) error
- func (b *BlobStoreBark) DeleteUtxo(txn types.Txn, txId []byte, outputIdx uint32) error
- func (b *BlobStoreBark) DiskSize() (int64, error)
- func (b *BlobStoreBark) Get(txn types.Txn, key []byte) ([]byte, error)
- func (b *BlobStoreBark) GetBlock(txn types.Txn, slot uint64, hash []byte) ([]byte, types.BlockMetadata, error)
- func (b *BlobStoreBark) GetBlockLocal(txn types.Txn, slot uint64, hash []byte) ([]byte, types.BlockMetadata, error)
- func (b *BlobStoreBark) GetBlockURL(ctx context.Context, txn types.Txn, point ocommon.Point) (types.SignedURL, types.BlockMetadata, error)
- func (b *BlobStoreBark) GetCommitTimestamp() (int64, error)
- func (b *BlobStoreBark) GetTx(txn types.Txn, txHash []byte) ([]byte, error)
- func (b *BlobStoreBark) GetUtxo(txn types.Txn, txId []byte, outputIdx uint32) ([]byte, error)
- func (b *BlobStoreBark) NewIterator(txn types.Txn, opts types.BlobIteratorOptions) types.BlobIterator
- func (b *BlobStoreBark) NewTransaction(b2 bool) types.Txn
- func (b *BlobStoreBark) Set(txn types.Txn, key, val []byte) error
- func (b *BlobStoreBark) SetBlock(txn types.Txn, slot uint64, hash []byte, cbor []byte, id uint64, ...) error
- func (b *BlobStoreBark) SetCommitTimestamp(i int64, txn types.Txn) error
- func (b *BlobStoreBark) SetTx(txn types.Txn, txHash []byte, offsetData []byte) error
- func (b *BlobStoreBark) SetUtxo(txn types.Txn, txId []byte, outputIdx uint32, cbor []byte) error
- func (b *BlobStoreBark) Sync() error
- func (b *BlobStoreBark) TombstoneBlock(txn types.Txn, slot uint64, hash []byte) error
- type BlobStoreBarkConfig
Constants ¶
const ( // DefaultMaxRequestBody bounds each incoming Connect message before it is // decoded or authenticated. Connect applies this per-message limit to both // compressed wire bytes and the decompressed message. DefaultMaxRequestBody = 1 << 20 // 1 MiB // DefaultMaxResponseBody bounds each outgoing Connect message without // imposing a whole-stream limit on StreamOperationProgress. DefaultMaxResponseBody = 1 << 20 // 1 MiB // DefaultMaxFetchBlockRefs bounds the storage/signing work and response // growth driven by one anonymous ArchiveService request. DefaultMaxFetchBlockRefs = 100 // DefaultRequestReadTimeout bounds request headers and bodies while leaving // response writes unbounded for long-lived server streams. DefaultRequestReadTimeout = 60 * time.Second )
Variables ¶
var ( // ErrArchiveBlockUndecodable reports an archive response body that does // not decode as a block of the type the archive claimed. ErrArchiveBlockUndecodable = errors.New( "bark: archive block could not be decoded", ) // ErrArchiveBlockHashMismatch reports a decoded block whose computed // hash is not the hash that was requested. ErrArchiveBlockHashMismatch = errors.New( "bark: archive block hash does not match the requested hash", ) // ErrArchiveBlockSlotMismatch reports a decoded block that does not sit // at the slot that was requested. ErrArchiveBlockSlotMismatch = errors.New( "bark: archive block slot does not match the requested slot", ) // ErrArchiveMetadataMismatch reports archive-supplied metadata that // contradicts the contents of the verified block it accompanied. ErrArchiveMetadataMismatch = errors.New( "bark: archive metadata contradicts the block", ) // ErrArchiveBlockTypeMismatch reports a block whose era, derived from its // own header, is not the era the archive claimed. ErrArchiveBlockTypeMismatch = errors.New( "bark: archive block era does not match the block header", ) // ErrArchiveBlockNotFullyAuthenticated reports a block whose body cannot // be bound to its header in full, so the archive could alter the // unauthenticated part without changing anything checked here. ErrArchiveBlockNotFullyAuthenticated = errors.New( "bark: archive block body cannot be fully authenticated", ) )
Errors reported when an archive response fails local verification. They are distinct from transport failures on purpose: a transport error is worth retrying, whereas these mean the archive served something that is not the block that was asked for, and its answers cannot be trusted as chain data.
ErrDBUnavailable is returned by Acquire when there is currently no usable database to hand out — either none has been set yet, or a live Restore/Truncate has paused access via PauseDB while it swaps the old one out for a freshly rebuilt one. Handlers should map this to connect.CodeUnavailable rather than surfacing it as an internal error.
Functions ¶
This section is empty.
Types ¶
type Bark ¶
type Bark struct {
// contains filtered or unexported fields
}
func NewBark ¶
func NewBark(cfg BarkConfig) (*Bark, error)
func (*Bark) Acquire ¶ added in v0.69.0
Acquire pins the current database for the duration of one request: callers must use the returned db for every call they make during the request, then call release exactly once (typically via defer) when done with it. Pinning matters because a live Restore/Truncate closes the old database and opens a new one in place — without pinning, a request that fetched the pointer at the top and kept calling methods on it over its lifetime (as GetDatabaseInfo and FetchBlock both do) could end up racing that close, anywhere from a confusing internal error (sqlite queries against a closed *sql.DB) to an outright panic (Badger panics opening a transaction against a closed DB). Acquire's underlying dbGate stays read-locked for exactly as long as release is unheld, so PauseDB's write-lock acquisition — and therefore the actual database close it's guarding — waits for every in-flight Acquire to finish first.
Returns ErrDBUnavailable (with a nil db and release) if no database is currently set, or if PauseDB currently has the gate held: Acquire never blocks waiting for a pause to end, since that could be a long-running Restore/Truncate — callers report unavailable immediately instead.
The config.DB read below deliberately does not take b.mu: Stop holds b.mu for the entire duration of its blocking server.Shutdown call, which waits for in-flight requests — including ones calling Acquire — to finish. If Acquire also needed b.mu here, a request whose handler is exactly what Shutdown is waiting to drain could deadlock against Stop forever. It's safe to skip: dbGate alone is sufficient synchronization for this access, since ResumeDB always finishes writing config.DB (under its own b.mu critical section) before it unlocks dbGate, and Go's mutex happens-before guarantee means that unlock is visible to whichever Acquire's TryRLock above next succeeds — no separate b.mu read needed.
func (*Bark) Addr ¶ added in v0.69.0
Addr returns the address the server is actually listening on (e.g. "127.0.0.1:54321"), populated once Start has bound the listener — most useful when Port was 0, letting a test or an operator discover the OS-assigned port without a separate, racy net.Listen-then-close probe. Returns "" before Start has been called, and again once the server has stopped (Stop, or the listener automatically shutting down when Start's ctx is cancelled) — never a stale address for a listener that is no longer actually open.
func (*Bark) PauseDB ¶ added in v0.69.0
func (b *Bark) PauseDB()
PauseDB blocks new Acquire calls (which fail immediately with ErrDBUnavailable rather than blocking behind it) and waits for every currently in-flight Acquire to release, so the database it currently points at can be safely closed once this returns. Must always be followed by a later ResumeDB call — typically bracketing a live Restore/Truncate's quiesce-close-reinitialize sequence — or Bark's database access is left paused permanently.
func (*Bark) ResumeDB ¶ added in v0.69.0
ResumeDB publishes db as what Acquire hands out going forward, then releases the pause PauseDB put in place. Call this only once the replacement database is fully initialized and ready to serve — e.g. from a live Restore/Truncate's reinitializeAPIServers step — so no Acquire caller ever observes a database that's still mid-setup.
type BarkConfig ¶
type BarkConfig struct {
Logger *slog.Logger
DB *database.Database
Lifecycle *dblifecycle.Service
// SnapshotDir is the base directory the DatabaseService's CreateSnapshot/
// Restore RPCs write to and read from — required when Lifecycle is set.
// There is no separate snapshot catalog store (see database.go's doc
// comment); ListSnapshots/ListAvailableSnapshots scan this directory
// for manifest.json files instead, so each snapshot's generated ID is
// also its directory name directly under SnapshotDir.
SnapshotDir string
// SnapshotCloudDestination, if set, is the same cloud destination URI
// as databaseLifecycle.snapshotCloudDestination — passed through here
// so ListAvailableSnapshots can additionally list what's stored there
// (via database/lifecycle.ListCloudSnapshots), merged with the local
// catalog. Empty disables cloud listing; CreateSnapshot's own upload
// path doesn't need this field since it goes through Lifecycle, which
// already has its own copy of the same config value.
SnapshotCloudDestination string
// DestinationRegistry supplies the cloud destination schemes (s3, gcs)
// this Bark instance's DatabaseService handler can resolve
// SnapshotCloudDestination/cloud snapshot URIs against — composition
// code owns constructing it; nil is valid when no cloud destination
// is ever configured.
DestinationRegistry *lifecycle.DestinationRegistry
TlsCertFilePath string
TlsKeyFilePath string
// TlsClientCAFilePath is a PEM CA bundle used to verify client
// certificates (mTLS) on this listener. Required whenever Lifecycle is
// set: the DatabaseService's destructive RPCs (CreateSnapshot,
// DeleteSnapshot, VerifySnapshot, Restore, Truncate, CancelOperation)
// refuse any request whose connection didn't present a certificate
// verified against this CA — see newOperatorAuthInterceptor in auth.go.
// ArchiveService remains public, but every DatabaseService RPC requires a
// verified certificate. Destructive DatabaseService RPCs additionally
// require a fingerprint in OperatorCertificateFingerprints. Requires
// TlsCertFilePath/TlsKeyFilePath to also be set, since mTLS has no meaning
// without the server's own TLS listener underneath it. Start (not NewBark)
// fails closed if Lifecycle is set without these policies.
TlsClientCAFilePath string
// OperatorCertificateFingerprints is the explicit authorization policy for
// destructive DatabaseService calls. Values are SHA-256 fingerprints of
// client certificate DER bytes; hexadecimal values may contain colons and
// are matched case-insensitively. Read-only DatabaseService calls require a
// verified client certificate but do not require membership in this list.
OperatorCertificateFingerprints []string
Host string
Port uint
// CORSAllowedOrigins configures Access-Control-Allow-Origin.
// Empty disables CORS.
CORSAllowedOrigins []string
}
type BlobStoreBark ¶
type BlobStoreBark struct {
// contains filtered or unexported fields
}
func NewBarkBlobStore ¶
func NewBarkBlobStore( config BlobStoreBarkConfig, upstream blob.BlobStore, ) (*BlobStoreBark, error)
func (*BlobStoreBark) Close ¶
func (b *BlobStoreBark) Close() error
func (*BlobStoreBark) DeleteBlock ¶
func (*BlobStoreBark) DeleteTx ¶
func (b *BlobStoreBark) DeleteTx(txn types.Txn, txHash []byte) error
func (*BlobStoreBark) DeleteUtxo ¶
func (*BlobStoreBark) DiskSize ¶ added in v0.29.0
func (b *BlobStoreBark) DiskSize() (int64, error)
func (*BlobStoreBark) GetBlock ¶
func (b *BlobStoreBark) GetBlock( txn types.Txn, slot uint64, hash []byte, ) ([]byte, types.BlockMetadata, error)
func (*BlobStoreBark) GetBlockLocal ¶ added in v0.70.1
func (b *BlobStoreBark) GetBlockLocal( txn types.Txn, slot uint64, hash []byte, ) ([]byte, types.BlockMetadata, error)
GetBlockLocal bypasses Bark's archive fallback. Nested wrappers are unwrapped through the same optional interface.
func (*BlobStoreBark) GetBlockURL ¶
func (*BlobStoreBark) GetCommitTimestamp ¶
func (b *BlobStoreBark) GetCommitTimestamp() (int64, error)
func (*BlobStoreBark) NewIterator ¶
func (b *BlobStoreBark) NewIterator( txn types.Txn, opts types.BlobIteratorOptions, ) types.BlobIterator
func (*BlobStoreBark) NewTransaction ¶
func (b *BlobStoreBark) NewTransaction(b2 bool) types.Txn
func (*BlobStoreBark) SetCommitTimestamp ¶
func (b *BlobStoreBark) SetCommitTimestamp(i int64, txn types.Txn) error
func (*BlobStoreBark) Sync ¶ added in v0.69.0
func (b *BlobStoreBark) Sync() error
Source Files