mirror of
https://github.com/mulgadc/spinifex.git
synced 2026-10-19 10:52:04 +00:00
docs: record RDS engine catalogue boundary and evidence
This commit is contained in:
@@ -294,6 +294,8 @@ while the branch is in flight; they do not describe the umbrella repository's
|
||||
| `544b0c6a0` | `spinifex/handlers/ecs` (`TaskDefRecord`, `ContainerDef`, `TaskDefRevKey`, `TaskDefLatestRevKey`, `ParseTaskDefRef`, `TaskDefARN`, `TaskDefRefARN`, revision register/deregister/resolve/list) | `spinifex/domains/ecs/taskdefinition` (`Owner`, `Record`, `Container`, `PortMapping`, `SystemControl`, `ParseRef`, `ARN`, `RefARN`, keys) | ADR-0004 owner extraction (ADR-0003 S1 contract in `docs/package-boundary/ecs-task-definition-lifecycle.md`). Stored keys and JSON field names unchanged; the owner declares its own persisted `PortMapping`/`SystemControl` so it does not import `handlers/ecs/bus`. Launches use the launch-side `taskDefinitionResolver`; gateway authz and all `iam:PassRole` checks unchanged. `docs/service-interfaces.yaml` now lists `spinifex/handlers/ecs` and the new package under `spinifex_daemon`. Proves ownership and dependency direction only; no conformance claimed. |
|
||||
| `b36d70b22` | — | — | EKS access entry characterization before extraction (ADR-0003 S1, ADR-0004): persisted and nested field names, pre-existing JSON decodes, actions ignore cluster status, associate without an entry is not found, disassociating an unbound policy is a no-op, an empty update keeps username and groups, cluster delete sweeps only that cluster's entries, token review needs no cluster record. Present contract and gaps in `docs/package-boundary/eks-access-entry-lifecycle.md`; no conformance claimed. |
|
||||
| `68ee6f620` | `spinifex/handlers/eks` (`AccessEntryRecord`, `AssociatedAccessPolicy`, `AccessScope`, `AccessEntriesPrefix`, `AccessEntryKey`, `PrincipalARNHash`, access-entry KV helpers, policy catalogue, `effectiveGroups`, the access mutation logic) | `spinifex/domains/eks/access` (`Owner`, `Record`, `AssociatedPolicy`, `Scope`, `Spec`, `Get`, `List`, `Key`, `Prefix`, `PrincipalARNHash`, `SupportedPolicies`, `EffectiveGroups`) | ADR-0004 owner extraction (ADR-0003 S1 contract in `docs/package-boundary/eks-access-entry-lifecycle.md`). Stored keys and JSON field names unchanged; writes go only through `Owner`, including the creator-admin seed at cluster launch. The handler keeps AWS validation, the cluster existence check, error mapping and projection; gateway authz switches only its hash import. `docs/service-interfaces.yaml` now lists `spinifex/handlers/eks` and the new package under `spinifex_daemon`. Proves ownership and dependency direction only; no conformance claimed. |
|
||||
| `955486421` | — | — | RDS engine catalogue characterization before extraction (ADR-0004): family normalisation, exact error codes, per-parameter agent metadata, internal-fault outcomes, recovery text, reference class. Static metadata, so no ADR-0003 lifecycle contract; boundary and evidence note in `docs/package-boundary/rds-engine-catalogue-boundary.md`. |
|
||||
| `f1f194b16` | — | — | Discovered and corrected during the catalogue characterization: a missing `MasterUserPassword` on `CreateDBInstance` returned HTTP 500 `ServerInternal`; it now returns 400 `InvalidParameterValue`, covered through the gateway by `gateway/rds_test.go` `TestRDSRequest_CreateDBInstance_EmptyMasterUserPasswordReturns400`. |
|
||||
|
||||
The EC2 contract row is intentionally different from the directory moves: it creates
|
||||
a compatibility boundary. `ec2.cmd.*` retains its deployed one-token NATS
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# RDS engine catalogue: boundary and evidence
|
||||
|
||||
The engine catalogue is static, process-local metadata: engine identity and versions, parameter-group families, the parameter catalogue and effective-parameter resolution, and `db.*` instance classes.
|
||||
It has no durable state and no realization, so it has no ADR-0003 lifecycle contract; this note records its boundaries and the behaviour pinned before it moves.
|
||||
Paths are relative to `spinifex/` unless they start with `tests/`.
|
||||
|
||||
## Pinned behaviour
|
||||
|
||||
`handlers/rds/engine_catalogue_characterization_test.go`, alongside the existing `engine_test.go`, `engine_mariadb_test.go`, `enginefamily_test.go`, `paramcatalog_test.go`, `sizing_test.go` and `catalog_test.go`:
|
||||
|
||||
- Family lookup ignores case and surrounding whitespace; an unknown family, a product name such as `PostgreSQL`, and an unsupported version return exactly `InvalidParameterValue` (`TestEngineForFamily_NormalisesCaseAndWhitespace`, `TestEngineForFamily_RejectsUnknownFamily`, `TestLookupEngine_RejectsProductNameWithExactCode`, `TestEngineValidateVersion_UnsupportedVersionCarriesExactCode`).
|
||||
- Master password rejections resolve to `InvalidParameterValue` with fixed messages (`TestValidateMasterUserPassword_ExactCodesAndMessages`).
|
||||
- Per engine and parameter, the option-file name, data type and static or dynamic apply type the guest agent relies on (`TestCatalogueAgentContractMetadata_MatchesGoldenTable`).
|
||||
- Internal faults return `ServerInternal`: an engine with no combination check, and a combination check reading a key the catalogue does not define (`TestResolveEffectiveParameters_NoCombinationCheckIsServerInternal`, `TestResolveEffectiveParameters_CombinationCheckMissingKeyIsServerInternal`).
|
||||
- The exact unclean-stop and crash-consistent snapshot recovery text per engine (`TestUncleanStopMessage_PinsExactTextPerEngine`, `TestCrashConsistentSnapshotMessage_PinsExactTextPerEngine`).
|
||||
- The reference class for reported parameter defaults is `db.t3.micro` at 1024 MiB (`TestSmallestInstanceClass_MemoryIsExactlyOneGiB`).
|
||||
|
||||
## Discovered and corrected divergence
|
||||
|
||||
`ValidateMasterUserPassword` built its empty-password error with a bare `errors.New`, which `awserrors` does not resolve, so `CreateDBInstance` without `MasterUserPassword` returned HTTP 500 `ServerInternal` where AWS returns a 400 client error.
|
||||
It now returns 400 `InvalidParameterValue`; `gateway/rds_test.go` `TestRDSRequest_CreateDBInstance_EmptyMasterUserPasswordReturns400` covers the gateway, NATS and RDS service path.
|
||||
|
||||
## Boundaries the owner move must keep
|
||||
|
||||
1. EC2 instance-type memory reaches the catalogue only through an immutable `Sizing` value built from a catalogue-declared `InstanceTypes` interface, backed by the fixed `domains/ec2/instancetypes` table at composition. The catalogue does not import an EC2 package, and `Sizing` is a static projection, never a route to live node availability; `DescribeOrderableDBInstanceOptions` keeps its caller-supplied runnable check in the gateway.
|
||||
2. The guest agent consumes engine metadata through a narrow interface and input/output shapes it declares itself, with an engine-backed implementation supplied by `cmd/rds-agent`. The agent does not import the catalogue package; if that injection cannot be added without a larger composition design, its existing `handlers/rds` dependency stays as recorded debt.
|
||||
3. Effective parameters leave the catalogue as an engine-owned `Setting{Name, Value}`, converted to `handlers/rds.Parameter` at the adapter; `Parameter` is not moved or aliased.
|
||||
4. AWS output building (`describeVersion`, `orderableOption`), paging, `ApplyMethod*`/`ParameterSource*`, the gateway runnable check and the storage limits stay in the existing adapter path.
|
||||
Reference in New Issue
Block a user