Aegis Gateway 2.0

PostgreSQL shared governance state

What it means and why you need it

Some Aegis rules need a memory that outlives a single request:

Aegis calls that memory its governance state, and state.type decides where it lives:

state.type Where the memory lives Survives a restart Shared by several gateway processes
memory inside the one gateway process no no
derby-local an embedded Derby database on local disk yes no (one process only)
postgres one PostgreSQL database that every replica uses yes yes

With one gateway process, memory or derby-local is enough. As soon as two or more gateway processes serve the same users (high availability, several Kubernetes replicas, a rolling upgrade where old and new pods overlap), each process would otherwise keep its own memory, and the rules break between them:

state.type: postgres puts that memory in one database and uses PostgreSQL transactions, so exactly one replica wins each single-use token and every replica counts against the same window. That is why the Helm chart refuses to render more than one replica without shared state. Use it whenever more than one Aegis process governs the same tools.

How the provider works

aegis-state-postgres is the shared-state provider for Aegis deployments with more than one replica. It is selected with state.type: postgres. It uses PostgreSQL transactions and database constraints for the state operations that cannot be safely split by gateway replica:

It is a real PostgreSQL JDBC provider. It does not use a cache, mock database, filesystem lock, or JVM-wide synchronization to provide cross-replica correctness.

Why PostgreSQL, not Derby

derby-local remains the no-server durable option for one Aegis process. Derby embedded locking prevents a second writable process from sharing it. It is deliberately not an active-active store.

PostgreSQL provides the required multi-process primitives: unique primary keys, INSERT ... ON CONFLICT, row locks, transactions and DELETE ... RETURNING. Aegis uses those primitives so one replica wins a nonce/take race and a rejected rate acquisition does not consume capacity.

Configuration

The provider is bundled in the own-host Aegis JAR and in the Knox bundle. Credentials are referenced by environment-variable name; do not put their values in YAML.

state:
  type: postgres
  settings:
    jdbcUrl: jdbc:postgresql://postgres.internal.example:5432/aegis?sslmode=verify-full
    usernameEnv: AEGIS_STATE_DB_USER
    passwordEnv: AEGIS_STATE_DB_PASSWORD
    namespace: production-gateway
    connectTimeoutSeconds: 10

Settings:

Setting Required Meaning
jdbcUrl yes PostgreSQL JDBC URL. Use TLS certificate verification in production (sslmode=verify-full).
usernameEnv yes Environment-variable name holding the database role name.
passwordEnv yes Environment-variable name holding the role password.
namespace yes 1 to 128 letters, digits, ., _, or -. Gateways share state only when database and namespace match.
connectTimeoutSeconds no 1 to 120 seconds; default 10.

The database role must be configured outside Aegis. Use a dedicated database or schema and a least-privilege role. The provider creates its two idempotent tables on first use, so the migration role needs CREATE initially; a production deployment may pre-create the tables and grant the runtime role only SELECT, INSERT, UPDATE, and DELETE on them.

Schema and transaction model

The provider creates two namespaced tables:

aegis_state(namespace, state_key, state_value, expires_at_ms)
aegis_window(namespace, window_key, window_start_ms, used_value)

Both have (namespace, key) primary keys. The provider opens one short transaction per StateStore operation:

The API does not turn independent engine steps into one distributed transaction. For example, the engine consumes an approval/receipt before backend execution and writes audit intent before execution. A database outage therefore fails closed and may burn a one-time artifact; retrying it would weaken single-use semantics.

Own-host deployment

The stock aegis-gateway-...-all.jar carries aegis-state-postgres, pgJDBC and its ServiceLoader registration. Set AEGIS_STATE_DB_USER and AEGIS_STATE_DB_PASSWORD in the gateway process environment, then run the usual own-host command.

java -jar aegis-gateway/target/aegis-gateway-2.0.0-SNAPSHOT-all.jar --config aegis.yaml

Apache Knox deployment

The aegis-knox3-extension shaded bundle includes the PostgreSQL provider and pgJDBC without including any Apache Knox implementation classes. Set the same environment variables on the Knox gateway process. The topology continues to authenticate/authorize at the edge; PostgreSQL changes only the shared Aegis governance state behind that front door.

What PostgreSQL does not solve

Real integration validation

PostgresStateStoreIT uses two independent provider instances against one real PostgreSQL service. It checks exactly-one nonce winner, globally single-use take, cross-instance fixed-window capacity, rejected-cost non-charging, expiry/reopen persistence, and factory credential resolution from environment names. It runs only in the integration profile:

export AEGIS_POSTGRES_URL='jdbc:postgresql://127.0.0.1:55432/postgres?sslmode=disable'
export AEGIS_POSTGRES_USER='aegis_state'
export AEGIS_POSTGRES_PASSWORD='local-development-password'
mvn -B -Ppostgres-integration -pl aegis-state-postgres -am test

sslmode=disable is only for an isolated loopback development server. It is not a production example. If the variables are absent, the integration test is skipped and must never be reported as passed.

TwoGatewayProcessesPostgresIT in aegis-gateway goes one level up: it starts two gateway JVMs with Main --config, both pointing at one namespace, and drives them over HTTP. An approval requested on one replica is decided on the other, the approved delete runs once, the replay on the first replica is refused, and one rate window covers both. Run it with the same variables:

mvn -B -Ppostgres-integration -pl aegis-gateway -am verify \
  -Dtest=TwoGatewayProcessesPostgresIT -Dsurefire.failIfNoSpecifiedTests=false

Retained runs: temporary managed PostgreSQL, provider and two-gateway levels and PostgreSQL 17.6, two gateway processes.