Repository navigation
omm: support the OpenShell v0.1.9 middleware contract - #106
Merged
Merged
Conversation
omm create failed for every OpenShell release since v0.1.0 because the supervisor middleware proto imports extension.proto, which omm did not download. The starter templates also still implemented the v0.0.86 contract. Generator: - Download the OpenShell protos that the middleware proto imports, record them in the manifest, and compile them into the Python bindings. - Publish each generator-owned proto file on update by exchange, add, or removal with rollback, and refuse to overwrite an unrecorded file that differs from the imported one. - Require the HTTP hooks contract (OpenShell v0.1.9 or newer) in omm create and report older releases before generating anything. Templates: - Negotiate extension protocol metadata in Describe. - Implement HttpHooks.EvaluateHttpRequestHook with preflight and whole-body extension points in the Python and Rust starters. Verification: - Add scripts/verify-openshell-release.sh, which generates both starters and sends sandbox traffic through them behind a real OpenShell gateway. Signed-off-by: Johnny Greco <jogreco@nvidia.com>
- Rust starter: build with tonic's generated default stubs and delete the hand-written "unimplemented" methods and stream types. A contract that adds or removes an RPC the starter does not implement, such as the removal of EvaluateHttpRequest announced for OpenShell 0.2.0, no longer breaks generated projects. - Verification script: turn errexit off inside the cleanup handler so a failing cleanup command cannot skip stopping the gateway and services or replace the exit status. - Generated READMEs: list the imported protocol files as part of the downloaded contract that the manifest records. Signed-off-by: Johnny Greco <jogreco@nvidia.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
omm createcould not produce a project for any OpenShell release since v0.1.0. The latest stable release is v0.1.9 (published 2026-11-17). This PR makesommwork with it and adds a repeatable check that proves it against a real gateway.There were two separate problems:
supervisor_middleware.protoimportsextension.proto.ommdownloaded only the one file, so binding generation failed withextension.proto: File not found.Describe, and made protocol negotiation mandatory. v0.1.9 adds streaming HTTP hooks and deprecates the unary request RPC for removal in 0.2.0.What changed
Generator
ommdownloads the OpenShell protos that the middleware proto imports, records each in the manifest underproto_importswith its source URL and SHA-256, and compiles them into the Python bindings. An import must be a plain file name; anything else is rejected before a file is written.omm updatepublishes each generator-owned proto file on its own: it exchanges a file the project already has, adds a new one without replacing anything, and moves out one the contract no longer imports. Each step rolls back if a later one fails. It refuses to overwrite a file inproto/that it did not record, unless that file is byte-identical to the imported one.omm createrequires a contract withservice HttpHooksand reports an older release immediately.Templates (Python and Rust)
DescribeacceptsMiddlewareDescribeRequest, checks the caller's protocol metadata, and returns the service's own (protocol 1.0, contract and HTTP hooks capabilities).HttpHooks.EvaluateHttpRequestHook. The starter continues without reading the body.evaluate_http_request_preflightandevaluate_http_request_bodyare the extension points.Verification script
scripts/verify-openshell-release.shdownloads a release's gateway and CLI into a temporary directory, generates both starters, and sends sandbox traffic through them.Decisions
omm createnow needs OpenShell v0.1.9 or newer (decided: follow OpenShell's recommendation). The starters use HTTP hooks. OpenShell's v0.1.9 documentation says "New HTTP middleware should implement HTTP Hooks", and its proto marks the unary request RPC as deprecated for removal in 0.2.0. Keeping the unary RPC would have covered v0.1.0 through v0.1.9, but new projects would need a rewrite at 0.2.0. Version 0.0.1 on PyPI still creates v0.0.86 starters (checked).AGENTS.mdsaysommmust never install or configure OpenShell. The script is separate fromomm, keeps everything in its work directory, and uses its own container label, ports, and database.proto_imports(open for review). Manifests without it still load.Contract history, from the protos at each tag:
max_body_bytes,Describe(Empty)max_payload_bytesextension.proto,Describe(MiddlewareDescribeRequest), unary request RPC onlyHttpHooksservices, deprecates the unary RPCVerification
Run on Linux x86_64 with Docker 29.9.1 and uv 0.13.4, using the official v0.1.9 release binaries (checksums verified).
Real gateway, both starters
cd projects/tools/openshell-middleware-manager scripts/verify-openshell-release.sh --openshell-version v0.1.9All 30 checks pass in about two minutes with Rust 1.90.0, the starter's declared minimum. The Rust half also passes with Rust 1.100.0.
omm create, thenomm update, then every check the generated README listsDescribefirst and exits on a mismatch)openshell gateway inforeports protocol 1.0 with the HTTP hooks capability requiredALLOWED ... http_event_kind:middleware_invocation ... failed:falsemiddleware_failedand never reaches the upstreamFull output
The script fails when it should
mainomm create:extension.proto: File not foundStarter extension points
I edited each generated starter the way its README describes, using the README snippet verbatim, and ran it behind the same gateway. This was a manual run, not part of the script. Python and Rust gave the same results.
note: prototype-secret insidenote: [REDACTED] insideand the added header. OpenShell logstransformed:true.x-omm-probe: denymiddleware_deniedwithreason_code: omm_probe_denied. The upstream is not contacted.[REDACTED], so a body at the 4 MiB platform maximum crosses gRPC in both directions.omm updateRun on a project created by the published
omm0.0.1 at v0.0.86.--check-commandproto/extension.protois added. Only the manifest, proto, and bindings change. A user file inproto/keeps its inode.proto/extension.protois removed; the user file staysproto/extension.protoextension.protoOther checks
ruff format --check,ruff check,ty check,pytest(118 passed, 96.16% coverage;mainhas 95 tests at 95.88%), anduv build. The tests also pass on Python 3.10.uvx, creates a Python starter with--openshell-version latest, creates a Rust starter, and runsomm update.a,request.audit_log-v2, andpartner-api-content-guard-v2pass their checks in both languages.omm createfor v0.1.8, v0.1.0, v0.0.116, and v0.0.86 reports the new minimum-release error and leaves nothing on disk.python3 scripts/update_license_headers.py --checkpasses.bd04b4e: Claude Opus 5.5, Claude Fable 5.2, and GPT-6.1 Sol, each at high effort. Fable's review of the generator's file safety was clean. Three findings were accepted and fixed in6c7b6e0: the script's cleanup could abort underset -eand leave its gateway running; the Rust starter hand-wrote stubs for unused RPCs; and the generated READMEs did not list the imported protocol files as generator-owned. The live run, the stable-Rust run, and the Rust extension-point run above were repeated on6c7b6e0.Not verified, and known limits
renameatx_npwithRENAME_EXCLon macOS, which is untested. The script supports Linux only.allow_insecure_transport). TLS and token-authenticated registrations were not tested; the starters remain unauthenticated development servers.docs/changed.uv_build>=0.11.8,<0.12.0pin excludes the running uv. Builds still succeed.Reviewed with sol-loop: 2 rounds with gpt-6.1-sol on high. Sol verdict: approved.
🤖 Generated with Claude Code