Skip to content

feat(services): publish authoritative application origins - #4956

Open
TaylorMutch wants to merge 9 commits into
mainfrom
feat/4953-authoritative-app-urls/TaylorMutch
Open

TaylorMutch wants to merge 9 commits into
mainfrom
feat/4953-authoritative-app-urls/TaylorMutch

Conversation

@TaylorMutch

@TaylorMutch TaylorMutch commented Oct 27, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Publish authoritative application URLs from the configured supervisor application origin, independently of the gateway API origin. Return explicit application and gateway URLs so clients can choose an access path. Allow installations to disable gateway-mediated application routing independently.

Based on main at df6a799eb.

Related Issue

Closes #4953. Part of RFC 0017.

Changes

  • Use supervisor.app_listener.base_url as the single authored application origin and derive its service domain. Enabled listeners require an HTTPS DNS base URL; replace the earlier domain field. The supervisor listener port stays independent of the public URL port.
  • Log enabled gateway/app-listener routing at startup and warn when neither mode is enabled. Runtime defaults remain unchanged.
  • Add [openshell.gateway].enable_gateway_service_routing (default true). Setting it to false omits gateway URLs and returns 404 for gateway application HTTP/WebSocket traffic, while keeping control-plane APIs, app listeners, and discovery available.
  • Share one readable/hashed hostname policy with gateway-mediated URLs, including the existing feat(gateway): add hashed service-routing hostnames for multi-gateway clusters #4842 hash encoding. URL responses, authenticated supervisor configuration, discovery, and SNI/Host routing use the same canonical hostname.
  • Validate the HTTPS public origin and preserve its independent public port.
  • Populate service and sandbox responses, mutation replays, suspend/resume responses, CLI, and Rust/TypeScript clients.
  • Replay all recorded preferred, application, and gateway URLs together on idempotent retries; use Get/List for current addresses. Keep the new curated TypeScript URL maps optional.
  • Document DNS/TLS requirements and distinct ingress authentication boundaries. Installation-status presentation remains in feat(services): publish authoritative supervisor ingress URLs and status #4670.
  • Share DNS-label validation across core, gateway, and supervisor; return no hostname for disabled/invalid listener configurations. Skip gateway service-host resolution when routing is disabled, and explain missing public URLs in human CLI output.

Configuration

Gateway routing is enabled by default. Disable it independently of the app listener using any of these equivalent settings:

Configuration surface Setting
Gateway TOML [openshell.gateway] → enable_gateway_service_routing = false
Gateway CLI --enable-gateway-service-routing=false
Environment OPENSHELL_ENABLE_GATEWAY_SERVICE_ROUTING=false
Helm values gatewayConfig."openshell.gateway".enable_gateway_service_routing: false

Precedence is CLI > environment > TOML > default. Explicit true and false overrides are supported.

Example: publish only application-ingress URLs, with hashed hostnames:

[openshell.gateway]
name = "gateway-a"
service_hostname_format = "hashed"
enable_gateway_service_routing = false

[openshell.supervisor.app_listener]
enabled = true
base_url = "https://apps.example.com"

base_url supplies the hostname suffix under which service DNS records are created. The listener derives its domain from that URL.

name supplies the stable installation identity for hashed names. service_hostname_format defaults to "readable" and applies to both ingress paths. The application base_url is an HTTPS origin whose hostname determines the service domain; its public port can differ from the listener port. DNS, certificates, and ingress are provisioned separately.

For the routing opt-out alone in Helm:

gatewayConfig:
  openshell.gateway:
    enable_gateway_service_routing: false

Integrator perspective

The service API tells clients which public URL to use; discovery tells routers where to send requests.

  • Configure the application base_url for your public ingress. Responses expose application_url, gateway_url when gateway routing is enabled, and a preferred url that selects the application URL when configured.
  • A proxy or controller consumes discovery snapshots/watches mapping each exact hostname to the current supervisor Pod IP and app-listener port. Follow ownership changes and honor withdrawal and expiry; consume the returned hostname without reconstructing it.
  • The sandbox proxy routes directly to those endpoints. An example Kubernetes HTTPRoute controller can instead configure HTTPRoutes and their backend/TLS resources. Application traffic bypasses the OpenShell gateway.

Publishing a URL does not create DNS or ingress resources, or establish reachability. Both ingress paths use [openshell.gateway].service_hostname_format; the app listener has no separate naming mode. Keeping the installation name and public HTTPS domain/port unchanged preserves the service URL when switching ingress.

Public URL selection

This PR publishes the configured application origin alongside the gateway-mediated URL when enabled. The example uses gateway installation gateway-a, workspace default, sandbox my-sandbox, and service web.

flowchart TD
    I["Service identity<br/>gateway-a / default / my-sandbox / web"]
    M["One gateway setting: service_hostname_format<br/>readable or hashed"]
    I --> L["Shared service label generator<br/>Hashed example: enh47uqyj7bpyttz"]
    M --> L
    E["enable_gateway_service_routing<br/>Default: true"] --> G
    L --> G["gateway_url<br/>https://enh47uqyj7bpyttz.gateway.example.com/"]
    L --> A["application_url<br/>https://enh47uqyj7bpyttz.apps.example.com/"]
    O["Configured application public origin<br/>https://apps.example.com"] --> A
    A -->|"Preferred when configured"| U["url returned to clients"]
    G -->|"Fallback when application_url is absent"| U
Loading

Set enable_gateway_service_routing = false to use application ingress without advertising or serving gateway-mediated application URLs. The CLI/env equivalents are --enable-gateway-service-routing=false and OPENSHELL_ENABLE_GATEWAY_SERVICE_ROUTING=false; Helm uses gatewayConfig."openshell.gateway".enable_gateway_service_routing: false.

Gateway routing Application origin Preferred url gateway_url
Enabled Configured Application URL Gateway URL
Enabled Absent Gateway URL Gateway URL
Disabled Configured Application URL Empty
Disabled Absent Empty Empty

Disabling routing also makes gateway_service_urls empty. Idempotent retries replay the original URL bundle together, even if routing has since been disabled. Get/List return current addresses.

Hashed mode is shown above. Readable mode uses <workspace>--<sandbox>[--<service>] for both paths. The two access paths are alternatives; when their public origins match, their complete URLs match. Integrators consume discovery hostnames as returned.

Connecting the published URL to a sandbox

The proxy and example controller below are alternative discovery consumers, shown for context. This PR publishes URLs; it does not deploy either integration. Dashed arrows configure routing; solid arrows carry application traffic.

flowchart TD
    API["Service API<br/>Returns public application URL"] -.->|"URL used by client"| Client["Application client"]
    D["Discovery API<br/>Exact hostname → current supervisor Pod IP:port<br/>Installation identity and expiry"]

    D -.->|"Snapshots / watches"| P["Sandbox proxy<br/>TLS passthrough"]
    D -.->|"Snapshots / watches"| C["Example Kubernetes HTTPRoute controller<br/>Separate POC"]
    C -.->|"Reconciles HTTPRoutes, backend resources<br/>and backend TLS configuration"| K["Kubernetes Gateway<br/>Edge TLS termination"]

    Client -->|"Option A: HTTPS to published hostname"| P
    Client -->|"Option B: HTTPS to published hostname"| K
    P -->|"Application TLS forwarded unchanged"| S["Owning supervisor<br/>Application TLS listener"]
    K -->|"HTTPS to discovered endpoint<br/>Preserve application Host and backend SNI"| S
    S --> W["Declared service inside sandbox"]
Loading

Both paths keep application traffic out of the OpenShell gateway. The integrator provides DNS, certificates, and ingress configuration; discovery supplies backend changes and withdrawal/expiry information.

Release Notes

Publish application URLs independently of the gateway connection. Gateway-mediated application routing can be disabled with enable_gateway_service_routing (runtime default true). When upgrading application ingress, replace domain with base_url, deploy matching gateway/driver/supervisor images, recreate old dedicated sandbox Pods with the updated supervisor image, and upgrade the CLI.

Compatibility context

The two changes in the compatibility advisory are intentional and explicitly accepted:

  1. Configuration: The app listener is a new, unsettled feature. Replacing domain with base_url, and the internal supervisor environment variable with OPENSHELL_APP_BASE_URL, is accepted without legacy aliases. Remove the old TOML keys and deploy matching gateway/supervisor images.
  2. API/CLI behavior: Application URLs are independent of the gateway connection. Preserving their advertised public port is the intended behavior, implemented for service expose/list and sandbox creation in this PR. Users enabling application ingress must upgrade their CLI; we accept that older CLIs may display an incorrect URL when application and gateway connection ports differ. Existing gateway-only behavior remains unchanged. We will not preserve gateway semantics in preferred application URLs or add negotiation for this new feature.

Enabled application listeners now require base_url in place of domain. Remove the old key when upgrading and deploy matching gateway/driver/supervisor images. The domain is derived from the HTTPS base URL; its public port remains separate from the supervisor listener port.

Supervisor route declarations are an internal, version-locked deployment protocol. Recreate existing dedicated sandbox Pods with the matching supervisor image when upgrading application ingress: older supervisors cannot acknowledge the new hostname declarations, so their services drop out of discovery until replaced; they also cannot serve hashed application hostnames. Plan for service interruption during replacement. New supervisors require OPENSHELL_APP_BASE_URL from the driver. Mixed-version compatibility fallbacks are intentionally not provided. Updated supervisors retain readable listener aliases.

Protobuf additions remain additive on the wire. Curated SDK callers retain their existing construction paths; new TypeScript URL maps are optional. Hand-written exhaustive generated Rust/TypeScript message literals must include new fields or use generated/default initialization; preserving those literal shapes is outside this change's migration scope.

Python SDK changes are deferred to the external SDK repository; this PR leaves the frozen core SDK files unchanged.

Testing

  • Rebased all five branches onto main df6a799eb, preserving the SPIFFE provider-token limiter and application-auth peer metadata. Branch ancestry, patch scope, and frozen Python/Go SDK checks passed.
  • Standalone URL PR: 2,801 server tests (50 PostgreSQL-dependent tests skipped), 650 core tests, 336 Kubernetes-driver tests, 300 supervisor tests, and 409 CLI library tests passed.
  • Combined auth/discovery-reader/proxy stack: 2,831 server tests (51 PostgreSQL-dependent tests skipped) and all nine proxy tests passed. Strict all-target Clippy passed for server, core, Kubernetes driver, supervisor, CLI, and proxy.
  • Full Helm suites passed for the URL/Helm follow-up, including rendered TOML, resource coherence, ownership, and scaling. The combined stack passed all 500 gateway-chart unit tests. Generated Helm docs, Markdown/MDX lint, Rust formatting, and whitespace checks passed.
  • Fresh live k3d shared/push/graceful E2E passed on the rebased URL/Helm stage with matching locally built images: Pod-IP ingress without app Services, HTTP/WebSockets, Host/SNI, NetworkPolicy, withdrawal/re-exposure, takeover preserving workload identity/process/memory, and listener-disabled gateway fallback using enable_gateway_service_routing: true. The isolated release and namespace were removed.

Dedicated, poll, abrupt-loss, and external-ingress scenarios were not rerun for these review fixes. Current-head GitHub CI is pending.

Qualification limits

Live Kubernetes qualification covers dedicated/shared supervisors, graceful shared-owner replacement, gateway outage, and policy isolation. Hashed URL/public-port behavior is covered by unit tests. Whole-node failure, real network partitions, metric-driven HPA, sustained production load, external ingress/DNS automation, and published release artifacts remain unqualified. Installation-status presentation (#4670) remains separate work. The example Kubernetes HTTPRoute controller remains a separate compatibility POC.

Checklist

  • Follows Conventional Commits
  • Commits are signed off (DCO)
  • Relevant implementation, configuration, and API documentation updated

PR dependency order: #4956 → #4963 → #4964 → #4957.

@copy-pr-bot

copy-pr-bot Bot commented Oct 27, 2026

Copy link
Copy Markdown

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

@github-actions

Copy link
Copy Markdown

@TaylorMutch
TaylorMutch added this pull request to stack #4942 October 27, 2026 02:54
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from a6d0833 to e6e1927 Compare October 27, 2026 03:15
@TaylorMutch
TaylorMutch force-pushed the feat/4667-service-discovery/TaylorMutch branch 2 times, most recently from 932643d to 6c83b66 Compare October 27, 2026 05:42
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from e6e1927 to 2574b9a Compare October 27, 2026 05:42
@TaylorMutch
TaylorMutch removed this pull request from stack #4942 October 27, 2026 05:45
@TaylorMutch
TaylorMutch added this pull request to stack #4965 October 27, 2026 05:46
@TaylorMutch
TaylorMutch removed this pull request from stack #4965 October 27, 2026 05:47
@TaylorMutch
TaylorMutch force-pushed the feat/4667-service-discovery/TaylorMutch branch from 6c83b66 to 755e4d1 Compare October 27, 2026 06:24
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch 2 times, most recently from 70e365e to 30cf9ce Compare October 27, 2026 06:25
@TaylorMutch
TaylorMutch force-pushed the feat/4667-service-discovery/TaylorMutch branch 2 times, most recently from 0944ea2 to 8504067 Compare October 27, 2026 06:46
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 30cf9ce to 6b2fe9c Compare October 27, 2026 06:46
@TaylorMutch
TaylorMutch force-pushed the feat/4667-service-discovery/TaylorMutch branch from 8504067 to feac6b4 Compare October 27, 2026 21:06
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch 2 times, most recently from dae4a9d to 66220a7 Compare October 28, 2026 17:05
@TaylorMutch
TaylorMutch force-pushed the feat/4667-service-discovery/TaylorMutch branch 2 times, most recently from 0939a70 to cf5448a Compare October 28, 2026 22:52
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 66220a7 to 3dc01d7 Compare October 28, 2026 22:52
@purp purp added topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards. topic:documentation Architecture docs, READMEs, project website updates, and automated documentation generation. topic:networking General network transport, connectivity, and proxy behavior. topic:sdk:python Python SDK implementation, maintenance, interfaces, and distribution. topic:sdk:rust Rust SDK implementation, maintenance, interfaces, and distribution. topic:sdk:typescript TypeScript SDK implementation, maintenance, interfaces, and distribution. topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience. labels Nov 15, 2026
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 433b9b9 to 35e2d05 Compare November 16, 2026 19:55
@TaylorMutch
TaylorMutch force-pushed the feat/4667-service-discovery/TaylorMutch branch from fd8af36 to 29c0d05 Compare November 16, 2026 19:55
Base automatically changed from feat/4667-service-discovery/TaylorMutch to main November 16, 2026 21:36
@TaylorMutch
TaylorMutch force-pushed the feat/4953-authoritative-app-urls/TaylorMutch branch from 35e2d05 to c503a94 Compare November 16, 2026 21:48
@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

3. typescript-sdk — No explicit risk acceptance found

Generated raw SandboxResponse, ServiceEndpointResponse, and SandboxServiceRoute types acquire required URL-map, URL, and applicationHostname properties absent from previously valid complete objects.

  • Impact: Typed raw-message fixtures and adapters fail assignment checks, while schema-based initialization and the now-optional curated SandboxRef properties remain compatible.
  • Action: Preserve existing raw TypeScript object shapes for v0.1.9, or defer incompatible additions to a permitted minor train with create(schema, init) migration guidance.
  • PR: feat(services): publish authoritative application origins #4956
Review details
  • Execution: complete
  • Candidate: PR #4956 (8c669ef9f62daea9114916c9482f5b2f05573d2e)
  • Baseline: bf9f55cdf009eaf9b84f486d5c15ff89c9fcf2ca (bf9f55cdf009eaf9b84f486d5c15ff89c9fcf2ca)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. configuration — No explicit risk acceptance found

App-listener TOML domain and supervisor environment variable OPENSHELL_APP_SERVICE_DOMAIN are replaced by base_url and OPENSHELL_APP_BASE_URL without legacy aliases.

  • Impact: Existing gateway TOML fails unknown-field validation, while enabled openshell-supervisor launches using the old environment fail with a missing-base_url error.
  • Action: Retain the legacy TOML key and supervisor environment variable as compatibility inputs, deriving an HTTPS base URL when necessary.
  • PR: feat(services): publish authoritative application origins #4956

2. api-behavior — No explicit risk acceptance found

ServiceEndpointResponse.url and create-time service_urls switch from gateway URLs to application URLs when the application listener is configured.

  • Impact: Older openshell service expose, service list, and sandbox-create clients replace the application port with the gateway connection port, producing unusable URLs when those ports differ.
  • Action: Preserve gateway semantics in the existing URL fields for legacy clients and expose application origins through the new fields or negotiated behavior.
  • PR: feat(services): publish authoritative application origins #4956
Review details
  • Execution: complete
  • Candidate: PR #4956 (e0f79051c0f8c4439881086cb828d34bae487951)
  • Baseline: 4b433e6e3284574866ed0a837a180dbc00ecc800 (4b433e6e3284574866ed0a837a180dbc00ecc800)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

The two changes in the compatibility advisory are intentional and explicitly accepted:

  1. Configuration: The app listener is a new, unsettled feature. Replacing domain/optional public_url with base_url, and the internal supervisor environment variable with OPENSHELL_APP_BASE_URL, is accepted without legacy aliases. Remove the old TOML keys and deploy matching gateway/supervisor images.
  2. API/CLI behavior: Application URLs are independent of the gateway connection. Preserving their advertised public port is the intended behavior, implemented for service expose/list and sandbox creation in this PR. Users enabling application ingress must upgrade their CLI; we accept that older CLIs may display an incorrect URL when application and gateway connection ports differ. Existing gateway-only behavior remains unchanged. We will not preserve gateway semantics in preferred application URLs or add negotiation for this new feature.

The PR compatibility notes now record this acceptance and the migration requirements.

@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test 5500740

@github-actions

Copy link
Copy Markdown

Compatibility review (advisory)

New or updated breaking changes; see the full report for all findings.

1. configuration — Risk explicitly accepted

App-listener TOML/Helm domain and supervisor environment variable OPENSHELL_APP_SERVICE_DOMAIN are replaced by base_url and OPENSHELL_APP_BASE_URL without compatibility aliases.

  • Impact: Existing gateway TOML fails unknown-field validation, enabled shared-supervisor Helm values fail rendering, and supervisor launches using the old environment fail with a missing-base_url error.

  • Action: Defer the alias-free rename to a permitted minor train; v0.1.10 must retain the legacy TOML, Helm, and supervisor environment inputs.

  • PR: feat(services): publish authoritative application origins #4956

  • Acceptance: comment

2. api-behavior — Risk explicitly accepted

ServiceEndpointResponse.url and create-time service_urls previously contained gateway URLs but now prefer application URLs when the application listener is enabled.

  • Impact: Older openshell service expose, service list, and sandbox-create clients replace the advertised application port with the gateway connection port, producing unusable URLs when those ports differ.

  • Action: Preserve gateway semantics in existing url and service_urls fields for v0.1.10, exposing application origins through the new fields or negotiated behavior.

  • PR: feat(services): publish authoritative application origins #4956

  • Acceptance: comment

Review details
  • Execution: complete
  • Candidate: PR #4956 (b451e5dc6c9977015e724d089bb9c83987cbc7b3)
  • Baseline: 78ba34775a34dcc8b01fd13cc30c10c1940a113a (78ba34775a34dcc8b01fd13cc30c10c1940a113a)
  • Reviewed: rust-sdk, python-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

@pimlock pimlock left a comment •

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Thanks, the overall shape looks right. Sharing one hostname policy across URL responses, supervisor config, discovery, and SNI/Host removes a real source of drift. Having the gateway send application_hostname is the right call, because the hashed label depends on the gateway name, which the supervisor doesn't have.

I checked the routing toggle against a local Docker gateway at this head. With service_routing_enabled=false, the gateway returned 404 for every request I tried:

  • plain HTTP
  • WebSocket upgrade
  • HTTP/2 prior knowledge
  • uppercase and trailing-dot Host
  • the app-domain Host
  • an IP Host
  • the loopback plaintext listener

base_url validation rejected http://, paths, IP literals, userinfo, trailing dots, and the legacy domain key. https://APPS.example.com:10443 was normalized to lowercase and kept its port. Hashed labels matched an independently computed SHA-256/base32 label.

Most of my comments are inline. The upgrade items are collected below because they cut across files.

Upgrades

1. A new gateway rejects installation reports from v0.1.9 supervisors, so running sandboxes drop out of discovery (should)

crates/openshell-server/src/grpc/service.rs:454 → crates/openshell-server/src/grpc/service_advertisement.rs:156

When the listener is enabled, configured_app_routes_from_endpoints now always sets application_hostname. A v0.1.9 supervisor decodes the route without field 6, so the routes it reports back don't include it (snapshot.routes.values().cloned() in the v0.1.9 supervisor). validate_routes compares routes with full struct equality (declared.contains(route)), so every report from an old supervisor fails with "installed service route is not a current declaration".

The result: after a Helm upgrade, a running sandbox whose pod still has the old supervisor disappears from discovery until the pod is recreated. The impact is narrow. It needs all of these:

  • the app listener is enabled, which is opt-in and Kubernetes-only, and these operators already have to edit domain → base_url in this upgrade
  • the sandbox has at least one exposed service routed by hostname (sandboxes with no routes send empty reports, which still validate)
  • the sandbox's pod still runs a v0.1.9 supervisor (dedicated-mode pods created before the upgrade; the shared DaemonSet and new sandboxes are fine)

Only discovery and app-listener ingress are affected; gateway_url routing keeps working. In hashed mode, the old supervisor also can't serve the hashed application_url, because it splits SNI on --. The legacy branch at service_discovery.rs:487 handles records stored by an older gateway, but not this direction.

Suggested fix: when the reported application_hostname is empty, compare the route with that field ignored. Then use the readable hostname for that installation, both in discovery and when choosing which application_url to publish. A test that sends a report with an empty application_hostname to a new gateway would cover it. If you'd rather not change the code, a line in the upgrade note ("recreate app-listener sandboxes after upgrading") would also cover it.

2. A new supervisor configured by an older driver fails at startup (should)

crates/openshell-supervisor/src/app_listener.rs:60

The supervisor now requires OPENSHELL_APP_BASE_URL. A driver from before this change sets only OPENSHELL_APP_SERVICE_DOMAIN, so from_values errors out and the sandbox or shared supervisor crash-loops. Helm usually rolls the driver and supervisor together, so this needs skew (a pinned supervisor image, or a DaemonSet that rolls first). A one-release fallback would turn it into a soft degrade: when OPENSHELL_APP_BASE_URL is absent, use https://<OPENSHELL_APP_SERVICE_DOMAIN>.

3. domain → base_url (acknowledged, no change requested)

Removing the v0.1.9 domain key is a deliberate, accepted break, and it fails loudly: the gateway refuses to start with "unknown field domain". I'm fine with it as is. Two small text fixes so operators and agents aren't misled:

4. Older CLIs rewrite the application port (FYI)

docs/how-it-works/gateways/configuration.mdx:2232 already says to upgrade the CLI alongside the gateway. That's worth carrying into the release notes together with item 3.

Comment thread crates/openshell-cli/src/run.rs Resolved
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
Signed-off-by: Taylor Mutch <taylormutch@gmail.com>
@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

/ok to test f8d1af1

@TaylorMutch

Copy link
Copy Markdown
Collaborator Author

Following up on the upgrade notes in your review:

  1. Older supervisors and discovery: Took the documented-upgrade option. The configuration reference, operational skill, PR compatibility notes, and release notes now require replacing existing dedicated sandbox Pods with the matching supervisor image and planning for service interruption. Older supervisors cannot acknowledge the new hostname declarations or serve hashed application hostnames.
  2. New supervisor with an older driver: We are retaining the internal, version-locked deployment contract. The upgrade guidance explicitly requires matching gateway/driver/supervisor images and explains that new supervisors require OPENSHELL_APP_BASE_URL; the old environment variable is not a compatibility input. We are intentionally accepting this version-skew limitation rather than adding a fallback.
  3. Configuration wording: Removed the never-shipped public_url migration reference and its test case. The docs now describe base_url = "https://<domain>" replacing domain, and the operational skill uses port and base_url.
  4. Older CLI port handling: The release notes now include upgrading the CLI alongside the gateway when enabling application ingress.

The six inline comments have code fixes and targeted regression coverage where applicable. Standalone and combined server tests, proxy tests, strict Clippy, Helm/runtime-parser checks, and the shared-listener k3d takeover/fallback E2E passed; PostgreSQL-dependent server tests were skipped. Mixed-version fallback support is outside the agreed scope.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:platform SDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management. topic:api Public APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards. topic:documentation Architecture docs, READMEs, project website updates, and automated documentation generation. topic:networking General network transport, connectivity, and proxy behavior. topic:sdk:python Python SDK implementation, maintenance, interfaces, and distribution. topic:sdk:rust Rust SDK implementation, maintenance, interfaces, and distribution. topic:sdk:typescript TypeScript SDK implementation, maintenance, interfaces, and distribution. topic:ux CLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(services): publish authoritative application origins independently of API transport

4 participants