README
¶
Local setup
Service.Initialize creates one configuration file and one initial gateway API key.
It honors the selected configuration file and Badger directory, including independent parent directories.
It refuses existing or conflicting state.
Setup closes and verifies the staged Badger database before publishing it at the selected database path. It publishes configuration last. A durable database binding blocks gateway startup until the configuration transaction settles. The two roots do not need to share a filesystem. Each rename stays within its own parent directory.
GuardLocalStorage holds the database writer lock throughout a persistent local gateway's lifetime.
Application shutdown closes the stores before releasing this guard.
Valkey and in-memory development storage do not use this local guard.
Files
C is the parent of the selected configuration file.
D is the parent of the selected Badger directory. B is that directory's basename.
These values follow explicit leaf overrides rather than assuming the default product roots.
| Path | Purpose and lifetime |
|---|---|
C/.starport-setup/.owner.lock |
Stable configuration transaction lock. Keep it after setup and rollback. |
C/.starport-setup/transaction.json |
Pending transaction, native identities, file receipts, and generated configuration. Remove it only after verified completion. |
D/.starport-setup-B/.owner.lock |
Stable exclusion between setup, rollback, and a running local gateway. |
D/.starport-setup-B/configuration.json |
Bind pending database work to its configuration selector. Keep it through interruptions. |
D/.starport-init-<uuid>/ |
Private staged database or database isolated for rollback. Preserve changed or unrecognized contents. |
.record-publications/ below each record-writing directory |
Starmap's native record publisher owns its lock, journals, and recovery. |
Transaction and configuration files can contain the security master key. Their access policy is owner-only. The plaintext gateway API key stays in the process result. Neither the transaction journal nor configuration stores it. Badger owns its internal file modes inside the private engine directory.
Setup limits its journal to 1 MiB and its database receipt to 64 files. Each database file can contain at most 64 MiB. The full receipt covers at most 128 MiB. These limits cover initialization and rollback, not normal database growth.
Recovery
Retry initialization with the same selected paths to recover a pending transaction. The retry checks native directory identities, file identities, sizes, modes, timestamps, and content hashes. It preserves unknown files, changed files, malformed journals, and conflicting destinations.
Recovery can remove an empty interrupted preparation. A preparation that stopped while writing Badger can contain state without a complete receipt. Recovery preserves that directory and reports its path for operator inspection.
Recovery removes verified unpublished state before issuing a new initial key. A completed configuration publication retains its key record. Recovery cannot reproduce the original one-time plaintext key.
Rollback isolates the database and verifies its initial records before deleting configuration. A refused rollback restores the database without replacing another destination. If restoration cannot finish, its journal and database remain available for recovery. Cleanup removes only receipt-bound files and supports retries after partial deletion.
The package tests terminate child processes at publication, rollback, restoration, and cleanup boundaries. They also cover concurrent writers, path overrides, cancellation, active storage, and changed state.
Documentation
¶
Overview ¶
Package setup owns safe first-run initialization for a local Starport instance.
Index ¶
- Variables
- func GuardLocalStorage(ctx context.Context, paths config.Paths) (_ io.Closer, resultErr error)
- func InitializeAPIKey(ctx context.Context, store storage.KVStore, name string) (apikey.IssueResult, error)
- func InspectRecoveryState(ctx context.Context, paths config.Paths) ([]byte, error)
- func ReleaseAPIKey(ctx context.Context, store storage.KVStore, id string) error
- type Request
- type Result
- type Service
- type State
Constants ¶
This section is empty.
Variables ¶
var ( // ErrPathsRequired reports incomplete managed paths. ErrPathsRequired = errors.New("setup paths are required") // ErrAlreadyInitialized reports existing configuration or API key storage. ErrAlreadyInitialized = errors.New("starport is already initialized") // ErrPartialState reports an incomplete managed configuration directory. ErrPartialState = errors.New("starport setup state is incomplete") // ErrRollbackRefused reports state that does not match an initialization result. ErrRollbackRefused = errors.New("setup rollback refused") )
Functions ¶
func GuardLocalStorage ¶ added in v1.3.0
GuardLocalStorage excludes setup while a persistent local gateway owns storage. The caller must close the guard after all gateway stores close. A pending setup transaction requires an explicit initialization retry.
func InitializeAPIKey ¶ added in v1.1.0
func InitializeAPIKey( ctx context.Context, store storage.KVStore, name string, ) (apikey.IssueResult, error)
InitializeAPIKey creates the first named API key in configured storage. It refuses a repository that already contains an apikey.
func InspectRecoveryState ¶ added in v1.3.0
InspectRecoveryState checks current target setup ownership without creating or repairing state. Captured source setup transactions remain inactive and never become target instructions.
Types ¶
type Request ¶
type Request struct {
APIKeyName string
}
Request contains the explicit choices for local initialization.
type Result ¶
type Result struct {
APIKeyName string
ConfigFile string
DataDir string
APIKey string
// contains filtered or unexported fields
}
Result contains initialized paths and the one-time gateway credential.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
Service initializes one local configuration and API key store.
func (*Service) Initialize ¶
Initialize creates local configuration and one named gateway apikey. It never replaces an existing configuration file or API key store.
type State ¶
type State string
State describes the durable local setup state.
const ( // StateAbsent means the managed configuration directory does not exist. StateAbsent State = "absent" // StatePartial means the directory exists without both required artifacts. StatePartial State = "partial" // StateReady means the configuration file and API key store both exist. StateReady State = "ready" )
Source Files