Skip to content

feat(services): publish authoritative supervisor ingress URLs and status #4670

Closed as not planned

Description

@TaylorMutch

Disposition

Authoritative application URL publication landed through #4953 / #4956, using supervisor.app_listener.base_url and preserving the public origin/port independently of the gateway API connection.

The remaining user-facing installation-status presentation is deferred. Existing discovery evidence and supervisor diagnostics support ingress consumers and operators; a separate configured/advertised/unavailable display would not establish DNS, ingress, TLS, or application health. It is not required for the initial RFC 0017 scope. Revisit it when a concrete troubleshooting workflow justifies the additional API and presentation logic.

The original replay criterion below is superseded by the implemented contract: idempotent retries preserve the originally returned URL bundle; Get/List return current addresses. The configuration example below also predates the consolidated base_url setting.

Closing this umbrella issue with URL publication delivered and installation-status presentation deferred.


User Story

I use OpenShell CLI and SDKs to run sandboxes that include an addressable service. I need the returned service URL to reach my configured application ingress, and status to distinguish a declaration from an installed route.

Problem Statement

With supervisor ingress, the gateway API endpoint and public application origin can differ. Returning or reconstructing gateway URLs sends clients to the wrong host/port, and a declaration alone does not establish route installation.

Impact / Why This Matters

Users must manually construct application URLs and cannot tell whether ingress configuration or supervisor installation is missing.

Proposed Design

Add public URL publication under the supervisor app-listener configuration introduced in #4666. Keep the hostname layout and derive named/unnamed service URLs from the configured HTTPS origin, independently of the API endpoint.

Gateway and supervisor ingress coexist. Publishing a supervisor URL does not remove gateway ingress or change either authentication boundary. Define how CLI and SDK responses identify the available addresses; if a primary URL preference is retained, it is presentation behavior, not an exclusive listener mode.

Document the authentication boundary with each ingress path: gateway service URLs use gateway-mediated authentication, while app-listener URLs use the operator's chosen data-plane authentication. URL selection must not silently change or bypass the selected path's access controls.

Expose configured, advertised, and unavailable installation states, explicitly separate from application health. Keep create-time exposure, service commands, and durable mutation replays consistent. This supports an operator-managed ingress implementation without requiring the reference proxy.

Suggested UX

[openshell.supervisor.app_listener]
enabled = true
port = 8443
domain = "services.example.com"
public_url = "https://services.example.com"

The table and enabled/port/domain fields belong to #4666; public_url is added by this issue. The listener port is internal to the supervisor; public_url may use a different port, such as standard HTTPS 443. This is proposed configuration syntax. A service on sandbox app-sandbox in workspace default returns https://default--app-sandbox.services.example.com/. openshell service list reports its installation state. Hostname hashing is separate existing work in #4631.

Acceptance Criteria

  • Create-time exposure and service expose/list/get return the configured application origin for named and unnamed services.
  • CLI and SDK callers preserve the origin and public port even when accessing the API through another endpoint or port-forward.
  • Status distinguishes configuration, accepted installation evidence, and unavailability without claiming application health.
  • Durable replay responses reflect current ingress configuration while preserving original resource identities.
  • Invalid origins/domain mismatches fail clearly; the supervisor app listener remains opt-in and existing service ingress remains available.
  • Public URL preference never disables gateway routing or makes the supervisor listener inherit gateway authentication.
  • Tests cover API, CLI, SDK, installation/withdrawal, configured nondefault ports, and operator-managed ingress.
  • Documentation describes the public DNS/TLS/ingress prerequisites and authoritative URL workflow.

Alternatives Considered

Client-side URL rewriting couples clients to gateway transport details. Manual URL construction is error-prone. Requiring the reference proxy would exclude existing ingress integrations. Middleware, interceptors, and providers do not define service URL publication or installation status.

Agent Investigation

Keep gateway URL configuration, protobuf status fields, mutation replay, CLI output, and SDK conversions consistent. Regenerate affected bindings and the schema inventory as part of this issue.

Activity

  1. self-assigned this
    on Oct 16, 2026
  2. added
    area:platformSDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management.
    topic:apiPublic APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.
    topic:authnzAuthentication, authorization, identity, sessions, credential protection, and policy integrity.
    topic:networkingGeneral network transport, connectivity, and proxy behavior.
    topic:uxCLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience.
    on Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

area:platformSDKs, CLIs, APIs, gateway infrastructure, persistence, configuration, and session management.state:acceptedA maintainer decided OpenShell should pursue this issuetopic:apiPublic APIs, gRPC/protobuf, SDK interfaces, versioning, compatibility, and API design standards.topic:authnzAuthentication, authorization, identity, sessions, credential protection, and policy integrity.topic:networkingGeneral network transport, connectivity, and proxy behavior.topic:uxCLI commands/flags, help, errors/exit codes, human-readable output, TUI, and first-run experience.

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions