feat(platform-api): support upstreamDefinitions pool and per-operation upstream overrides#2155
Conversation
mehara-rothila
changed the title
📝 WalkthroughWalkthroughThis change adds reusable upstream definitions and per-operation upstream overrides across the OpenAPI contract, generated API models, internal models, YAML DTOs, service validation, API handlers, conversion utilities, repository persistence, and deployment YAML generation. Upstream definitions support named backend pools, optional base paths, weighted targets, and connect timeouts. Operations can reference named definitions for main and sandbox upstreams. Create and update flows validate definitions and references, while tests cover conversion, merging, persistence, and deployment output. Sequence Diagram(s)sequenceDiagram
participant Client
participant APIHandler
participant APIService
participant Repository
participant DeploymentYAML
Client->>APIHandler: submit API with upstream definitions
APIHandler->>APIService: create or update request
APIService->>APIService: validate definitions and operation references
APIService->>Repository: persist validated configuration
Repository-->>APIService: stored API configuration
APIService->>DeploymentYAML: build deployment specification
DeploymentYAML-->>Client: upstream pools and operation references
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
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. Comment |
|
@coderabbitai review |
✅ Action performedReview finished.
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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 `@platform-api/src/resources/openapi.yaml`:
- Around line 8455-8464: UpstreamTimeout.connect's OpenAPI regex only allows a
single unit but the runtime uses time.ParseDuration (see
spec.upstreamDefinitions[%d].timeout.connect), so update the OpenAPI schema for
UpstreamTimeout.connect to either (A) broaden the pattern to match Go
time.ParseDuration format (allow multiple sequential value+unit segments,
decimals, and units like ns|us|µs|ms|s|m|h, optional leading minus) or (B)
explicitly document/validate that only single-unit durations are accepted;
locate the UpstreamTimeout.connect property in the OpenAPI file and change the
pattern or description accordingly.
- Around line 8427-8447: Update the ReusableUpstream schema so its basePath
property is constrained to a path-only form and each upstream.url is constrained
to host[:port]-only (no path/query/fragment) to match gateway validation:
tighten basePath (property name basePath) to require a leading "/" and a path
pattern (e.g., path segment characters only) and change
upstreams.items.properties.url to validate host[:port] (e.g., restrict
format/pattern to host with optional port) instead of generic uri; keep timeout
($ref: '`#/components/schemas/UpstreamTimeout`') unchanged.
🪄 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: c978ac83-b305-4917-85d3-8826d792c30e
📒 Files selected for processing (1)
platform-api/src/resources/openapi.yaml
mehara-rothila
changed the title
mehara-rothila
force-pushed
the
feat/platform-api-upstream-definitions
branch
2 times, most recently
from
e27ea92 to
3cb7216
Compare
|
@coderabbitai a naming sanity-check on the upstream schemas in this PR, please. Context: this PR (#2155) is the platform-api / control-plane side of the per-operation upstream feature. Its gateway / data-plane companion is #2012 (#2012), which adds the matching schemas to Current state in
How the gateway side names the same things:
The clash: our field is Proposed rename, keeping
Please advise:
|
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Find the OpenAPI files =="
fd -p 'openapi.yaml|management-openapi.yaml'
echo
echo "== Outline current platform-api upstream-related schema names =="
rg -n -C2 '^\s{4}(Upstream|UpstreamDefinition|ReusableUpstream|UpstreamTimeout|RESTAPI):|upstreamDefinitions:|`#/components/schemas/`(Upstream|UpstreamDefinition|ReusableUpstream|UpstreamTimeout)\b' \
platform-api/src/resources/openapi.yaml || true
echo
echo "== Read the relevant platform-api slice =="
start=$(rg -n '^\s{4}RESTAPI:' platform-api/src/resources/openapi.yaml | cut -d: -f1 | head -n1)
end=$(rg -n '^\s{4}UpstreamTimeout:' platform-api/src/resources/openapi.yaml | cut -d: -f1 | head -n1)
if [[ -n "${start:-}" && -n "${end:-}" ]]; then
sed -n "$((start-10)),$((end+80))p" platform-api/src/resources/openapi.yaml | nl -ba
fi
echo
echo "== Current branch: all refs to UpstreamDefinition / ReusableUpstream in platform-api =="
rg -n -C2 '`#/components/schemas/`(UpstreamDefinition|ReusableUpstream)\b|^\s{4}(UpstreamDefinition|ReusableUpstream):' platform-api/src/resources/openapi.yaml || true
echo
echo "== Companion PR `#2012`: inspect gateway management-openapi upstream naming =="
gh pr diff 2012 --repo wso2/api-platform -- gateway/gateway-controller/api/management-openapi.yaml | \
rg -n -C3 'UpstreamDefinition|UpstreamReference|OperationUpstream|upstreamDefinitions|timeout|basePath|main:|sandbox:' || true
echo
echo "== Companion PR `#2012` metadata =="
gh pr view 2012 --repo wso2/api-platform --json number,title,headRefName,baseRefName,state,urlLength of output: 4416 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== platform-api: RESTAPI and upstream schema slice =="
sed -n '6318,8498p' platform-api/src/resources/openapi.yaml
echo
echo "== platform-api: precise refs/usages of UpstreamDefinition and ReusableUpstream =="
rg -n -C2 '`#/components/schemas/`(UpstreamDefinition|ReusableUpstream)\b|^\s{4}(UpstreamDefinition|ReusableUpstream):' \
platform-api/src/resources/openapi.yaml
echo
echo "== gateway companion PR `#2012`: files changed =="
gh pr view 2012 --repo wso2/api-platform --json files \
--jq '.files[].path'
echo
echo "== gateway companion PR `#2012`: upstream-related diff excerpt from management-openapi.yaml =="
gh pr diff 2012 --repo wso2/api-platform | \
sed -n '/gateway\/gateway-controller\/api\/management-openapi.yaml/,$p' | \
rg -n -C4 'UpstreamDefinition|UpstreamReference|OperationUpstream|upstreamDefinitions|`#/components/schemas/`' || true
echo
echo "== gateway main branch: current upstream naming in management-openapi.yaml =="
rg -n -C3 '^\s{4}(UpstreamDefinition|UpstreamReference|OperationUpstream|API|RESTAPI):|upstreamDefinitions:|`#/components/schemas/`(UpstreamDefinition|UpstreamReference|OperationUpstream)\b' \
gateway/gateway-controller/api/management-openapi.yaml || trueLength of output: 131926
Bottom line: I recommend making the rename now. It reduces local ambiguity and brings the control-plane terminology into line with the gateway model. One small follow-up suggestion: if you do this rename, also update the ✏️ Learnings added
|
|
@coderabbitai we're renaming the Our candidates:
Please (a) add any stronger options, then (b) rank ALL of them best-to-worst with a one-line rationale each. Judge by: cross-plane consistency with the gateway (which calls this |
|
Tip For best results, initiate chat on the files or code changes.
Additional candidates to consider: Ranking (best to worst):
Recommendation unchanged: ✏️ Learnings added
|
|
@coderabbitai for the agreed rename, please show a focused before/after of ONLY the affected schema blocks, not the full file: the |
mehara-rothila
force-pushed
the
feat/platform-api-upstream-definitions
branch
from
3cb7216 to
f2e8961
Compare
|
@coderabbitai full review This is the control-plane (platform-api) side of per-operation upstream routing. The data-plane contract it must match is in PR #2012 (gateway-controller/pkg/config/api_validator.go and management-openapi.yaml). Please verify each of these and flag any divergence:
|
🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== PR 2155 files changed =="
gh pr view 2155 --repo wso2/api-platform --json files --jq '.files[].path'
echo
echo "== PR 2155 diff stat =="
gh pr diff 2155 --repo wso2/api-platform --stat
echo
echo "== Confirm no generated.go / validator / test files touched =="
gh pr diff 2155 --repo wso2/api-platform | rg -n '^diff --git' || trueLength of output: 1675 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Full diff PR 2155 (patch) =="
gh pr diff 2155 --repo wso2/api-platform --patch > /tmp/pr2155.diff
wc -l /tmp/pr2155.diff
echo
echo "== Show diff per file with line counts =="
rg -n '^diff --git' /tmp/pr2155.diff
echo
echo "== upstream.go full diff =="
awk '/^diff --git a\/platform-api\/src\/internal\/model\/upstream.go/,/^diff --git a\/platform-api\/src\/internal\/(model\/api|repository)/' /tmp/pr2155.diff | head -300
echo
echo "== utils/api.go diff =="
awk '/^diff --git a\/platform-api\/src\/internal\/utils\/api\.go/,/^diff --git a\/platform-api\/src\/internal\/utils\/api_test\.go/' /tmp/pr2155.diff | head -400Length of output: 18754 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== constants/error.go diff =="
sed -n '353,365p' /tmp/pr2155.diff
awk '/^diff --git a\/platform-api\/src\/internal\/constants\/error\.go/,/^diff --git a\/platform-api\/src\/internal\/dto\/api\.go/' /tmp/pr2155.diff
echo
echo "== dto/api.go diff =="
awk '/^diff --git a\/platform-api\/src\/internal\/dto\/api\.go/,/^diff --git a\/platform-api\/src\/internal\/handler\/api\.go/' /tmp/pr2155.diff
echo
echo "== handler/api.go diff =="
awk '/^diff --git a\/platform-api\/src\/internal\/handler\/api\.go/,/^diff --git a\/platform-api\/src\/internal\/model\/api\.go/' /tmp/pr2155.diff
echo
echo "== model/api.go diff =="
awk '/^diff --git a\/platform-api\/src\/internal\/model\/api\.go/,/^diff --git a\/platform-api\/src\/internal\/model\/upstream\.go/' /tmp/pr2155.diff
echo
echo "== service/api.go diff (validation logic) =="
awk '/^diff --git a\/platform-api\/src\/internal\/service\/api\.go/,/^diff --git a\/platform-api\/src\/internal\/service\/api_test\.go/' /tmp/pr2155.diffLength of output: 43390 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== PR 2012 files changed =="
gh pr view 2012 --repo wso2/api-platform --json files --jq '.files[].path' || true
echo
echo "== PR 2012 diff for api_validator.go =="
gh pr diff 2012 --repo wso2/api-platform --patch -- gateway/gateway-controller/pkg/config/api_validator.go > /tmp/pr2012_validator.diff || true
wc -l /tmp/pr2012_validator.diff
cat /tmp/pr2012_validator.diff | head -400
echo
echo "== generated.go diff (nil safety on OperationUpstream) =="
awk '/^diff --git a\/platform-api\/src\/api\/generated\.go/,/^diff --git a\/platform-api\/src\/internal\/constants\/error\.go/' /tmp/pr2155.diff | head -200
echo
echo "== repository/api_test.go and service/api_test.go and utils/api_test.go: search upstream-related test names =="
awk '/^diff --git a\/platform-api\/src\/internal\/repository\/api_test\.go/,/^diff --git a\/platform-api\/src\/internal\/service\/api\.go/' /tmp/pr2155.diff | rg -n '^\+func Test|^\+\s*t\.Run'
awk '/^diff --git a\/platform-api\/src\/internal\/service\/api_test\.go/,/^diff --git a\/platform-api\/src\/internal\/utils\/api\.go/' /tmp/pr2155.diff | rg -n '^\+func Test|^\+\s*\{name:|^\+\s*name:'
awk '/^diff --git a\/platform-api\/src\/internal\/utils\/api_test\.go/,0' /tmp/pr2155.diff | rg -n '^\+func Test|^\+\s*\{name:|^\+\s*name:'Length of output: 12110 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== PR 2012 head branch =="
head_ref=$(gh pr view 2012 --repo wso2/api-platform --json headRefName --jq .headRefName)
echo "$head_ref"
echo
echo "== Fetch api_validator.go content from PR2012 head =="
gh api repos/wso2/api-platform/contents/gateway/gateway-controller/pkg/config/api_validator.go?ref="$head_ref" --jq .content | base64 -d > /tmp/api_validator.go
wc -l /tmp/api_validator.go
rg -n 'func Validate|upstream|Upstream|weight|Weight|timeout|Timeout|regexp|MustCompile' /tmp/api_validator.go | head -100
echo
echo "== Fetch upstreamref.go content =="
gh api repos/wso2/api-platform/contents/gateway/gateway-controller/pkg/utils/upstreamref/upstreamref.go?ref="$head_ref" --jq .content | base64 -d > /tmp/upstreamref.go
cat /tmp/upstreamref.goLength of output: 1301 🏁 Script executed: #!/bin/bash
set -euo pipefail
echo "== Try git fetch branch directly =="
git fetch origin feat/per-op-upstream-gateway:refs/remotes/origin/feat/per-op-upstream-gateway 2>&1 | tail -20 || true
git show origin/feat/per-op-upstream-gateway:gateway/gateway-controller/pkg/config/api_validator.go > /tmp/api_validator.go 2>&1 || echo "FAILED git show validator"
git show origin/feat/per-op-upstream-gateway:gateway/gateway-controller/pkg/utils/upstreamref/upstreamref.go > /tmp/upstreamref.go 2>&1 || echo "FAILED git show upstreamref"
wc -l /tmp/api_validator.go /tmp/upstreamref.go 2>&1 || true
echo
echo "== grep upstream-related validation in api_validator.go =="
rg -n 'upstream|Upstream|weight|Weight|timeout|Timeout|regexp|MustCompile|func ' /tmp/api_validator.go 2>/dev/null | head -150
echo
echo "== upstreamref.go content =="
cat /tmp/upstreamref.go 2>/dev/nullLength of output: 1443 🏁 Script executed: #!/bin/bash
set -euo pipefail
git fetch origin pull/2012/head:refs/remotes/origin/pr-2012 2>&1 | tail -20
git show origin/pr-2012:gateway/gateway-controller/pkg/config/api_validator.go > /tmp/api_validator.go 2>&1 || echo "FAILED validator"
git show origin/pr-2012:gateway/gateway-controller/pkg/utils/upstreamref/upstreamref.go > /tmp/upstreamref.go 2>&1 || echo "FAILED upstreamref"
wc -l /tmp/api_validator.go /tmp/upstreamref.go
echo
echo "== grep validation logic =="
rg -n 'upstream|Upstream|weight|Weight|timeout|Timeout|regexp|MustCompile|func ' /tmp/api_validator.go 2>/dev/null | head -200
echo
echo "== upstreamref.go =="
cat /tmp/upstreamref.go 2>/dev/nullLength of output: 13864 🏁 Script executed: #!/bin/bash
set -euo pipefail
sed -n '158,260p' /tmp/api_validator.goLength of output: 3206
1. Validation parity with the gateway validator — Matches closely.
2. Validation on create and merged update, surfaced as 400 — Confirmed.
3. Persistence round-trip — 4. Deployment YAML emission — Matches the gateway shape. 5. Nil-safety and generated.go — 6. Tests — Yes, they exercise the intended paths: repository round-trip, One open item from earlier in this thread: the agreed rename ( ✅ Action performedReview finished.
|
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (3)
platform-api/src/internal/utils/api_test.go (1)
672-679: 📐 Maintainability & Code Quality | 🔵 Trivial | 🏗️ Heavy liftApply the agreed upstream type rename.
These tests continue to encode
ReusableUpstream; rename the reusable pool entry toUpstreamDefinitionand reserveUpstreamEndpointfor direct endpoint shapes across the schema, generated code, models, and tests. As noted in the PR objectives, this is the agreed naming model.🤖 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 `@platform-api/src/internal/utils/api_test.go` around lines 672 - 679, Rename the reusable pool type represented by UpstreamDefinitions and its entries from ReusableUpstream to UpstreamDefinition across the schema, generated code, models, and tests. Reserve UpstreamEndpoint for direct endpoint shapes, updating all references and generated artifacts consistently while preserving the existing behavior and structure.platform-api/src/internal/handler/api.go (1)
162-163: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winUse
Warnfor expected 400-level validation failures.Invalid upstream definitions are client-input errors, not unexpected server failures. Reserve
Errorfor 5xx conditions and useWarnhere.Based on learnings, expected 4xx handler errors should use
slog.Warn, whileslog.Erroris reserved for unexpected server-side failures.Also applies to: 319-320
🤖 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 `@platform-api/src/internal/handler/api.go` around lines 162 - 163, Change the logging call for constants.ErrInvalidUpstreamDefinition in the handler to h.slogger.Warn, preserving the existing message and structured fields. Apply the same severity change to the corresponding handler branch around lines 319-320, while leaving unexpected server-side failures logged at Error.Source: Learnings
platform-api/src/internal/utils/api.go (1)
1539-1545: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winCanonicalize methods before constructing lookup keys.
Normalize the method once at the conversion boundary and use that canonical value throughout merging. The current inline normalization only affects the temporary key; the underlying operation can retain user-supplied casing.
As per coding guidelines, user-supplied HTTP methods must be uppercased before map-key creation and downstream route processing.
Also applies to: 1552-1554
🤖 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 `@platform-api/src/internal/utils/api.go` around lines 1539 - 1545, In the override-operation merge logic around byKey, uppercase each user-supplied op.Request.Method at the conversion boundary before constructing lookup keys, and use that canonical method for downstream route processing as well. Update the corresponding logic at the additional referenced range so the underlying operation no longer retains mixed-case methods while preserving the existing upstream lookup behavior.Source: Coding guidelines
🤖 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 `@platform-api/src/internal/handler/api.go`:
- Around line 162-166: Sanitize client responses in the
invalid-upstream-definition branches, including the corresponding occurrences
near lines 319, 702, and 925: keep logging the detailed err server-side, but
replace err.Error() passed to utils.NewErrorResponse with the fixed message
“Invalid upstream definition”.
In `@platform-api/src/internal/service/api_test.go`:
- Around line 844-846: Update the schema fixture setup around runtime.Caller and
schemaPath to resolve the path to an absolute, cleaned value, then verify it
remains within the intended test root before calling os.ReadFile. Reject or fail
the test for paths outside that root while preserving the existing
schema-loading behavior for valid paths.
In `@platform-api/src/internal/service/api.go`:
- Around line 694-701: Update resolveUpstreamRef to reject whitespace-padded
references or consistently normalize the reference before it is persisted and
emitted; ensure validation, resolution, and deployment use the same canonical
value rather than only validating strings.TrimSpace(ref).
- Around line 723-731: Update both URL validation paths around url.Parse to
validate parsed.Hostname() rather than only parsed.Host, rejecting empty
hostnames such as http://:8080. Preserve the existing http/https scheme
requirement, and only accept a port when a non-empty hostname is present.
---
Nitpick comments:
In `@platform-api/src/internal/handler/api.go`:
- Around line 162-163: Change the logging call for
constants.ErrInvalidUpstreamDefinition in the handler to h.slogger.Warn,
preserving the existing message and structured fields. Apply the same severity
change to the corresponding handler branch around lines 319-320, while leaving
unexpected server-side failures logged at Error.
In `@platform-api/src/internal/utils/api_test.go`:
- Around line 672-679: Rename the reusable pool type represented by
UpstreamDefinitions and its entries from ReusableUpstream to UpstreamDefinition
across the schema, generated code, models, and tests. Reserve UpstreamEndpoint
for direct endpoint shapes, updating all references and generated artifacts
consistently while preserving the existing behavior and structure.
In `@platform-api/src/internal/utils/api.go`:
- Around line 1539-1545: In the override-operation merge logic around byKey,
uppercase each user-supplied op.Request.Method at the conversion boundary before
constructing lookup keys, and use that canonical method for downstream route
processing as well. Update the corresponding logic at the additional referenced
range so the underlying operation no longer retains mixed-case methods while
preserving the existing upstream lookup behavior.
🪄 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: 9aa52fdf-c292-4869-ad6a-295d40587ab3
📒 Files selected for processing (12)
platform-api/src/api/generated.goplatform-api/src/internal/constants/error.goplatform-api/src/internal/dto/api.goplatform-api/src/internal/handler/api.goplatform-api/src/internal/model/api.goplatform-api/src/internal/model/upstream.goplatform-api/src/internal/repository/api_test.goplatform-api/src/internal/service/api.goplatform-api/src/internal/service/api_test.goplatform-api/src/internal/utils/api.goplatform-api/src/internal/utils/api_test.goplatform-api/src/resources/openapi.yaml
✅ Files skipped from review due to trivial changes (1)
- platform-api/src/api/generated.go
|
@coderabbitai we've decided to keep the pool entry schema named ReusableUpstream and are not renaming it to UpstreamDefinition. My earlier comment that called the rename "agreed" was premature; on reflection we are not doing it in this PR. Reasoning: adopting UpstreamDefinition for the pool would also force renaming the pre-existing UpstreamDefinition endpoint schema (the url/ref endpoint under Upstream.main/sandbox) to UpstreamEndpoint, which churns a large amount of pre-existing code (dto, model, service, utils, and their tests) that is unrelated to this feature. This PR is scoped to adding the upstreamDefinitions pool and per-operation upstream overrides, and we want to keep that scope tight. The schema shapes already match the gateway contract in #2012; only the pool entry name differs, and ReusableUpstream reads clearly for a reusable named entry in the pool. Please note this decision and do not re-flag the ReusableUpstream -> UpstreamDefinition rename in future reviews of this PR. If the maintainers prefer the rename, we will do it as a separate follow-up. |
|
Tip For best results, initiate chat on the files or code changes.
✏️ Learnings added
|
mehara-rothila
force-pushed
the
feat/platform-api-upstream-definitions
branch
from
13d47a5 to
47ed679
Compare
|
@coderabbitai review |
✅ Action performedReview finished.
|
2 participants
Summary
This PR implements the
upstreamDefinitionspool and per-operation upstream overrides in the platform-api control plane, so an API can declare a set of reusable named backends and route the API-level upstream or any individual operation to one of them by reference. This single commit adds both the OpenAPI schema for these shapes and the Go behavior behind it: model types, request and response mapping, persistence, validation, and deployment-descriptor emission.Why
The gateway side of this feature (#2012) understands
upstreamDefinitionsand an operation-levelupstream.ref, but the control plane never carried the pool through. As a result aref(API-level or operation-level) was accepted by the API and then had nothing to resolve against, producing a configuration the gateway rejects when it is deployed. This PR closes that gap on the control plane: the pool is stored, returned on reads, and emitted into the deployment descriptor, and every reference is resolved before anything is persisted or deployed, so an unresolved reference is reported to the caller as a validation error instead of failing later at deploy time.Design decisions
Operation-level overrides are reference-only. An operation's
upstream.mainandupstream.sandboxeach carry only arefinto the pool, never an inline URL, and a side that is omitted falls back to the API-level upstream. This keeps every backend definition in one place (the pool) and matches the gateway contract.Validation mirrors the gateway's rules and runs on every write path. On create, and on the merged result of an update, the control plane rejects: a duplicate or malformed pool name (must match
^[a-zA-Z0-9\-_]+$, at most 100 characters), a pool entry with no backends, a backend URL that is not host-only http or https (a path, query, or fragment is rejected because the base path belongs inbasePath), a weight outside 0 to 100, a connect timeout that is not a single unsignedms,s,m, orhunit or is not positive, an API-level endpoint that sets bothurlandrefor neither, and any API-level or operation-levelrefthat does not resolve to a declared pool entry. Validating the merged result of an update means an update cannot remove a pool entry that a still-present operation references. These surface as HTTP 400 through the standard error catalog.No database migration. The pool and the per-operation references are stored inside the existing
rest_apis.configurationJSON blob, so rows written before this change simply decode with the new fields empty and remain fully compatible.The pool entry type is named
ReusableUpstream. The platform-api generated code already has anUpstreamDefinitiontype for the API-level endpoint (the url-or-ref union), so the pool entry uses a distinct name to avoid a collision. This is open to the maintainers' preference if a different name is preferred for consistency with the gateway.Scope is limited to the upstream feature. This PR only touches the
upstreamDefinitionspool and per-operation upstream behavior; no unrelated validation or formatting changes are included.What changed
Added the
ReusableUpstream,UpstreamReference,OperationUpstream, andUpstreamTimeoutschemas to the OpenAPI spec and regeneratedapi/generated.go(the new types plus the new fields on the REST API and operation request shapes). Added persistence types and fields ininternal/model, lossless converters and deployment-YAML emission ininternal/utils, the pool and reference validation plus create and update wiring ininternal/service, the deployment-YAML DTOs ininternal/dto, the validation error sentinel ininternal/constants, and the 400 mapping ininternal/handler. The pool and per-operation references are carried through create, update, get, list, and deployment emission.Test coverage
Table-driven validation tests cover the full rule set above (pool integrity, backend URL shape, weight and timeout bounds, the API-level union, and API-level and operation-level reference resolution). Real-SQLite integration tests, wired through the concrete service and repositories, cover create, persist, and read of a pool with a per-operation override, rejection of an unresolved operation reference on create, and rejection of an update that removes a pool entry still referenced by an unchanged operation. Emission tests assert the exact
spec.upstreamDefinitionsandspec.operations[].upstreamcontent and that a WebSub API omits the pool, a conversion test proves the pool and per-operation references survive the request-to-model-to-response round trip, and a repository test proves they survive the configuration blob's database round trip.Example
An API can declare a pool and route one operation to an alternate backend while the rest use the API-level upstream:
Here
GET /whoamiis routed toalt-backendfrom the pool, whileGET /pinguses the API-levelmainupstream.Related PRs
Depends on #2012, the gateway (data plane) side of this feature, which should merge first: the deployment YAML this PR emits for per-operation upstreams is only understood by the gateway once #2012 lands. This PR supersedes #2108, which carried the same schema and was closed in favor of this branch.