Documentation
¶
Overview ¶
Package demo implements the BubbleFish Nexus reliability demo — the golden crash-recovery scenario that proves WAL-first durability.
The demo writes 50 memories with unique idempotency keys, kills the daemon via SIGKILL, restarts it, waits for readiness, queries all memories, and asserts exactly 50 results with 0 duplicates.
Reference: Tech Spec Section 13.3, Phase R-26.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Options ¶
type Options struct {
// URL is the base URL of the running Nexus daemon. When empty, the demo
// runner starts and manages its own daemon process.
URL string
// Source is the source name for write requests.
Source string
// Destination is the destination name for query requests.
Destination string
// APIKey is the data-plane API key.
APIKey string
// AdminKey is the admin token (used for /ready check and cleanup).
AdminKey string
// Keep prevents cleanup of demo data after the run.
Keep bool
// Logger for structured output.
Logger *slog.Logger
}
Options configures a reliability demo run.
type Result ¶
type Result struct {
// TotalWritten is the number of writes attempted.
TotalWritten int `json:"total_written"`
// TotalRecovered is the number of records found after crash recovery.
TotalRecovered int `json:"total_recovered"`
// Duplicates is the count of duplicate payload_ids in the result set.
Duplicates int `json:"duplicates"`
// MissingKeys lists idempotency keys that were not recovered.
MissingKeys []string `json:"missing_keys,omitempty"`
// Pass is true when all assertions hold.
Pass bool `json:"pass"`
// DurationMs is the total wall-clock time of the demo.
DurationMs float64 `json:"duration_ms"`
}
Result holds the outcome of a reliability demo run.
func Analyse ¶
func Analyse(results []struct {
PayloadID string `json:"payload_id"`
IdempotencyKey string `json:"idempotency_key"`
}, expectedIDs map[string]string) *Result
Analyse checks the query results against the expected idempotency key set. Exported for unit testing.
func Run ¶
Run executes the reliability demo. If opts.URL is empty, it starts a managed daemon process and performs the SIGKILL simulation. If opts.URL is set, it uses the existing daemon (no process management — suitable for the HTTP endpoint variant where the daemon manages itself).
func RunInProcess ¶
func RunInProcess(url, source, destination, apiKey, adminKey string, logger *slog.Logger) (*Result, error)
RunInProcess executes the demo against a daemon at the given URL. This is used by the /api/demo/reliability handler where the daemon is already running. No SIGKILL simulation — this variant only verifies the write-query round-trip works correctly (useful as a smoke test or for dashboard display).
Source Files