[TaylorMutch]

Summary

Persist validated, expiring evidence of application routes installed by supervisors. Integrate the shared-supervisor ownership authority merged in #4864 so dedicated and shared installations can be advertised safely.

Based on main at 32dcc4a67.

Related Issue

Closes #4939. Part of RFC 0017.

Changes

• Resolve trusted application endpoints through the optional ComputeDriverAppEndpoints.ResolveSupervisorAppEndpoint extension RPC, independently of GetSandbox. The baseline ComputeDriver service and existing factories remain compatible. In-process factories register the optional resolver during build; unsupported drivers withhold publication; resolution failures cannot fail ordinary sandbox observations.
• Fence installation reports and discovery eligibility by runtime, configuration, session, credential epoch, current acknowledged pool owner, and process/member readiness.
• Resolve shared application endpoints from trusted Kubernetes membership and Pod state, independently of runtime control addresses.
• Revalidate durable authority before each serving lease; enforce absolute lease expiry and a shared listener serving-authority bound of at most 15 seconds, closing stale streams.
• Preserve workload identity across owner changes; keep gateway-session identity independent of supervisor takeover identity.

Application route advertisement flow

This PR records which application routes a supervisor has actually installed, together with a trusted endpoint and an expiry.

flowchart TB
    subgraph Supervisor["Supervisor — dedicated or shared"]
        Config["Apply sandbox service configuration"]
        Listener["Application listener<br/>Installed routes"]
        Report["Installation report<br/>Routes + configuration identity<br/>Session identity + lease sequence"]
        Config --> Listener
        Listener --> Report
    end

    subgraph Gateway["OpenShell gateway"]
        Session["Authenticated supervisor session<br/>App listener enabled + capability advertised"]
        Lease["Issue single-use lease challenge<br/>Every 5 seconds · expires within 15 seconds"]
        Validate["Validate report<br/>Current session, runtime and configuration<br/>Current ownership and readiness"]
        Resolve["ResolveSupervisorAppEndpoint<br/>Optional compute-driver extension RPC"]
        Accept["Accept installation evidence<br/>Routes + trusted endpoint + expiry"]
        Session --> Lease
        Validate --> Resolve
        Resolve --> Accept
    end

    Authority[("Shared ownership and membership state")]
    Driver["Kubernetes compute driver<br/>Resolve dedicated supervisor Pod IP<br/>or acknowledged shared owner's Pod IP"]
    Store[("Shared installation records<br/>One per sandbox<br/>Expiring, conditionally updated")]

    Lease -->|"Challenge over existing session"| Listener
    Report -->|"Response over existing session"| Validate
    Authority -->|"Fence stale owners and sessions"| Validate
    Resolve --> Driver
    Driver -->|"Trusted Pod IP + app port"| Resolve
    Accept --> Store

Loading

The supervisor reports what it installed; the compute driver determines where it can be reached. The gateway combines those only after validating current authority. Multiple gateway replicas use shared state to validate ownership.

During shared-supervisor takeover, old evidence becomes ineligible. The replacement must install the configuration and report it before its endpoint can be published. Shared listeners also lose serving authority when their lease expires, closing stale application streams.

This PR supplies the evidence used by the later discovery API. It does not create ingress resources or carry application traffic through the gateway. Installation evidence does not establish application health or external ingress readiness.

Release Notes

Testing

• 40 focused combined-stack Rust regression tests cover listener routing, route-limit concurrency, shutdown fencing, advertisements, discovery, and proxy behavior.
• Local k3d validated the Service removal with dedicated push/poll, abrupt shared-owner takeover, HTTP/WebSockets, network-policy denial, freshness/withdrawal, outage recovery, and disabled-listener gateway access. Workload identity and memory survived owner changes.
• Discovery API snapshots/watches and workspace-restricted discovery credentials drove two proxy replicas; both followed Pod-IP endpoints, graceful owner handover, and route withdrawal without per-sandbox app Services.
• Helm lint/unit/parser/coherence/scaling checks, Python lint/format/type checks, and topology assertions passed.

Live Kubernetes validation preceded integration of the latest listener hardening;
focused Rust regressions validate that final integration. New-head CI is pending.

Qualification limits

Live HA validation exercised supervisor process/Pod loss on a local k3d cluster. Whole-node failure, real network partitions, metric-driven HPA, sustained production load, and published release artifacts remain unqualified. Grant-file projection contributes to revocation propagation time. Main now includes #4842 for gateway-mediated hashed hostnames. Direct application-listener/discovery hostnames remain readable; extending hashed naming to that path and installation-status presentation (#4670) remain separate work.

The example Kubernetes HTTPRoute controller is a deferred compatibility POC outside this stack.

Checklist

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

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

[copy-pr-bot]

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]

🌿 Preview your docs: https://nvidia-preview-pr-4940.docs.buildwithfern.com/openshell

[github-actions]

Compatibility review (advisory)

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

1. rust-sdk — No explicit risk acceptance found

Complete raw::proto::SupervisorHello literals now require supports_service_advertisements, while the session Payload enums gain ServiceAdvertisement and ServiceRouteLease variants.

• Impact: Existing complete literals, exhaustive destructuring, and exhaustive payload matches fail to compile; ordinary client calls and unchanged server-trait implementations are unaffected.
• Action: Preserve the baseline exported message shapes for v0.1.7, or defer these changes to a minor release with guidance for supports_service_advertisements: false, default initialization, and both new match arms.
• PR: feat(supervisor): advertise accepted application route installations #4940

2. typescript-sdk — No explicit risk acceptance found

@nvidia/openshell-sdk/raw gains required SupervisorHello.supportsServiceAdvertisements and expands the session payload unions with serviceAdvertisement and serviceRouteLease cases.

• Impact: Existing complete SupervisorHello objects and exhaustive payload switches using never checks fail type checking, while schema-based initialization and ordinary RPC calls remain compatible.
• Action: Preserve the baseline raw types for v0.1.7, or defer these changes to a minor release with guidance for supportsServiceAdvertisements: false, schema-based initialization, and both new switch cases.
• PR: feat(supervisor): advertise accepted application route installations #4940

Review details

• Execution: complete
• Candidate: PR #4940 (0210e41b8a99e1ed636403f473225ca7c68f9b31)
• Baseline: 6925a44d6b3f1bf684578d8d71b9992c1d68ac47 (6925a44d6b3f1bf684578d8d71b9992c1d68ac47)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run

[TaylorMutch]

Regarding the compatibility findings above: these changes affect the internal gateway–supervisor session protocol, which proto/openshell.proto explicitly documents as a version-locked deployment protocol rather than a public sandbox client API.

The raw Rust and TypeScript bindings expose those messages, so the reported source changes are real: complete SupervisorHello literals and exhaustive session-payload matches may need updating. The curated public SDK APIs and existing sandbox client RPC contracts are unchanged by these additions.

The protobuf additions are wire-compatible. The gateway issues application route leases only when the app listener is enabled and the supervisor advertises supports_service_advertisements; an older supervisor omitting that field defaults to false and receives no route leases.

The PR author has explicitly accepted the source-compatibility impact on this internal contract. Public-facing API compatibility remains the requirement; these findings do not warrant deferring or redesigning the internal protocol additions.

[github-actions]

Compatibility review (advisory)

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

1. rust-sdk — Risk explicitly accepted

raw::proto::SupervisorHello gains the required supports_service_advertisements field, while the two session Payload enums gain ServiceAdvertisement and ServiceRouteLease variants.

• Impact: Existing complete literals, exhaustive destructuring, and exhaustive payload matches fail to compile; ordinary client calls and existing server-trait implementations remain compatible.

• Action: This no-break change requires preserving the baseline raw shapes; a deferred breaking migration needs notice covering supports_service_advertisements: false, default initialization, and both new match arms.

• PR: feat(supervisor): advertise accepted application route installations #4940

• Acceptance: comment

2. typescript-sdk — Risk explicitly accepted

@nvidia/openshell-sdk/raw gains required SupervisorHello.supportsServiceAdvertisements and expands the session payload unions with serviceAdvertisement and serviceRouteLease cases.

• Impact: Existing complete SupervisorHello objects and exhaustive payload switches using never checks fail type checking; schema-based initialization and ordinary RPC calls remain compatible.

• Action: This no-break change requires preserving the baseline raw types; a deferred breaking migration needs notice covering supportsServiceAdvertisements: false, schema-based initialization, and both new switch cases.

• PR: feat(supervisor): advertise accepted application route installations #4940

• Acceptance: comment

Review details

• Execution: complete
• Candidate: PR #4940 (aafa33e37b3bd4117f436ff0522136e34e8d9be2)
• Baseline: 32dcc4a67f4939b71d72b0efb392c2c0998e48ac (32dcc4a67f4939b71d72b0efb392c2c0998e48ac)
• Reviewed: rust-sdk, python-sdk, go-sdk, typescript-sdk, api-behavior, cli, configuration, policy, helm, state

Advisory review; publication gates are unchanged.

Branch check run