Skip to content

fix: rework GoatDB lifecycle into a state machine - #136

Open
ofriw wants to merge 3 commits into
mainfrom
debt/94
Open

ofriw wants to merge 3 commits into
mainfrom
debt/94

Conversation

@ofriw

@ofriw ofriw commented Nov 18, 2026

Copy link
Copy Markdown
Collaborator

Note: This PR was generated by an AI agent. If you'd like to talk with other humans, drop by our Discord!


Why

Closing a GoatDB instance was fragile. The ready boolean could not represent closing, closed, or failed states. Callers could keep using a closed database, and operations failed deep inside code with unclear errors.

Teardown ran on every close() call. Concurrent calls ran multiple teardown sequences in parallel. A failed teardown was reported as success, and dirty items could be lost. A stalled sync peer blocked close() until the network timeout fired.

What changed

State machine replaces the ready boolean

GoatDB.state is now an explicit state machine:

  • booting
  • ready
  • closing
  • closed
  • failed

isOpen derives from state and reports whether the instance accepts work. state === 'ready' replaces ready as the readiness check. Each transition emits a LifecycleChanged event.

Public operations fail closed

Public data operations reject with serviceUnavailable when the instance is not open. Guards run at the API boundary in GoatDB and ManagedItem:

  • count(), keys(), getTrustPool(), logout()
  • set(), delete(), and mutator setters on items

Errors surface at the boundary instead of inside a repository.

close() is single-flight and idempotent

close() returns the same promise for every concurrent call. A single teardown runs. Repeated calls are safe.

Failed teardown is retryable

A failed close() moves the instance to failed and rejects. A later close() retries the remaining teardown. On success, the instance settles at closed. No partial teardown is reported as success.

Sync aborts on close

SyncScheduler carries an AbortController. close() aborts the in-flight batch-sync fetch, so teardown does not wait on a stalled peer. Abort is cancellation, not a peer fault, so it is not logged as a sync error. RepoClient suppresses SerializeError logs while closed.

Dirty items persist during close

Teardown commits dirty items through _commitForClose() and _acquireRepoForClose(). These internal paths bypass the public guards during the closing state. If a commit fails, the item stays dirty for a retry, and the trust pool is preserved.

React hook maps lifecycle events

useDBReady() subscribes to LifecycleChanged through useSyncExternalStore. It maps closed and failed states to error, and ready to a ready signal.

Tests

New coverage exercises state transitions, fail-closed guards, single-flight close, retryable failed teardown, sync abort, and React hook behavior. Failure injection helpers simulate commit and file-close failures.

Impact

  • Users of ready migrate to state === 'ready'.
  • Post-close operations now throw serviceUnavailable instead of failing silently.
  • close() is deterministic: one teardown, no leaks, no hangs on stalled peers.
  • Failed teardown is recoverable without data loss.
  • React consumers see a correct error state after close or failure.

Fixes #94

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

debt: GoatDB instance has no closed state

1 participant