Repository navigation
feat: add shared Connect/gRPC contract for the playground - #1
Merged
Merged
Conversation
Add the Playground contract as two protobuf packages: - playground.api.v1: browser-facing Language, Execution, Share, Settings and Auth services. Messages carry no user ids, request ids or limit-raising fields; identity comes from the session at the gateway. Every input is bounded with protovalidate rules (file count, path alphabet without dot segments, per-file and stdin size, argument count, id formats). - playground.svc.v1: services the gateway calls over mTLS. Requests carry a gateway-built CallContext (principal, request id, client IP) and execution requests carry an ExecutionPolicy enforced by the sandbox. Runtime commands are argv arrays, images are pinned by digest. The service package is named svc rather than internal because Go does not allow importing generated code under an internal/ path from another module.
Generated with protoc-gen-go, protoc-gen-connect-go (connect v2) and protoc-gen-go-grpc (service package only). go/limits holds limits that protovalidate cannot express, such as the total source size, plus the edge read limits. go/validationtest checks that the declared rules reject path traversal, duplicate paths, oversized input and malformed ids.
@kingsejong-lang/playground-proto exports the generated schemas and service descriptors for connect-es v2 and a limits module mirroring the Go helpers. Only playground.api.v1 is generated for the browser. The package ships dist/ only and has no install scripts. Tests run the same validation rules as the Go suite.
SECURITY_PROTOCOL.md records the defects found in the previous gateway, the threat model, the layered request checks (body size, origin, session, rate and concurrency limits, validation, admission, owner checks) and the sandbox rules. RPC_DESIGN.md maps every old REST, WebSocket, SSE and gRPC-Web call to the new RPCs and defines the Run stream. ROADMAP.md lists the remaining work.
CI runs buf lint and format checks, breaking-change detection against the base branch, verifies that generated code is up to date, and runs the Go and TypeScript tests. Pushing a vX.Y.Z tag attaches the npm package tarball to a GitHub release.
CI generates TypeScript code with the generator installed by npm ci; without it buf generate fails with 'protoc-gen-es not found'.
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
Adds the shared protobuf contract for the KingSejong Playground. Until now the frontend and the backend each kept their own copy of the
.protofiles (the copies had already drifted), and the gateway exposed every internal RPC to browsers through an unauthenticated gRPC-Web proxy. This repository becomes the single source of the API, with generated Go and TypeScript code and documented security rules.Design
playground.api.v1is the browser-facing API (Language, Execution, Share, Settings, Auth).playground.svc.v1is what the gateway calls over mTLS. Nothing insvcis ever mounted on the public listener.CallContextand anExecutionPolicyto the services. API keys can only be created for the caller../..segments, 64 KiB each), stdin (64 KiB), arguments (16 × 256 B), wall time and id formats. The total-size limit, which CEL cannot express, lives ingo/limits, and the TS package mirrors it.ExecutionService.Runis a server stream of typed events (accepted, queued, started, output, diagnostic, truncated, heartbeat, finished) with a sequence number. Closing the stream cancels the run.svc, notinternal, because Go refuses imports of generated code under aninternal/path from another module.Docs:
docs/SECURITY_PROTOCOL.md(threat model, request checks in order, sandbox contract, acceptance tests),docs/RPC_DESIGN.md(old endpoint → new RPC map, stream semantics, versioning) anddocs/ROADMAP.md(open work).Testing
buf lintandbuf format --diff --exit-code: clean.go vet ./...andgo test ./...:go/limitsandgo/validationtestpass. The 18 validation cases include path traversal, absolute paths, duplicate paths, 17 files, 65537-byte stdin, bad execution ids and an invalid email.ts:npm run buildandnpm test(vitest, 7 tests) pass;npm packcontains onlydist/.Not verified
v0.3.0will be its first run.