[Proposal] Separate API-Facing Resource Types from Internal Runtime Model in Gateway Controller

[renuka-fernando]

Summary

Refactor the gateway controller's internal model to cleanly separate API-facing resource types (used for REST API communication and persistence) from internal runtime types (used for Envoy and Policy Engine configuration via xDS). The core changes are:

• Introduce an ephemeral RuntimeConfig struct as the canonical internal representation for all deployable resources, replacing the current pattern of forcing every resource into APIConfiguration
• Define a DeployableResource Go interface with Kind() and Handle() methods that all resource configuration types implement
• Redesign the Transformer interface to connect DeployableResource (input) to RuntimeConfig (output), with a Kind-keyed registry and per-resource-type implementations in a dedicated pkg/transformer/ package
• Unify three separate deployment services (APIDeploymentService, LLMDeploymentService, MCPDeploymentService) into a single pipeline that dispatches via the Kind registry
• Rename StoredConfig to Deployment; merge the deployments + deployment_configs two-table schema into a single table with a discriminated resource_config JSON column
• Replace UNIQUE(display_name, version, gateway_id) identity with UNIQUE(gateway_id, kind, handle) — handle-based identity eliminates the {displayName}:{version} composite key pattern
• Wrap deployment persistence and transformation in SQLite transactions, replacing the current best-effort DB-then-memory write with rollback attempt
• Replace the flat in-memory map[string]*StoredConfig (O(n) kind lookups) with a two-level Kind → Handle → RuntimeConfig map
• Implement ordered startup loading with dependency resolution (independent resources before dependent ones)
• Update the existing config_dump admin endpoint to return RuntimeConfig state organized by Kind and Handle

The external REST API contract remains fully backward compatible. Breaking changes are limited to the database schema and internal implementation.

Motivation

The Problem: Everything Is Forced Into APIConfiguration

Today, the gateway controller handles five resource types -- REST APIs, LLM providers, LLM proxies, MCP proxies, and WebSub APIs -- but all of them are forced through a single APIConfiguration struct before storage and xDS translation.

Here is the current StoredConfig struct (from pkg/models/stored_config.go):

type StoredConfig struct {
    ID                  string               `json:"id"`
    Kind                string               `json:"kind"`
    Configuration       api.APIConfiguration `json:"configuration"`
    SourceConfiguration any                  `json:"source_configuration,omitempty"`
    Status              ConfigStatus         `json:"status"`
    // ...
}

And the current Transformer interface (from pkg/utils/transformer.go):

type Transformer interface {
    Transform(input any, output *api.APIConfiguration) (*api.APIConfiguration, error)
}

This creates several concrete problems:

1. Semantic loss. An LLM provider is not a REST API. Forcing it into APIConfiguration strips away its meaning -- access control modes (allow_all/deny_all), provider templates, and model-level configuration become invisible to the internal model. The transformer must reconstruct API-shaped constructs (fake operations, synthetic routes) to carry non-API concepts through a struct that was never designed for them.

2. Unsafe type assertions everywhere. The SourceConfiguration any field requires interface{} type assertions scattered across REST handlers and storage code. A typo or wrong assertion produces runtime panics, not compile-time errors. Every handler that returns a non-REST-API resource must cast SourceConfiguration to the correct type manually.

3. No compile-time type safety for dispatch. The transformer accepts any as input. There is no Go compiler enforcement that a resource type provides the right data or that the correct transformer is used. Dispatch relies on string-based Kind matching with manual switch statements.

4. Fragile identity model. Resources are identified by a {displayName}:{version} composite key (GetCompositeKey()) that requires extracting display name and version from deeply nested spec data, with special-case handling for WebSub APIs. This composite key leaks API-level concepts into every layer.

5. Split-table storage confusion. The database splits a single logical entity across two tables: deployments (metadata: display_name, version, kind, handle, status) and deployment_configs (payload: configuration as APIConfiguration, source_configuration as any), joined by a shared primary key. This 1:1 split adds unnecessary complexity and the dual payload columns create ambiguity about which is the source of truth.

6. Duplicated deployment pipelines. Three separate deployment services (APIDeploymentService, LLMDeploymentService, MCPDeploymentService) each duplicate the parse → validate → transform → save flow. REST APIs skip transformation entirely since APIConfiguration is already the target type. Adding a new resource kind requires creating yet another deployment service with the same boilerplate.

7. Non-transactional persistence. The current saveOrUpdateConfig() writes to the DB then to the in-memory store sequentially. On DB failure, it attempts a best-effort memory rollback — not a true atomic operation. Multiple controller instances sharing the same database can observe inconsistent state.

Why This Matters Now

The platform is expanding beyond REST APIs. LLM providers, LLM proxies, and MCP proxies are first-class resource types with their own semantics, but the internal model treats them as second-class citizens that must disguise themselves as REST APIs. Every new resource type added under the current design increases the surface area of unsafe type assertions, deepens the semantic mismatch, and makes the codebase harder to reason about. This is the right time to establish a clean internal model before the resource type count grows further.

Proposal

1. RuntimeConfig: The Canonical Internal Representation

A new RuntimeConfig struct replaces APIConfiguration as the internal model consumed by the xDS translator. It is resource-agnostic -- it describes what Envoy and the Policy Engine need, not what the original resource type was.

RuntimeConfig
  - Kind                  (discriminator: "RestApi", "LlmProvider", ...)
  - Handle                (resource identity within a Kind)
  - UpstreamConfig        (cluster URLs, auth, load balancing)
  - ListenerConfig        (listener/vhost settings)
  - TLSConfig             (TLS settings)
  - Routes                (map[string]RouteConfig -- route ID to config)
      RouteConfig
        - ID              (self-describing route identity)
        - Path
        - Method
        - Policies         (merged per-route policy chain)
        - Metadata         (route-level metadata)

Key design properties:

• Ephemeral. RuntimeConfig is held only in the in-memory ConfigStore, never persisted to the database. It is derived from stored resources at deployment time and rebuilt from stored resources on startup. This means the original API resource is always the single source of truth, RuntimeConfig struct changes between controller versions do not require database migrations, and there is no risk of derived data drifting out of sync.

• Embedded sub-structs. Rather than a flat struct with dozens of fields, RuntimeConfig uses logical groupings (UpstreamConfig, TLSConfig, ListenerConfig) so functions can accept only the subset they need.

• Per-route policy chains only. There is no distinction between "API-level" and "operation-level" policies at the RuntimeConfig level. The transformer merges all policy sources into per-route chains before placing them into RuntimeConfig. At the Router and Policy Engine, everything is route-level.

• No resource-specific fields copied as-is. LLM access control modes, provider template references, and model-level configuration are transformed into per-route policies and route metadata by the transformer. RuntimeConfig holds derived configuration, not a mirror of the source.

• In-memory ConfigStore uses a two-level map (Kind -> Handle -> RuntimeConfig) for O(1) lookup by (Kind, Handle) and O(1) enumeration of all resources of a given Kind. This replaces the current flat map[string]*StoredConfig which requires O(n) scans for GetAllByKind() and GetByKindAndHandle().

• config_dump endpoint. The existing admin API config_dump endpoint (port 9092) is updated to return RuntimeConfig state from the ConfigStore, organized by Kind and Handle, instead of the current APIConfiguration-based format.

2. DeployableResource: A Common Interface for All Resource Types

A DeployableResource Go interface provides compile-time type safety for all resource types entering the deployment pipeline:

type DeployableResource interface {
    Kind() string         // "RestApi", "LlmProvider", "LlmProxy", "Mcp", "WebSubApi"
    Handle() string       // metadata.name -- THE resource identity
}

All five resource configuration types implement this interface: APIConfiguration (RestApi), LLMProviderConfiguration (LlmProvider), LLMProxyConfiguration (LlmProxy), MCPProxyConfiguration (Mcp), and a new WebhookAPIConfiguration (WebSubApi). Note: WebhookAPIConfiguration does not exist today as a standalone type — WebSubApi currently uses APIConfiguration with a union pattern (Spec.AsWebhookAPIData()). A thin wrapper type will be introduced.

The interface is intentionally minimal -- only what the deployment pipeline needs for identification. Name(), Version(), and Translator() are deliberately excluded: display names and version information remain accessible from each concrete type's spec data but are not part of the common interface contract. Translator() was considered but rejected (see Alternatives) -- transformer dispatch uses a Kind-keyed registry instead. Handle (from metadata.name) is the sole resource identity. The {displayName}:{version} composite key pattern is eliminated entirely.

Since these types are OpenAPI-generated (in api/generated/generated.go), the interface method implementations are placed in separate Go source files (e.g., api_configuration_deployable.go, llm_provider_configuration_deployable.go) so they survive code regeneration.

3. Redesigned Transformer: DeployableResource to RuntimeConfig

The Transformer interface is redesigned with typed input and output:

// Current (pkg/utils/transformer.go)
type Transformer interface {
    Transform(input any, output *api.APIConfiguration) (*api.APIConfiguration, error)
}

// Proposed (pkg/transformer/)
type Transformer interface {
    Transform(resource DeployableResource) (RuntimeConfig, error)
}

Each resource type gets a dedicated Transformer implementation:

Resource Kind	Transformer	Responsibilities
RestApi	RestApiTransformer	Map operations to routes, merge API/operation policies into per-route chains, resolve upstreams (new — REST APIs currently skip transformation since APIConfiguration is already the target type)
LlmProvider	LlmProviderTransformer	Translate access control modes and model config into per-route policies, resolve provider upstream
LlmProxy	LlmProxyTransformer	Resolve referenced LLM provider from DB, configure loopback routing
Mcp	McpTransformer	Map MCP endpoints to routes with appropriate policies
WebSubApi	WebSubApiTransformer	Map webhook subscriptions to routes

Dispatch uses a Kind-keyed transformer registry (map[string]Transformer) initialized at startup. The deployment pipeline looks up the transformer via transformers[resource.Kind()]. This is a simple, explicit dispatch mechanism that avoids the problems of embedding infrastructure references in data structs (see Alternatives).

Each Transformer is a singleton per Kind, constructed once with a reference to the storage layer (constructor injection). Within the Transform method, transformers can query the database to resolve cross-resource references (e.g., LLM proxy resolving its referenced provider).

All transformer code moves from pkg/utils/ (a catch-all package) to a dedicated pkg/transformer/ package.

4. Deployment: Renamed Storage with Discriminated JSON

StoredConfig is renamed to Deployment (aligning with the existing deployments table name). The two-table pattern is merged into a single table with a discriminated JSON column:

Before:
  deployments table
  - id, gateway_id, display_name, version, context, kind, handle, status, ...
  UNIQUE(display_name, version, gateway_id)
  UNIQUE(handle, gateway_id)

  deployment_configs table  (1:1 with deployments, shared PK)
  - configuration (JSON: APIConfiguration -- always)
  - source_configuration (JSON: any -- original resource)

After:
  deployments table  (single table)
  - kind (TEXT: "RestApi" | "LlmProvider" | ...)
  - handle (TEXT: metadata.name)
  - resource_config (JSON: typed per Kind)
  UNIQUE(gateway_id, kind, handle)

The deployment_configs table is eliminated — no reason for a 1:1 split. The Kind field determines deserialization type at load time — no any or interface{} required. The UNIQUE(display_name, version, gateway_id) constraint is replaced by UNIQUE(gateway_id, kind, handle). Handles can be duplicated across different Kinds (an LLM provider and an LLM proxy may both be named "my-service"), so kind is part of the uniqueness constraint.

Deployment persistence and transformation are wrapped in a SQLite transaction. If the Transformer returns an error, the transaction rolls back -- no partially deployed resources remain in the database. This is critical because multiple controller instances may share the same database.

5. Ordered Startup with Dependency Resolution

On startup, the controller loads resources from the database and transforms them into RuntimeConfig instances. Resources are loaded in dependency order:

1. Independent resources first: LLM providers, REST APIs, MCP proxies, templates
2. Dependent resources second: LLM proxies (which reference LLM providers for upstream resolution)

If a dependent resource references a missing dependency, it is marked as failed with a clear error message. Other resources continue loading normally.

6. REST API Backward Compatibility

The external REST API contract is preserved exactly as-is. Each resource type's API-facing struct (APIConfiguration, LLMProviderConfiguration, etc.) continues to serve REST request/response payloads. REST GET handlers read the original resource configuration from the database (deserialized using the Kind discriminator), not from the in-memory ConfigStore. The ConfigStore holds only RuntimeConfig.

Architecture Diagram

flowchart TD
    A["REST API Layer
    POST /apis, /llm-providers, ..."] -->|parse & validate| B["DeployableResource
    .Kind() .Handle()"]

    subgraph TX ["SQLite Transaction"]
        direction TB
        P["Persist Deployment"] --> T["Transform"]
        T -->|rollback on error| P
    end

    B --> TX
    P --> C[("SQLite DB
    single deployments table
    UNIQUE(gateway_id, kind, handle)
    resource_config JSON")]
    B -->|lookup by Kind| D["Transformer Registry
    map[Kind]Transformer"]
    D --> T
    C -->|cross-resource lookups| D

    T -->|RuntimeConfig| F["In-Memory ConfigStore
    Kind → Handle → RuntimeConfig"]

    F --> G["xDS Translator
    reads only RuntimeConfig"]
    G --> H["Envoy + Policy Engine"]

    F -.->|GET /config_dump| I["Admin API
    port 9092"]

    style A fill:#4a90d9,color:#fff
    style C fill:#f5a623,color:#fff
    style TX fill:#f0f0f0,stroke:#999,stroke-dasharray: 5 5
    style F fill:#7ed321,color:#fff
    style H fill:#d0021b,color:#fff
    style I fill:#9b59b6,color:#fff

Loading

Alternatives Considered

Alternative 1: Store RuntimeConfig in the Database Alongside Original Resources

Persist both the original resource configuration and the derived RuntimeConfig in the database, so startup does not require re-transformation.

Rejected because: This creates a dual-source-of-truth problem. If transformation logic changes between controller versions, the stored RuntimeConfig becomes stale and must be migrated or invalidated. The startup cost of re-transformation is negligible for typical deployments (tens to low hundreds of resources), and the single-source-of-truth benefit of ephemeral RuntimeConfig significantly outweighs the sub-second startup cost.

Alternative 2: Translator() Method on DeployableResource

Add a Translator() Transformer method to the DeployableResource interface so each resource is self-describing and the pipeline calls resource.Translator().Transform(resource) with no registry needed.

Rejected because: Transformers are stateful singletons constructed with a DB reference. DeployableResource types are data structs deserialized from JSON -- they don't naturally hold infrastructure references. This would require injecting a Transformer into every deserialized config struct before use. It also creates a circular dependency risk (DeployableResource references Transformer which accepts DeployableResource), and complicates the separate-file strategy for OpenAPI-generated types. A Kind-keyed map is simpler, has no injection problem, no import cycle risk, and is trivially testable (swap the map entry in tests).

Alternative 3: Use Generics Instead of a Common Interface

Define Transformer[T DeployableResource] with generic type parameters so each transformer receives its concrete type directly.

Not rejected outright, but the current design favors the simpler interface-based approach. The deployment pipeline needs to work with heterogeneous resource types through a single code path. Generic transformers would require type-switch dispatch at some point, losing the benefit of the Kind-keyed registry pattern. If the Go generics story improves in a way that makes this cleaner, it can be revisited.

Impact Analysis

Benefits

• Type safety across the deployment pipeline. No any or interface{} type assertions in REST handlers or storage code. The Go compiler enforces that resource types implement the required interface.
• Clean separation of concerns. API-facing structs handle REST communication. RuntimeConfig handles internal processing. Neither knows about the other's details.
• Extensibility. Adding a new resource type requires implementing DeployableResource, creating a Transformer in pkg/transformer/, and adding a Kind constant. No changes to RuntimeConfig, xDS translator, or storage core logic.
• Simplified identity model. Handle-based identity (metadata.name) replaces the fragile {displayName}:{version} composite key everywhere.
• Unified deployment pipeline. A single pipeline dispatches to the correct Transformer via the Kind registry, replacing three separate deployment services (APIDeploymentService, LLMDeploymentService, MCPDeploymentService) that duplicate the same flow.
• True transactional deployment. SQLite transactions replace the current best-effort DB-then-memory write with rollback attempt on failure.
• Schema simplicity. A single deployments table with one resource_config JSON column replaces the current two-table split (deployments + deployment_configs) with dual payload columns.
• Version-resilient RuntimeConfig. Struct changes between controller versions take effect automatically on restart with no database migrations.

Risks and Mitigations

Risk	Mitigation
Database breaking change requires clean restart	Acceptable for current deployment model. No migration tooling needed.
Startup re-transformation cost	Negligible for typical deployments (sub-second for hundreds of resources). Monitored by SC-006 (less than 10% increase).
Transformation logic changes affect existing deployments on restart	Generally desirable (bug fixes apply retroactively). Documented as expected behavior.
Large surface area of code changes	Behavioral equivalence validated by all 46 existing BDD integration tests passing without modification (SC-001).

References

• Feature Specification: 007-controller-model-refactor -- Full requirements and acceptance criteria
• Current StoredConfig struct: gateway/gateway-controller/pkg/models/stored_config.go
• Current Transformer interface: gateway/gateway-controller/pkg/utils/transformer.go
• Current LLMTransformer: gateway/gateway-controller/pkg/utils/llm_transformer.go
• Current MCPTransformer: gateway/gateway-controller/pkg/utils/mcp_transformer.go
• Deployment services: gateway/gateway-controller/pkg/utils/api_deployment.go, llm_deployment.go, mcp_deployment.go
• xDS translator: gateway/gateway-controller/pkg/xds/translator.go
• DB schema: gateway/gateway-controller/resources/gateway-controller-db.sql
• Storage layer: gateway/gateway-controller/pkg/storage/sql_store.go
• In-memory store: gateway/gateway-controller/pkg/storage/memory.go
• Admin server (config_dump): gateway/gateway-controller/pkg/adminserver/server.go

---

Document Version: 1.0
Last Updated: 2026-02-24
Status: Proposed

[malinthaprasan]

RuntimeConfig
  - Kind                  (discriminator: "RestApi", "LlmProvider", ...)
  - Handle                (resource identity within a Kind)
  - UpstreamConfig        (cluster URLs, auth, load balancing)
  - ListenerConfig        (listener/vhost settings)
  - TLSConfig             (TLS settings)
  - Routes                (map[string]RouteConfig -- route ID to config)
      RouteConfig
        - ID              (self-describing route identity)
        - Path
        - Method
        - Policies         (merged per-route policy chain)
        - Metadata         (route-level metadata)

Having a small question:

For kinds like MCP, GraphQL etc where policy targets are derived from the payload rather than the URL path, how do we consider a "route" from Envoy vs Policy Engine perspective?.

MCP for example: Envoy would see a single route (e.g., POST /mcp), but the Policy Engine needs per-tool (or per-operation) granularity for policy attachment. The current RouteConfig struct has Path and Method, which looks similar to a HTTP-level routing.
How does the xDS Translator know which routes are meant for Envoy listener/route configuration vs. Policy Engine policies? Are we having a kind specific logic in translater that decides the routes for envoy and policy engine?