Skip to content

Add per-operation upstream override for REST API operations#2012

Open
mehara-rothila wants to merge 43 commits into
wso2:mainfrom
mehara-rothila:feat/per-op-upstream-gateway
Open

Add per-operation upstream override for REST API operations#2012
mehara-rothila wants to merge 43 commits into
wso2:mainfrom
mehara-rothila:feat/per-op-upstream-gateway

Conversation

@mehara-rothila

@mehara-rothila mehara-rothila commented May 22, 2026

Copy link
Copy Markdown
Contributor

Summary

Adds a per-operation upstream override on REST API operations: an operation can route its main and/or sandbox traffic to a different backend than the API-level upstream. Per-op targets are ref-only: each references a named entry in spec.upstreamDefinitions rather than carrying an inline URL. Operations without a per-op upstream fall back to the API-level upstream, exactly as before.

A per-op route reuses the referenced upstreamDefinition's cluster (one cluster per definition, so operations sharing a ref share it) rather than minting a cluster per operation. API-level main/sandbox cluster names are URL-stable (derived from a hash of the API's identity, not the URL). Both are URL-independent, so URL edits update Envoy endpoints in place instead of recreating clusters.

Why

Real-world APIs often need individual operations to reach different backend services. Today that needs path-based workarounds or splitting into multiple APIs. This lets the API definition declare per-operation routing directly, while backend URLs stay defined once in upstreamDefinitions and are referenced by name.

Design decisions

Ref-only at the operation level. operations[].upstream.main / .sandbox carry only a ref to a named upstreamDefinition, with no inline url and no per-target timeout/hostRewrite. Backends are declared once in spec.upstreamDefinitions; connect timeout lives on the definition. (API-level upstream still accepts either url or ref, unchanged.)

Per-op routes reuse the definition cluster. A per-op ref does not create a new cluster. It points the operation's route at the cluster the referenced upstreamDefinition already owns (upstream_<kind>_<apiID>_<defName>, built once per definition). N operations sharing a ref cost one cluster, not N, and the route inherits the definition's authoritative base path. cluster_header stays on with that cluster as the default, so a dynamic-endpoint policy can still override the operation (precedence: op-policy > api-policy > per-op ref > api-level upstream).

URL-stable API-level cluster naming. API-level main/sandbox cluster names derive from the first 12 bytes of sha256(apiID) (24 hex), via clusterkey.APILevelName(env, apiID), producing main_<fragment> / sandbox_<fragment>. The env is a plaintext prefix, not part of the hash, so main and sandbox share the same fragment. The URL is intentionally excluded, so a URL edit keeps the same cluster name and Envoy updates its endpoints in place (no connection drain) rather than recreating the cluster. The clusters are STRICT_DNS with an inline load assignment. Rollout: a one-time cluster rebuild on the first config push after upgrade (URL-derived to identity-based names), handled gracefully by Envoy's CDS warming; stable thereafter.

Single source of truth. Ref resolution and connect-timeout parsing go through pkg/utils/upstreamref (FindByName, ParseConnectTimeout); API-level cluster-name hashing goes through pkg/utils/clusterkey (APILevel returns the identity fragment, APILevelName joins the env prefix). Both are consumed by the validator, the RDC transformer, and the xDS translator so they cannot drift. The policy-engine kernel (a separate Go module that cannot import clusterkey) reconstructs the definition cluster name for dynamic-endpoint targets; a kernel unit test pins its output byte-for-byte to clusterkey.DefinitionName so the two modules cannot drift either.

What changed (gateway-controller layer)

  • OpenAPI schema (management-openapi.yaml): optional upstream on Operation resolving to RestAPIOperationUpstream (main/sandbox), each a ref-only RestAPIOperationUpstreamTarget. Wrapper and leaf both locked with additionalProperties: false.
  • Validator (api_validator.go): rejects an empty upstream: {} wrapper; requires at least one of main/sandbox; rejects a ref that does not resolve; and enforces one name contract (^[a-zA-Z0-9\-_]+$, max 100 chars) on per-op refs, API-level refs, and upstreamDefinition names so every valid definition name is referenceable.
  • Transform (transform/restapi.go) and xDS translator (xds/translator.go): per-op routes reuse the referenced definition's cluster (upstream_<kind>_<apiID>_<defName>, built once per definition); API-level clusters use URL-stable names main_<fragment>/sandbox_<fragment>; operations without a per-op upstream fall back to the API-level cluster.
  • Shared utils (pkg/utils/upstreamref, pkg/utils/clusterkey): new leaf packages. upstreamref handles ref resolution and connect-timeout parsing; the stdlib-only clusterkey handles URL-stable API-level cluster-key hashing (APILevel / APILevelName) and definition cluster naming (DefinitionName).

Cluster names: before / after

For an API with UUID 0190b3e2-7b1c-7c2a-9b3d-1a2b3c4d5e6f (sha256(apiID)[:12] = 54a9b3e5ce2b6ccb97168e59):

Cluster Before After
API-level main cluster_http_default-backend_8080 (URL-derived) main_54a9b3e5ce2b6ccb97168e59 (identity-based)
API-level sandbox cluster_http_sandbox-backend_8080 (URL-derived) sandbox_54a9b3e5ce2b6ccb97168e59 (identity-based)
Definition user-service upstream_RestApi_0190b3e2-7b1c-7c2a-9b3d-1a2b3c4d5e6f_user-service unchanged (same name, now built via the shared clusterkey.DefinitionName helper)

Only the API-level names change. Editing a backend URL previously renamed the API-level cluster, so Envoy dropped and recreated it; with identity-based names the cluster name never changes and Envoy updates the endpoints in place. Definition cluster names were already URL-independent.

Test coverage

  • Unit tests across pkg/config, pkg/transform, pkg/xds, pkg/utils/upstreamref, and pkg/utils/clusterkey: deterministic hash tests (APILevel), validator rejection tests (empty/unknown/pattern/length refs, with exact error reasons), URL-stable cluster-name contract tests (same name across a URL edit), definition-cluster reuse and cross-API isolation tests, per-op route tests asserting the exact referenced definition cluster, a policy chain-order test (API-level policies precede operation-level, so the operation-level policy wins as the last write), and a policy-engine kernel test pinning the x-target-upstream value for a dotted/coloned definition name byte-for-byte to the controller's clusterkey.DefinitionName.
  • Integration tests (godog), 26 scenarios across four feature files (per-op-upstream-basic (9), per-op-upstream-ref (5), per-op-upstream-validation (6), api-level-url-stable (6)) covering API-level fallback, per-op main/sandbox ref overrides, routing to two distinct real backends, validation rejections (strict 400), dynamic-endpoint precedence over per-op refs at both operation and API level, and URL-stable in-place endpoint updates. All passing against a local docker-compose stack.

Example

One API exercising every capability: API-level fallback, per-op main override, per-op main+sandbox overrides, definition base path and connect timeout, host rewrite, and a dynamic-endpoint policy overriding a per-op ref.

apiVersion: gateway.api-platform.wso2.com/v1
kind: RestApi
metadata:
  name: shop-api-v1.0
spec:
  displayName: Shop API
  version: v1.0
  context: /shop/$version
  vhosts:
    main: shop.example.com
    sandbox: sandbox.shop.example.com

  # Named backends, declared once, referenced everywhere
  upstreamDefinitions:
    - name: user-service
      basePath: /api/v2                 # prepended to requests routed to this backend
      timeout:
        connect: 5s                     # connect timeout lives on the definition (per-op targets are ref-only)
      upstreams:
        - url: http://user-service:8080
    - name: order-service
      timeout:
        connect: 500ms
      upstreams:
        - url: http://order-service:8080
    - name: promo-service
      upstreams:
        - url: http://promo-service:8080

  # API-level default upstream (url or ref; hostRewrite lives at this level)
  upstream:
    main:
      url: http://default-backend:8080
      hostRewrite: auto
    sandbox:
      ref: user-service                 # API-level upstream can also use a ref

  operations:
    # 1. No per-op upstream: falls back to the API-level upstream
    - method: GET
      path: /products

    # 2. Per-op main override: routes to user-service, inheriting its basePath and timeout
    - method: GET
      path: /users/{id}
      upstream:
        main:
          ref: user-service

    # 3. Per-op main and sandbox overrides: different backends per environment
    - method: POST
      path: /orders
      upstream:
        main:
          ref: order-service
        sandbox:
          ref: user-service

    # 4. Per-op ref plus dynamic-endpoint policy: the policy wins over the ref
    - method: GET
      path: /recommendations
      upstream:
        main:
          ref: user-service
      policies:
        - name: dynamic-endpoint
          version: v1
          params:
            targetUpstream: promo-service

Routing result:

  • GET /products goes to default-backend (no per-op upstream, API-level fallback)
  • GET /users/{id} goes to user-service under /api/v2 (per-op main ref, inherits the definition's basePath)
  • POST /orders goes to order-service on main and user-service on sandbox (per-op overrides per environment)
  • GET /recommendations goes to promo-service (the operation-level dynamic-endpoint policy overrides the per-op ref)

@coderabbitai

coderabbitai Bot commented May 22, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

  • @coderabbitai resume to resume automatic reviews.
  • @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

  • ▶️ Resume reviews
  • 🔍 Trigger review
📝 Walkthrough

Walkthrough

This PR adds per-operation upstream overrides for REST operations, including main and sandbox ref-based targets. It introduces shared UpstreamReference, upstreamref, and clusterkey utilities; updates validation to enforce ref format, length, existence, and timeout rules; and rewires REST/XDS translation to resolve per-op upstream definitions with API-scoped cluster naming. Tests and integration features were expanded for schema, validation, routing, storage roundtrips, and cluster naming behavior.

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant Validator
  participant RESTTransformer
  participant XdsTranslator
  participant Envoy

  Client->>Validator: submit REST API config
  Validator->>RESTTransformer: validated per-op upstream refs
  RESTTransformer->>XdsTranslator: route wiring with API-scoped cluster keys
  XdsTranslator->>Envoy: emit clusters and routes
  Envoy-->>Client: traffic routed to API-level or per-op upstream
Loading

Suggested reviewers: Krishanx92, renuka-fernando, malinthaprasan

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 55.34% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly states the main change: adding per-operation upstream overrides for REST API operations.
Description check ✅ Passed The description is detailed and covers purpose, goals, approach, tests, and examples, but it omits several template sections.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@CLAassistant

CLAassistant commented May 22, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 22, 2026

Copy link
Copy Markdown
Contributor
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@gateway/gateway-controller/api/management-openapi.yaml`:
- Around line 4139-4148: OperationUpstream currently allows an empty object
which is invalid; update the OperationUpstream schema (the OperationUpstream
object that defines properties main and sandbox) to require at least one of
those properties by adding an anyOf clause such as anyOf: - required: [main] -
required: [sandbox] (or an equivalent oneOf/anyOf expression) so the schema
enforces presence of main or sandbox and prevents {} being valid.

In `@gateway/gateway-controller/pkg/policy/builder.go`:
- Around line 185-186: The current condition treats any non-nil
op.Upstream.Sandbox as active; change it to perform a content-based check like
apiSandboxHasContent so empty sandbox objects are ignored. Introduce/compute a
per-op predicate (e.g., perOpSandboxHasContent) that mirrors the api-level
sandbox content test and use if apiSandboxHasContent || (op.Upstream != nil &&
perOpSandboxHasContent) to decide whether to append effectiveSandboxVHost.

In `@gateway/gateway-controller/pkg/xds/translator_test.go`:
- Around line 2061-2074: Update TestResolvePerOpUpstream_DedupSameURL to ensure
URL-stability by creating two distinct api.Upstream instances with different Url
values (e.g., "http://shared-svc:8080" and "http://shared-svc:8081") but the
same apiID, method, path and env, then call translator.resolvePerOpUpstream for
both and assert the returned cluster names are equal; keep the test name and use
the Translator.resolvePerOpUpstream and translator variable references so the
test still targets the same logic and verifies that cluster key derivation does
not depend on the exact URL string.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4012d4ee-58df-4773-b82e-fa11e65290d8

📥 Commits

Reviewing files that changed from the base of the PR and between 943c653 and b2426a7.

📒 Files selected for processing (16)
  • gateway/gateway-controller/api/management-openapi.yaml
  • gateway/gateway-controller/pkg/api/management/generated.go
  • gateway/gateway-controller/pkg/config/api_validator.go
  • gateway/gateway-controller/pkg/config/validator_test.go
  • gateway/gateway-controller/pkg/models/runtime_deploy_config.go
  • gateway/gateway-controller/pkg/policy/builder.go
  • gateway/gateway-controller/pkg/policy/builder_test.go
  • gateway/gateway-controller/pkg/transform/restapi.go
  • gateway/gateway-controller/pkg/transform/restapi_test.go
  • gateway/gateway-controller/pkg/utils/commonutils.go
  • gateway/gateway-controller/pkg/utils/commonutils_test.go
  • gateway/gateway-controller/pkg/xds/translator.go
  • gateway/gateway-controller/pkg/xds/translator_test.go
  • gateway/it/features/per-op-upstream-basic.feature
  • gateway/it/features/per-op-upstream-ref.feature
  • gateway/it/features/per-op-upstream-validation.feature

Comment thread gateway/gateway-controller/api/management-openapi.yaml Outdated
Comment thread gateway/gateway-controller/pkg/policy/builder.go Outdated
Comment thread gateway/gateway-controller/pkg/xds/translator_test.go Outdated
mehara-rothila pushed a commit to mehara-rothila/api-platform that referenced this pull request May 22, 2026
- OperationUpstream schema now requires at least one of main or sandbox
  via anyOf, rejecting empty {} at the schema layer as defense in depth
  alongside the validator.
- Policy builder per-op sandbox check is now content-based (trims and
  checks Url/Ref non-empty) matching the apiSandboxHasContent pattern
  used elsewhere. Fixes asymmetric pointer-only check that would emit
  sandbox policy chains for empty sandbox wrappers.
- TestResolvePerOpUpstream_DedupSameURL now uses two distinct URLs with
  identical apiID|METHOD|path|env, asserting cluster name independence
  from URL. Pins the EDS-stable design contract.
@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 22, 2026

Copy link
Copy Markdown
Contributor
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 23, 2026

Copy link
Copy Markdown
Contributor
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 26, 2026

Copy link
Copy Markdown
Contributor
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🧹 Nitpick comments (1)
gateway/gateway-controller/pkg/policyxds/policyxds_test.go (1)

120-120: 💤 Low value

Consider using a hash-like cluster key suffix for test realism.

The cluster key "main_fixture" has the correct main_ prefix for an API-level main environment cluster, but the suffix fixture doesn't reflect the production naming pattern introduced in this PR. According to the PR objectives, API-level clusters follow the pattern <env>_<sha256(apiID|env)[:8]> (e.g., main_a1b2c3d4). While the current fixture name is functionally correct and clear, using a hash-like suffix such as "main_12ab34cd" would make the test more representative of production behavior.

📝 Proposed update for more realistic fixture naming
 					Upstream: models.RouteUpstream{
-						ClusterKey: "main_fixture",
+						ClusterKey: "main_12ab34cd",
 					},
 				UpstreamClusters: map[string]*models.UpstreamCluster{
-					"main_fixture": {
+					"main_12ab34cd": {
 						BasePath:  "/",

Also applies to: 132-132

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@gateway/gateway-controller/pkg/policyxds/policyxds_test.go` at line 120,
Update the test fixture cluster key strings that currently use "main_fixture" to
a realistic hash-like suffix such as "main_12ab34cd" to match the production
pattern; locate the occurrences in the policyxds_test setup where ClusterKey:
"main_fixture" is declared (the test fixture variables/constants used in Policy
XDS tests) and replace them with "main_12ab34cd" (or another 8-char hex-like
hash) to make the test names reflect the <env>_<sha256(... )[:8]> convention.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@gateway/gateway-controller/pkg/policyxds/policyxds_test.go`:
- Line 120: Update the test fixture cluster key strings that currently use
"main_fixture" to a realistic hash-like suffix such as "main_12ab34cd" to match
the production pattern; locate the occurrences in the policyxds_test setup where
ClusterKey: "main_fixture" is declared (the test fixture variables/constants
used in Policy XDS tests) and replace them with "main_12ab34cd" (or another
8-char hex-like hash) to make the test names reflect the <env>_<sha256(...
)[:8]> convention.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 8729c50c-d6aa-40f4-b0b0-efec0f9c903c

📥 Commits

Reviewing files that changed from the base of the PR and between c242faa and ab55925.

📒 Files selected for processing (13)
  • gateway/gateway-controller/cmd/controller/main.go
  • gateway/gateway-controller/pkg/config/api_validator.go
  • gateway/gateway-controller/pkg/policyxds/policyxds_test.go
  • gateway/gateway-controller/pkg/transform/restapi.go
  • gateway/gateway-controller/pkg/transform/restapi_test.go
  • gateway/gateway-controller/pkg/utils/clusterkey/clusterkey.go
  • gateway/gateway-controller/pkg/utils/clusterkey/clusterkey_test.go
  • gateway/gateway-controller/pkg/utils/commonutils_test.go
  • gateway/gateway-controller/pkg/xds/translator.go
  • gateway/gateway-controller/pkg/xds/translator_test.go
  • gateway/it/features/api-level-eds-stable.feature
  • gateway/it/features/per-op-upstream-basic.feature
  • gateway/it/suite_test.go
💤 Files with no reviewable changes (1)
  • gateway/gateway-controller/pkg/utils/commonutils_test.go
✅ Files skipped from review due to trivial changes (2)
  • gateway/gateway-controller/cmd/controller/main.go
  • gateway/it/suite_test.go

@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 30, 2026

Copy link
Copy Markdown
Contributor
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
gateway/gateway-controller/pkg/config/validator_test.go (1)

773-796: ⚡ Quick win

Isolate invalid-timeout cases with subtests.

Using require inside the loop means the first failing case can stop execution before the next case is checked. Wrapping each badTimeout in t.Run(...) keeps both cases independently validated and easier to diagnose.

Proposed test refactor
- for _, badTimeout := range []string{"0s", "-5s"} {
+ for _, badTimeout := range []string{"0s", "-5s"} {
+   t.Run(badTimeout, func(t *testing.T) {
      connect := badTimeout
      definitions := &[]api.UpstreamDefinition{
        {
          Name: "my-upstream",
          Timeout: &api.UpstreamTimeout{
            Connect: &connect,
          },
          Upstreams: []struct {
            Url    string `json:"url" yaml:"url"`
            Weight *int   `json:"weight,omitempty" yaml:"weight,omitempty"`
          }{
            {
              Url: "http://backend:8080",
            },
          },
        },
      }

      errors := validator.validateUpstreamDefinitions(definitions)
      require.Len(t, errors, 1, "timeout %q must be rejected", badTimeout)
      assert.Equal(t, "spec.upstreamDefinitions[0].timeout.connect", errors[0].Field)
      assert.Contains(t, errors[0].Message, "must be a positive duration")
+   })
  }
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@gateway/gateway-controller/pkg/config/validator_test.go` around lines 773 -
796, The test loop in validator_test.go uses require inside a for-range which
can abort the whole loop on first failure; refactor by wrapping each badTimeout
iteration in a subtest using t.Run(fmt.Sprintf("timeout=%s", badTimeout), func(t
*testing.T) { ... }) and move the assertions (require.Len, assert.Equal,
assert.Contains) into that subtest, capturing the loop variable (e.g., tt :=
badTimeout) before using it to build the definitions passed to
validator.validateUpstreamDefinitions so each case runs and reports
independently.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@gateway/gateway-controller/api/management-openapi.yaml`:
- Around line 4136-4137: The schemas that currently use a $ref with a sibling
description (referencing "`#/components/schemas/RestAPIOperationUpstream`") must
be changed so the description is not a sibling of $ref; instead wrap the
reference in an allOf and move the description onto the enclosing schema object.
Concretely, replace occurrences where a property has "$ref:
'`#/components/schemas/RestAPIOperationUpstream`'" alongside "description" by
creating an object with "description: <same text>" and "allOf: [{ $ref:
'`#/components/schemas/RestAPIOperationUpstream`' }]" (apply this change for every
place referencing RestAPIOperationUpstream in the file).

In `@gateway/gateway-controller/pkg/config/api_validator.go`:
- Around line 656-667: The per-operation upstream ref checks (using
upstreamRefRegex and length >100 in the validate path that returns
ValidationError for field/refName) are stricter than names allowed by
validateUpstreamDefinitions, causing valid definition names to become
unreferencable; to fix, apply the same validation rules to
spec.upstreamDefinitions[*].name inside validateUpstreamDefinitions (reuse
upstreamRefRegex and the 100-character limit and return a ValidationError with
the same message format when a definition name violates them) OR remove the
extra constraints from the per-operation check so both places use the same
contract; update validateUpstreamDefinitions to reference the same
upstreamRefRegex and error messages (Field and Message) so names and refs are
aligned.

---

Nitpick comments:
In `@gateway/gateway-controller/pkg/config/validator_test.go`:
- Around line 773-796: The test loop in validator_test.go uses require inside a
for-range which can abort the whole loop on first failure; refactor by wrapping
each badTimeout iteration in a subtest using t.Run(fmt.Sprintf("timeout=%s",
badTimeout), func(t *testing.T) { ... }) and move the assertions (require.Len,
assert.Equal, assert.Contains) into that subtest, capturing the loop variable
(e.g., tt := badTimeout) before using it to build the definitions passed to
validator.validateUpstreamDefinitions so each case runs and reports
independently.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: a0b21e0b-ca37-459a-b596-04dce4de1349

📥 Commits

Reviewing files that changed from the base of the PR and between ab55925 and 4d08e3a.

📒 Files selected for processing (18)
  • gateway/gateway-controller/api/management-openapi.yaml
  • gateway/gateway-controller/pkg/api/management/generated.go
  • gateway/gateway-controller/pkg/config/api_validator.go
  • gateway/gateway-controller/pkg/config/validator_test.go
  • gateway/gateway-controller/pkg/policy/builder.go
  • gateway/gateway-controller/pkg/policy/builder_test.go
  • gateway/gateway-controller/pkg/transform/restapi.go
  • gateway/gateway-controller/pkg/transform/restapi_test.go
  • gateway/gateway-controller/pkg/utils/upstreamref/upstreamref.go
  • gateway/gateway-controller/pkg/utils/upstreamref/upstreamref_test.go
  • gateway/gateway-controller/pkg/xds/translator.go
  • gateway/gateway-controller/pkg/xds/translator_test.go
  • gateway/gateway-controller/tests/integration/storage_test.go
  • gateway/gateway-runtime/policy-engine/internal/kernel/translator.go
  • gateway/gateway-runtime/policy-engine/internal/kernel/translator_test.go
  • gateway/it/features/per-op-upstream-basic.feature
  • gateway/it/features/per-op-upstream-ref.feature
  • gateway/it/features/per-op-upstream-validation.feature
🚧 Files skipped from review as they are similar to previous changes (4)
  • gateway/gateway-controller/pkg/policy/builder.go
  • gateway/gateway-controller/pkg/policy/builder_test.go
  • gateway/gateway-controller/pkg/transform/restapi.go
  • gateway/gateway-controller/pkg/xds/translator.go

Comment thread gateway/gateway-controller/api/management-openapi.yaml Outdated
Comment thread gateway/gateway-controller/pkg/config/api_validator.go Outdated
@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented May 30, 2026

Copy link
Copy Markdown
Contributor
✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@renuka-fernando renuka-fernando changed the base branch from main to feature/operation-level-ep June 3, 2026 12:46
@mehara-rothila mehara-rothila force-pushed the feat/per-op-upstream-gateway branch 2 times, most recently from 4cfd850 to 4caca38 Compare June 4, 2026 00:16
@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jun 4, 2026

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

@renuka-fernando renuka-fernando changed the base branch from feature/operation-level-ep to main June 4, 2026 00:31
@renuka-fernando renuka-fernando changed the base branch from main to feature/operation-level-ep June 4, 2026 00:32
@renuka-fernando renuka-fernando marked this pull request as ready for review June 4, 2026 00:32
Comment thread gateway/it/features/per-op-upstream-ref.feature
Comment thread gateway/it/features/per-op-upstream-ref.feature Outdated
Comment thread gateway/it/features/per-op-upstream-ref.feature Outdated
Comment thread gateway/it/features/per-op-upstream-ref.feature
Regenerate generated.go and migrate the per-op feature files and tests from API version v1alpha1 to v1 to match main.
Main's vhost-materialization feature auto-populates a default sandbox vhost on every API, so rejecting a sandbox vhost without a sandbox upstream would reject nearly every API (it broke TestVhostMaterializationOnDeploy and TestCreateRestAPIDBError after the merge). Remove the check, its unit test, and its IT scenario.
…m field

OpenAPI 3.0 ignores a description placed beside a ref; RestAPIOperationUpstream already carries the field description. generated.go is unchanged (the parsed/embedded spec never held the ignored sibling).
anyOf:[required:main, required:sandbox] made oapi-codegen model RestAPIOperationUpstream as a union and emit unused helper types and marshalers. minProperties:1 with additionalProperties:false expresses the same 'at least one of main/sandbox' constraint, matches the existing spec convention, and generates a plain struct. Regenerated generated.go and updated a stale test message. Behavior is unchanged; the validator still enforces the rule.
…e gaps

Removed xDS tests that re-tested the shared upstreamref helpers through one-line delegates (parseTimeout, resolveUpstreamDefinition), keeping one wiring check each; consolidated the duplicate resolveUpstreamCluster direct-URL and missing-URL cases. Added the missing per-op sandbox cluster_header/default-cluster assertions (parity with main), a route-level assertion that the per-op main route uses cluster_header, and explicit minute/hour cases for the shared connect-timeout parser.
An earlier commit changed a single comment character in this pre-existing test; restore it so the branch diff stays limited to the feature.
The op_ prefix was a placeholder for a rejected per-op-cluster design that was never implemented in code. The upstream_ prefix check plus the single-cluster and same-key assertions already prove definition-cluster reuse, so the op_ guards (and their comments) were redundant.
An earlier cleanup commit removed pre-existing base tests (ResolveUpstreamCluster SimpleURL/MissingURL, ResolveUpstreamDefinition, ParseTimeout) and op_ guards that are not part of this feature, and added two extra assertions. Restore the originals so the PR stays additive to the per-op feature; the only retained test change is the minute/hour coverage relocated into upstreamref_test.go.
The op_ prefix never existed in code; these guards (in our own per-op tests) are redundant with the upstream_ prefix and single-cluster assertions. Pre-existing base tests remain intact.
The comment described the old dedicated-per-op-cluster design; the test actually asserts the reused upstreamDefinition cluster (matching the feature's reuse model). Reword to describe what the test really checks.
… base path

Add TestTranslateConfigs_PerOpRoutesUseClusterHeaderAndDefinitionBasePath (main + sandbox subtests) covering the translateAPIConfig -> createRoute path: the generated per-op route must use cluster_header dynamic routing on the target-upstream header, strip that header before forwarding, and rewrite the path with the referenced definition base path. Existing per-op TranslateConfigs tests only asserted the definition cluster was emitted, not that the route actually uses it. The sandbox subtest also covers per-op-only sandbox route creation (no API-level sandbox).
Pin that API-level policies precede operation-level ones in the policy chain so an operation-level policy wins as the last write, and pin the exact x-target-upstream cluster name emitted for a definition name containing dots or colons. Tighten the per-op override route tests to assert the exact referenced definition cluster and the ref validation negative tests to assert the exact error reason.
@mehara-rothila

Copy link
Copy Markdown
Contributor Author

@coderabbitai review

@coderabbitai

coderabbitai Bot commented Jul 1, 2026

Copy link
Copy Markdown
Contributor
✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

The route loop chose sandbox values by comparing the vhost string against the sandbox vhost. When an API sets identical main and sandbox vhosts with no sandbox upstream configured, the guard does not fire and the main route matched the comparison, silently replacing the per-op upstream override with the API-level cluster while the xDS path still applied the override. Dispatch on the vhost's position instead: the first entry is always main and the sandbox vhost, when present, is appended second.
…a helper

The max-length and pattern checks for an UpstreamReference name were duplicated across the API-level ref, per-op ref, and upstreamDefinition name validation. Extract them into validateUpstreamRefName(field, value, label); each caller keeps its own field path, message noun, and control flow (return for the ref sites, append and continue for the definition loop). Messages are unchanged.
@mehara-rothila mehara-rothila force-pushed the feat/per-op-upstream-gateway branch from 674f8dc to 21ba17b Compare July 6, 2026 00:03
…dation

Renames RestAPIOperationUpstream to OperationUpstream so the schema name is
not tied to a single API type, and removes the standalone
RestAPIOperationUpstreamTarget schema; the ref-only target object is declared
inline under the operation upstream main and sandbox fields, so the payload
shape (main: { ref: <name> }) is unchanged. The generated server code is
regenerated from the updated spec.

Also unexports the API-level cluster-key fragment helper to apiLevel (only
APILevelName is used outside the package), drops the caller-passed label from
upstream name validation and derives the field name from the error path
instead, and trims over-verbose validator comments.
@mehara-rothila mehara-rothila force-pushed the feat/per-op-upstream-gateway branch from 80924d0 to 66dd517 Compare July 6, 2026 09:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants