Organization-Level Configuration Overrides

[dakshina99]

What

Every platform-api setting is one value for the whole deployment: it comes from
config.toml (or a {{ env }} token) and applies identically to every
organization. Some settings need to differ per organization. The first concrete
case is deployments.max_builds_per_api — how many builds an API may keep —
where different organizations are entitled to different limits. Today the only
way to express that is a code change or a separate deployment.

This proposes one generic override layer: an organization may carry a value for a
declared subset of config keys, and when it does, that value wins over the
file. Nothing else about configuration changes, and a deployment that sets no
overrides behaves exactly as it does now.

Precedence

organization row   (organization_configurations)   ← highest
config file        (config.toml, {{ env }} token)
built-in default   (config.DefaultConfig)          ← lowest

Keys are the same dotted paths the file already uses
(deployments.max_builds_per_api), so both sources share one key space and
precedence needs no mapping between them.

Table

CREATE TABLE IF NOT EXISTS organization_configurations (
    uuid              VARCHAR(40) PRIMARY KEY,
    organization_uuid VARCHAR(40) NOT NULL,
    config_key        VARCHAR(200) NOT NULL,
    config_value      TEXT NOT NULL,
    updated_by        VARCHAR(200),
    created_at        TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    updated_at        TIMESTAMPTZ DEFAULT CURRENT_TIMESTAMP,
    UNIQUE (organization_uuid, config_key),
    FOREIGN KEY (organization_uuid) REFERENCES organizations(uuid) ON DELETE CASCADE
);

Key/value rows rather than a column per setting: making a new setting
overridable is then a registry entry, not a schema migration. Values are stored
as text and parsed against the type the registry declares.

Registry — what may be overridden

Not every setting may be. database.password, security.encryption_key,
listener ports and the auth configuration are properties of the deployment; an
organization-scoped write to any of them is an escalation, not a preference. So
overridable keys are declared, and anything not declared is refused — an
allowlist, not a denylist:

var Overridable = map[string]Definition{
    "deployments.max_builds_per_api": {Type: TypeInt, Min: 1, Max: 50},
}

The definition carries the type and its bounds, so a bad value is rejected at the
write rather than discovered at the read, where there is nothing sensible to do
with it.

Reading it

Resolution goes through one seam, so no call site can reach for cfg.X and an
override at the same time and get a different answer than its neighbour:

// Falls back to the file value, then the built-in default.
limit := s.orgCfg.Int(orgUUID, config.KeyMaxBuildsPerAPI)

These reads sit on hot paths — every build and every deploy — so the resolver
caches per organization with a short TTL. platform-api runs multiple replicas, so
a write cannot invalidate its peers' caches; a TTL bounds how long a stale value
can be in force instead of pretending the problem does not exist.

REST

GET    /organizations/{organizationId}/configurations         this org's overrides, and each key's effective value
PUT    /organizations/{organizationId}/configurations/{key}   set one    { "value": "5" }
DELETE /organizations/{organizationId}/configurations/{key}   revert to the platform value

New scopes ap:organization:config:read and ap:organization:config:manage,
alongside the existing ap:organization:*. The listing reports each key's
effective value and its source (organization or platform), so a console can
show what is actually in force without knowing anything about the config file.

Scope of the first PR

• The table, the registry, the resolver and the three routes.
• One registered key, deployments.max_builds_per_api, switched to resolve
  through the resolver instead of reading the config struct directly.

Every other setting keeps reading the file until it is registered, so the change
is additive.

Open questions

• Should DELETE of an unset key be a 404 or a no-op 204?