registrystack / registrystack/registry-stack

Define and prove supported high-availability topologies

Open
#507 0 comments 0 reactions 0 assignees View on GitHub
area:docs area:notary area:platform area:relay enhancement post-1.0 triage:roadmap
Dominant language
Rust
Stars
2
Forks
0
Avg merge
2h 55m
Merged PRs (30d)
130

Description

## Outcome

Registry Stack documents and proves the exact Relay and Notary topologies that remain correct during replica, process, node, and dependency failures. High availability is claimed only for profiles with repeatable failure and recovery evidence.

Roadmap default: 1.2. Reprioritize only when a release-scoped deployment requirement mandates an availability target that cannot be met by the supported single-node profile.

Kubernetes packaging alone is not evidence of high availability.

## Design checkpoint

For each product and state mode, decide:

- supported replica count and active/active, active/passive, or single-writer behavior;
- PostgreSQL topology, transaction, locking, fencing, migration, and failover assumptions;
- cache, materialization, generation, anti-rollback, signing, replay, quota, and audit ownership;
- load-balancer and traffic-admission requirements;
- readiness behavior during partial failure and mixed generation;
- configuration rollout, signer rotation, schema migration, rollback, and fix-forward behavior;
- backup, restore, stale-restore quarantine, regional failure, and disaster-recovery boundaries; and
- which availability, RPO, and RTO values are product evidence versus institution-owned targets.

## Security and correctness invariants

- Replicas cannot create split-brain signing, duplicate issuance, conflicting anti-rollback state, divergent policy, or incomplete audit history.
- No replica serves traffic until its exact bundle, schema, dependencies, and generation are verified.
- Load balancing and network policy do not replace product authentication, authorization, or fencing.
- Removing a failed replica must not require deleting correctness state, audit state, or anti-rollback evidence.
- A failed rollout cannot admit traffic to an incompatible Relay/Notary combination.

## Definition of Done

- [ ] A public topology matrix names every supported and unsupported Relay, Notary, and combined deployment shape.
- [ ] The matrix distinguishes availability of stateless request handling from correctness-state, audit, signing, source-refresh, and database availability.
- [ ] Repeatable tests cover process kill, pod or container replacement, node loss, network partition, database primary loss, slow dependency, stale replica, mixed configuration generation, signer failure, and recovery.
- [ ] Multi-instance Notary evidence proves single-consumption, replay, nonce, issuance, status, and signing correctness under concurrency and failover.
- [ ] Multi-instance Relay evidence proves refresh, dispatch, quota, materialization, consultation, audit, and generation correctness under concurrency and failover.
- [ ] Upgrade, schema migration, rollback boundary, backup, restore, and stale-restore quarantine are exercised for every supported topology.
- [ ] Resource, connection-pool, disruption-budget, termination, and readiness guidance is measured rather than guessed.
- [ ] Documentation states institutional responsibilities for cluster, load balancer, database service, network, backup custody, DR, monitoring, and incident response.
- [ ] No general HA claim remains where only happy-path replicas were tested.

## Non-goals

- Building a Kubernetes operator or database service.
- Promising a universal SLA, RPO, or RTO.
- Requiring a service mesh.
- Treating a multi-replica Deployment as sufficient evidence.

## Related work

- #203
- #226
- #361
- #497
- #501

Contributor guide

Open the contributing guide

Research direction

Start with the design checkpoint, Definition of Done, and related issues #203, #226, #361, #497, and #501; then inventory the existing Relay and Notary deployment and test entry points. Define the supported topology matrix and failure scenarios before implementing repeatable evidence for concurrency, failover, upgrades, restore, and readiness. Done means unsupported claims are removed and every supported topology has measured correctness and recovery evidence.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes, postgresql, rust
Domain
databases, devops, distributed-systems, security, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.