View on GitHub

OdbDesign ODB++ Parser

REST API and C++ library for parsing ODB++ Design archives

OdbDesignServer — open issues: options & recommendations (SI1–SI8, SI19)

   
Status DECIDED 2026-09-10 — all decisions resolved (per-item NOTE remarks + follow-ups): SI4 = Option 1, REST TLS cert source = Option C (cert-manager private CA). Execution tracked in server-issues-implementation-plan.md; first tranche on nam/server-issues-impl.
Date 2026-09-09
Scope OdbDesignServer (Crow REST + gRPC), CI / GitHub Pages publishing, branch topology
Related https-tls-options.md (REST TLS decision, §8 gRPC TLS) · gh-pages-coverage-integration.md · opt/phase2-grpc-optimizations.md

Each issue: Current state (facts, with code references) → Options (pros/cons) → Recommendation + why → Dependencies / effort.


Original task list (verbatim)

Create a doc with options + pros/cons and recommendations + why for all of these issues.

  • SI1 add redoc page — maximally annotated to maximize detailed type and api behavior in redoc page’s definitions — /redoc
  • SI2 add coverage report HTML to the pages site when deploying pages — do we generate results and coverage reports per environment branch (i.e. development, staging, main, release)? — post per-branch for development, staging, main, release (not main)
  • SI3 do we need the main branch? it seems like development, staging, main, release are only ones we need. Actually, ideally we would be using production instead of main. Dont change unless risk is totally nontrivial.
  • SI4 grpc tls
  • SI5a Need unified overall authentication mechanism that is more secure than Basic we have for REST and nothing we have for grpc
  • SI5b Need Authorization scheme based on logged-in user and resource-by-resource (grpc and REST). Both communication channel type AND specific data resources (e.g. only designs you have uploaded or are shared to all users). Need regular interactive client scheme AND device flow in addition to for machine → server auth
  • SI6 Server-side optimizations — any optimizations options? (client design fetching, loading, display, and visibility toggle has been heavily optimized, >10x faster fetch→load→display, almost instantaneous component and layer visibility toggling)
  • SI7 RequestLoadDesign(Async): start a FileArchive/Design load (parse) and return immediately. Next GetDesignAsync request for that same design can skip loading and return response data immediately
  • SI8 server communication channel — non-language-specific: SSE? websockets? optional connection and use — app still functions, falls back even if connection is not attempted or attempted but can’t complete successfully
  • SI19 remaining grpc optimization items from docs/plan/opt/phase2-grpc-optimizations.md — implement remaining issues from the previous grpc optimization round

Server today (shared context)

Facts referenced by several sections below; verified 2026-09-09.

Area Current state
REST framework Crow 1.3.3 (vcpkg.json override), crow::Crow<crow::CORSHandler> (Utils/crow_win.h). GZIP response compression on (OdbServerAppBase.cpp, use_compression(GZIP)); CORS wide open (origin("*"), headers("*"), OdbDesignServerApp.cpp). No TLS in-app (OdbDesignArgs::useHttps() is a dead declaration — declared, never implemented, never called).
REST auth HTTP Basic, enforced by an explicit AuthenticateRequest(req) call inside every protected route lambda (e.g. DesignsController.cpp, FileModelController.cpp). Credentials from ODBDESIGN_SERVER_REQUEST_USERNAME/PASSWORD env vars with hardcoded fallback odb/plusplus when unset (OdbDesignLib/App/BasicRequestAuthentication.cpp). Bypass in _DEBUG + Environment=Local. Unauthenticated: /healthz*, /ready, /helloworld*.
gRPC Odb.Grpc.OdbDesignService (OdbDesignServer/protoc/grpc/service.proto): GetDesign, GetLayerFeaturesStream, GetLayerFeaturesBatchStream (feature-flagged), GetLayerSymbols, GetStandardFonts, HealthCheck; reflection + standard health service enabled. Bound with InsecureServerCredentials() (OdbDesignServerApp.cpp) — no auth at all, no interceptors anywhere. gzip default compression; 250 MB max message (OdbDesignServer/config.json).
Design loading One shared DesignCache (OdbDesignLib/App/DesignCache.cpp) for REST + gRPC: shared-lock read, on miss synchronous parse in the requesting call (minute-scale for large designs), double-checked insert. No eviction, no in-flight dedup, no serialized-response cache — every REST response re-runs protobuf to_json(). List endpoints rescan the designs directory per call. Uploads (FileUploadController) write the archive but never parse it. --load-all startup preload exists but no deployment uses it.
API docs Hand-maintained OpenAPI 3.0.3 spec: swagger/odbdesign-server-0.9-swagger.yaml (37 paths, already tagged/example-annotated). Served by a sidecar container (ghcr.io/nam20485/odbdesignserver-swaggerui, separate repo) whose spec is refreshed via ConfigMap (scripts/deploy.ps1 → deploy/kube/OdbDesignServer-SwaggerUI/swagger-spec-configmap.yaml); Traefik routes /swagger to it (deploy/kube/local-ingress.yaml). No ReDoc anywhere.
Pages / CI Pages deploys the Jekyll docs/ site on push to release only (.github/workflows/jekyll-gh-pages.yml; custom domain source.odbdesignserver.com; Doxygen runs but the copy-to-site step is commented out). Coverage workflow (.github/workflows/code-coverage.yml, lcov + genhtml → HTML, artifact linux-coverage-report, 14-day retention, Codacy upload) runs on push/PR for development, staging, main, release, nam20485.
Branch topology nam/<feature> → nam20485 → development → staging → main → release; production is defunct legacy (see AGENTS.md). Ruleset 169360 covers main/release/staging/production and requires the three CMake legs, SBOM, Codacy, dependency-review and Docker-Build-and-Publish.

SI1 — add ReDoc page at /redoc, maximally annotated

Current state

The OpenAPI spec (swagger/odbdesign-server-0.9-swagger.yaml) is the single source of truth and is already well-annotated (info block, per-tag descriptions, response examples). Swagger UI is a sidecar container; ReDoc is not deployed anywhere. The spec is hand-maintained — there is no generator in-repo (the “GENERATED from route registrations” header is aspirational).

Options

Option 1 — redoc.html in the existing Swagger UI sidecar. Add a static redoc.html (redoc-standalone: one HTML file + CDN script tag pointing at the existing spec URL) next to swagger-ui in the sidecar image / nginx content; route /redoc to the sidecar exactly as /swagger is routed today (Traefik ingress + nginx compose catch-all already exist).

Option 2 — serve /redoc + /openapi.json from the Crow binary. Embed the spec (CMake define or a resource compiler) and serve it plus a bundled redoc.html from the server itself.

Option 3 — publish a static ReDoc build to the GitHub Pages site. Build redoc-cli bundle (or a redoc.html + spec copy) into the Jekyll site, e.g. at /api/redoc — the same mechanism SI2 will use for coverage, and the slot docs/README.md already (stale-)links to (…github.io/OdbDesign/api).

Annotation work (orthogonal to hosting — it’s all in the YAML). Whatever hosts the page, “maximally annotated” means investing in swagger/odbdesign-server-0.9-swagger.yaml:

  1. Property-level description: on every schema (source material already exists as comments in OdbDesignLib/protoc/*.proto).
  2. Complete error response sets per operation (400/401/403/404/500 — several operations currently document only success + 401/404).
  3. example/examples on all large schemas (StepDirectory, LayerDirectory, FeaturesFile, MatrixFile, Design).
  4. commonParameters/header docs, and deprecated markers on the commented-out legacy routes if they return.
  5. When SI5 lands: replace the global BasicAuth security scheme with the new scheme(s), per-route.

Recommendation

Option 1 now, Option 3 as the public home; keep Option 2 in the back pocket. Option 1 is pure deployment config on infrastructure that already routes /swagger — the lowest-risk way to get /redoc tomorrow, and the annotation investment lands in the same YAML either way. Option 3 pairs naturally with the SI2 Pages work (one publisher workflow assembling Jekyll + coverage + API docs). Option 2’s “spec matches the running binary” property becomes valuable once auth (SI5) and new endpoints (SI7) start changing the API faster; do it as part of SI5 rather than standalone.

Dependencies/effort: Option 1 ≈ a day (sidecar repo + ingress route + spec polish is the long pole — the annotation pass is the bulk of the work). No blockers.

NOTE: Option1 is good for now. Well the agent who hand-rolled the current spec off of source code inspection did a great job- its definitely the most well annoatetd/comprehensive generated swagger UI page that ive ever seen for an API. But what would you recommend ideally? Are there tools that can dynamically generate it from source code or live endpoints? The issue ahs been that the server is my manual impementaiont of REST using the crow HTTP server + json (gernated from the protobugs of OdnDesign lib’s data model) so im not aware of a tool that can gnerate off of such an adhoc one-off server codebase. And then if you go the interrgoiate liove endpointsm then you cant get the level opf detail that the agent generated. I mean ive used kiota before, but i dont know how well it could do with thticodebase?


SI2 — publish HTML coverage report(s) on the Pages site

Current state

Options

Option A — latest-only /coverage (prior Solution A/B). One publisher workflow assembles Jekyll site + the single latest coverage artifact at _site/coverage/.

Option B — per-branch /coverage/<branch>/ (recommended default: development + release). Keep code-coverage.yml as the producer (already uploads the artifact every run). Extend the Pages workflow (staying the only deploy-pages caller) to, before uploading: for each branch in the chosen set, download the latest linux-coverage-report artifact from that branch’s most recent successful coverage run (dawidd6/action-download-artifact with workflow: code-coverage.yml, branch: <b> — or gh api for exact control) into _site/coverage/<b>/, plus a small generated _site/coverage/index.html linking each branch report with its run date/SHA.

Option C — all four environment branches (development, staging, main, release). Same mechanism as B, bigger set.

Recommendation

Option B with {development, release} as the default set — freshest state and shipped state are the two reports anyone actually consults; adding branches later is a one-line change. While implementing, fix two adjacent bugs in the same workflow: the Doxygen copy step (# cp -r ./OdbDesignLib/doxygen/html ./_site/api) is commented out while docs/README.md still links to /api, and those README links point at nam20485.github.io/OdbDesign although the site’s canonical URL is source.odbdesignserver.com (docs/_config.yml). Either restore the Doxygen copy or fix the links — folding it in here is cheaper than a separate CI change.

Open decision (flagged): the branch set — dev+release (recommended) vs all four vs the literal “not main” reading (dev, staging, release). Mechanism is identical; only the array changes.

Dependencies/effort: 1–2 days of workflow work; no C++ changes. Requires actions: read (artifact download) alongside existing Pages permissions, and the retention bump.

Option B is good.


SI3 — do we need the main branch?

Current state

Flow per AGENTS.md: nam20485 → development → staging → main → release; production is a defunct legacy branch (absent from CI triggers, not part of the flow). main and release were re-baselined onto development on 2026-09-08, so today main ≈ development tip — the cheapest moment to remove a branch that will ever come. main is wired into: ruleset 169360 (required checks incl. Docker-Build-and-Publish, code-owner + last-push approvals), the trigger lists of cmake-multi-platform.yml, code-coverage.yml, docker-publish.yml, sbom-generate-submit.yml, dependency-review.yml, and docker-scout-scan.yml’s compare-to-main baseline.

Options

Option 1 — keep main as-is.

Option 2 — drop main (flow: development → staging → release).

Option 3 — rename main → production.

Recommendation

Option 1 — keep main, change nothing. The task’s own constraint (“don’t change unless risk is totally nontrivial”) plus the analysis above: the rename is impossible-without-cleanup, the drop is a coordinated multi-system change whose only payoff is one fewer gh pr merge. If branch count ever actually hurts, Option 2 is the correct variant now (post-re-baseline equivalence makes the diff trivially verifiable) — file it as a deliberate future cleanup, not an urgent one. production stays defunct and ignored, per AGENTS.md.

Dependencies/effort: none (decision only).

NOTE: OK fine option 1 keep main. it just bothers my sense of OCD. Which admittedly is not a good reason to reconfigure production application deployments.


SI4 — gRPC TLS

Current state

gRPC binds plaintext (InsecureServerCredentials(), OdbDesignServerApp.cpp) and is exposed as a plaintext TCP LoadBalancer Service on :50051 (deploy/kube/OdbDesignServer/service-grpc.yaml) — it does not pass through the HTTP ingress, so REST ingress TLS changes nothing for it. In the compose deployment, the nginx sidecar already proxies gRPC over TLS :443 (deploy/nginx/nginx.conf, h2 grpc_pass incl. reflection routes). The REST TLS decision is OPEN with a full option matrix in https-tls-options.md; its §8 already sketches gRPC options and the principle “decision for gRPC should follow the REST decision (same cert source)”.

Options (from https-tls-options.md §8, evaluated)

Option 1 — Traefik TCP termination (IngressRouteTCP :50051 with tls:). Replace the LoadBalancer Service with a Traefik TCP route presenting the same cert Secret the REST ingress uses (whatever wins the A–E REST decision feeds it).

Option 2 — TLS passthrough (app serves the cert). Traefik routes raw TCP; the gRPC server loads the cert/key from mounted secrets.

Option 3 — app-native TLS only (SslServerCredentials, plaintext never exposed).

Option 4 — status quo: plaintext on the trusted network, terminate at an edge for public exposure.

Recommendation

Option 1 — Traefik IngressRouteTCP termination sharing the REST cert Secret, decided and implemented together with the REST TLS decision (don’t pick a gRPC cert source now that might diverge from it). Keep the app plaintext-in-cluster; revisit passthrough/app-native TLS only if/when SI5b wants mTLS for machine clients. Note for implementation: grpcurl then drops -plaintext; reflection already routes through the proxy in the compose nginx config, which is the reference for the Traefik router shape.

Dependencies/effort: blocked on the REST TLS decision (https-tls-options.md open questions §10); ~1 day once decided.

Cert source decided 2026-09-10: Option C — cert-manager + self-managed CA with IP SANs (192.168.122.200, 100.118.225.119), per https-tls-options.md §5 Option C. The same Secret feeds the REST ingress and the gRPC IngressRouteTCP (milestone M3.1).

option 1 is good.


SI5a — unified authentication (more secure than Basic; currently nothing on gRPC)

Current state

Basic auth per-route on REST with hardcoded fallback credentials (odb/plusplus) when env vars are unset (BasicRequestAuthentication.cpp); auth is an explicit call inside every handler lambda (easy to miss on a new route); gRPC has none — any network-reachable client can read every design. CORS is * in all environments. These are the concrete defects any option must fix: single shared password, plaintext-equivalent basic credentials on every request, no identity (no way to say who), no coverage of gRPC, no revocation.

Options

Option 1 — self-hosted OIDC provider (Keycloak) on the k3s cluster; JWT bearer tokens everywhere. Keycloak realm holds users/clients; the server validates access tokens: a Crow auth middleware (crow::Crow<CORSHandler, AuthMiddleware> — replaces the per-handler AuthenticateRequest calls) checking Authorization: Bearer against Keycloak’s JWKS (e.g. jwt-cpp, available as a vcpkg port), and a gRPC sync interceptor doing the same for the authorization metadata key. /healthz* stays anonymous. --disable-authentication stays as the local/dev escape hatch.

Option 2 — server-issued tokens, no new infrastructure. The C++ server issues and validates its own signed JWTs (or long-lived API keys); an identity/ownership store (see SI5b) maps token → user.

Option 3 — managed external IdP (Auth0/Logto/…).

Option 4 — keep Basic, harden it (per-user credentials, constant-time compare, HTTPS-only).

Recommendation

Option 1 — Keycloak on k3s, JWT bearer validated in a Crow middleware + a gRPC interceptor. It is the only option that satisfies SI5a and SI5b (identity, per-resource decisions, device flow, machine clients) without hand-rolled security code, and it rides the existing GitOps deployment pattern. Sequence: (1) stopgap hardening now — remove the odb/plusplus fallback, fail closed when env creds are missing, move auth from per-handler calls to one middleware, tighten CORS to configured origins; (2) introduce Keycloak + bearer validation with a transition window where Basic still works; (3) remove Basic. Option 4’s stopgaps happen on day one regardless of the final choice.

Dependencies/effort: stopgaps ~1 day; Keycloak deployment + realm ~2–3 days; middleware/interceptor ~2–4 days. Interacts with SI4 (tokens over TLS) and SI1 (spec security schemes).

NOTE: Wow. Thats alot. I have given it some serious thought, and at this point I have only one question……………….

What is “yak-shaving?”

Option 1 is good.

SI5b — per-user, per-resource authorization + device flow (gRPC and REST)

Current state

No identity exists (see SI5a), hence no authorization: every authenticated caller can read every design, upload anywhere, and both channels are equivalent-or-nothing (“both communication channel type AND specific data resources” from the task is currently unsatisfiable). The resource set is small: designs (archives on disk / in DesignCache), uploads, and channel-level actions.

Options

Option 1 — ownership metadata + centralized enforcement (recommended). Each design gets an ownership record — start as a JSON sidecar next to the archive (<design>.tgz.owners.json) or a small index file; graduate to SQLite only if concurrent-write pain appears. Record: owner, shared: all | none, optional explicit user list. Enforcement lives in one place per channel: a check in RouteController/auth middleware for REST and a helper in OdbDesignServiceImpl for gRPC, keyed off the identity established by SI5a (sub claim). Roles from the IdP: admin (everything) vs user (own + shared). Uploads stamp the authenticated user as owner; a migration rule marks pre-existing designs owner=admin, shared=all so nothing breaks on rollout.

Option 2 — per-user directory namespaces (designs/<user>/…).

Option 3 — externalized authorization (OPA sidecar / SpiceDB).

Device flow (machine → server). With Keycloak (SI5a Option 1) this is configuration: enable the Device Authorization Grant on the realm, register a public client for CLIs/agents, and machines do the standard device_authorization_endpoint → user approves in browser → token poll dance. REST/gRPC clients just send the resulting bearer token like interactive clients. Without an IdP this is a from-scratch protocol implementation — the strongest single argument for Keycloak.

Recommendation

Option 1 + Keycloak device flow, sequenced strictly after SI5a. The ownership store is intentionally boring (JSON sidecar first), the enforcement points piggyback on SI5a’s middleware/interceptor so there is exactly one place per channel to get it right, and the migration rule (shared=all) keeps today’s behavior intact at rollout. REST and gRPC get identical decisions from the same claim set, satisfying the “both channel type and data resources” requirement by construction.

Dependencies/effort: ~3–5 days after SI5a lands (store + choke points + migration + tests). The upload path also gains its missing sanitizeFilename implementation while it’s being touched (FileUploadController.cpp TODO) — a pre-existing security gap in the same code.

Option 1 is good.


SI6 — server-side optimization options

Current state

Client-side fetch→load→display is already >10× faster; the remaining costs are server-side per request: (a) every REST response re-serializes protobuf → JSON (to_json()) even for unchanged designs — the dominant CPU cost on large designs; (b) first-touch parse blocks the calling request for minutes; (c) list endpoints rescan the designs directory per call; (d) DesignCache never evicts — memory grows monotonically; (e) gRPC matrix/bulk surface is thinner than REST’s. Gzip is already on for both channels; gRPC batch streaming already exists (feature-flagged).

Options (ranked)

1. Serialized-response cache. At design-load time (and on invalidation), pre-serialize the hot payloads — protobuf bytes for gRPC, JSON strings per endpoint for REST (/filemodels/<d>, /designs/<d>, …/matrix/matrix, …/layers/<l>/features, …) — and serve bytes from cache.

2. HTTP conditional requests: ETag + Cache-Control. ETag = cheap hash of (design file mtime, size, endpoint); honor If-None-Match → 304. Send Cache-Control: private, max-age=… for immutable design payloads.

3. Cache eviction (byte-budget LRU) + single-flight in-flight dedup. Cap DesignCache by estimated bytes; evict least-recently-served. Deduplicate concurrent misses on the same design (one parse, others wait) via a shared_future map — required once SI7 makes background loads possible.

4. Filesystem watcher (inotify) for the designs directory. Replace per-call directory rescans with a watch-driven cached listing; optionally detect replaced archives → invalidate caches proactively.

5. Pagination / field projection on heavy endpoints. ?offset=&limit= and/or sparse fieldsets on the large JSON endpoints.

6. gRPC surface parity (matrix, bulk fetch). Add e.g. GetMatrix, and batch variants of the heavy unary RPCs so gRPC clients get the same shapes REST clients have.

Recommendation

Do 1 + 2 first (measure before/after with a large design), fold 3 into SI7 (it’s a prerequisite there anyway), do 4 opportunistically, keep 5 and 6 demand-driven. The ordering follows cost/benefit: response caching + ETags attack the only costs that recur on every request; everything else is a first-touch or listing cost. When SI19.1.3 (arena allocation) and option 1 land together, the whole serialize-once story covers both channels.

Dependencies/effort: (1) ~3–5 days incl. invalidation tests; (2) ~1 day; (3) counted in SI7; (4) ~1–2 days with the PVC fallback; (5)/(6) sized on demand.

1 + 2 sounsd good.


SI7 — RequestLoadDesign(Async): kick a load, return immediately

Current state

DesignCache::GetDesign/GetFileArchive parse synchronously in the requesting call — a client’s first GetDesign for a big design blocks for the parse duration (minute-scale; the k8s probe comments budget for it). There is no RequestLoadDesign/GetDesignAsync RPC or REST equivalent today. The task: start the parse, return immediately; subsequent GetDesign for that design hits the warm cache and returns data immediately.

Options

Option 1 — background single-flight load + RequestLoadDesign RPC (+ REST twin + auto-warm on upload). Add to DesignCache an in-flight map (design name → std::shared_future) so exactly one parse runs per design regardless of how many callers request it. Expose:

GetDesign semantics unchanged: warm → immediate data; cold → still blocks (correct, just no longer the only path) or — later, if clients want it — returns a distinct “loading” error with retry guidance.

Option 2 — progress streaming too (LoadDesignProgress server-streaming RPC). Stream parse progress events to interested clients while the background load runs.

Option 3 — startup --load-all for known sets. Already exists (OdbAppBase), used by no deployment: unbounded memory, no selectivity. Not the mechanism, though worth documenting as the “small fixed set of designs” answer.

Recommendation

Option 1, with SI6.3 (eviction + single-flight) built as part of it and Option 2 deferred-but-not-precluded. This is the item where SI6 and SI7 genuinely merge: single-flight is the concurrency backbone for both, and pre-serialization after background load makes “request → instant data” true end-to-end. Ship RequestLoadDesign + POST /designs/<name>/load + upload auto-warm together; add progress via SI8’s channel when it exists.

Dependencies/effort: ~4–6 days including tests and the eviction coupling. Touches DesignCache, service.proto (+ codegen), OdbDesignServiceImpl, FileUploadController, and the swagger spec (SI1).

Option 1 is good.


SI8 — optional push channel (SSE? WebSockets?) with mandatory fallback

Current state

No SSE or WebSocket usage anywhere (verified: zero hits for websocket/event-stream in server sources). The only server-initiated streaming is gRPC server-streaming (GetLayerFeaturesStream/BatchStream) — proven in production. Framework fact that gates the options: the pinned Crow 1.3.3 has native WebSocket support but no chunked/SSE response API (verified in the vendored headers; upstream CrowCpp/Crow#1013 tracks chunked/SSE). The task’s requirement is that the channel be optional: the app must function unchanged if the connection is never attempted or fails mid-flight.

Options

Option 1 — WebSockets (Crow-native) as an events channel. A /events WS route (Crow websocket_handler) pushing small typed JSON events: design-load-started/finished/failed, design-list-changed (upload), optionally server-shutting-down. Clients feature-detect: try WS, and if it fails or drops, keep polling REST exactly as today — the fallback is the status quo, so “app still functions without it” holds by construction.

Option 2 — SSE.

Option 3 — gRPC server-streaming as the push channel. Extend the existing streaming machinery with e.g. a SubscribeDesignEvents stream; non-browser clients get events with zero new infrastructure.

Recommendation

Option 1 (WebSockets) for the browser-facing events channel + Option 3 already covers native/bulk clients; SSE is deferred until a Crow upgrade lands for other reasons. The fallback requirement decides the architecture more than the transport choice: whatever is built must be a pure optimization layer over the existing polling REST API, never a dependency — that invariant should be written into the client contract (and the SI1 spec) explicitly. SI7’s load events are the first payload this channel should carry, which sequences SI8 after (or with) SI7.

Dependencies/effort: ~3–5 days (route + event schema + reconnect semantics + proxy config for both deployment shapes).

Option 1 is good.


SI19 — remaining phase-2 gRPC optimization items

Current state (verified 2026-09-09)

phase2-grpc-optimizations.md specced three items behind PR #498 (feature/grpc, merged 2026-02-14). None of the three landed — PR #498 evidently carried only the phase-1 work:

Item Spec Status in code
2.1 — cc_enable_arenas = true in all .proto files 27 files Not done — 0/27 protos carry the option; stale //option optimize_for = CODE_SIZE; comments remain
1.3 — arena allocation in streaming RPCs (to_protobuf(TPbMessage*) overload, arena in GetLayerFeaturesStream/BatchStream) hot-path rework Not done — no arena usage or pointer-population overload in IProtoBuffable.h / OdbDesignServiceImpl
2.2 — compression level config replacing the boolean config surface Not done — GrpcServiceConfig.h still bool compression_enabled; config.json still compression: {enabled: true, algorithm: "gzip"}

The phase-2 doc is implementation-grade (per-file change lists, acceptance criteria, verified-against-headers API notes) — this section decides whether/when, not how.

Options

Option A — execute all three as specced (2.1 → 2.2 → 1.3).

Option B — cheap pair now (2.1 + 2.2), defer 1.3 until measured.

Option C — fold 1.3 into the SI6 optimization round. 1.3 and SI6.1 (serialized-response cache) are complementary, not overlapping: arenas cut per-message allocation in streaming RPCs; the response cache cuts re-serialization of unary/poll responses. Doing them together means one measurement campaign, one before/after benchmark on a large design, and one review of the serialization hot path.

Recommendation

B + C hybrid: land 2.1 and 2.2 now as standalone PRs (they’re finished specs sitting idle); sequence 1.3 as part of the SI6.1 work with a shared benchmark. One delta the phase-2 spec must absorb when 2.2 is implemented: config.json has since grown an algorithm: "gzip" field alongside enabled — the rewrite replaces two fields with level, and the migration note in the spec should say so.

Dependencies/effort: 2.1 ≈ 1–2 h; 2.2 ≈ 1–2 h (+ spec delta); 1.3 ≈ 4–8 h, scheduled with SI6.1. All are C++/proto changes → feature branch → nam20485 per the merge flow, protobuf regeneration wipes build dir (see workspace notes on major-bump gencode).

Sopunds good- take your recommendation


Cross-cutting sequencing

now, independent:   SI1 (redoc + annotations)     SI2 (pages coverage)     SI19.2.1/2.2 (cheap pair)
decision-gated:     SI4 (gRPC TLS)  ──after──►  REST TLS decision (https-tls-options.md, still OPEN)
identity track:     SI5a (Keycloak + middleware/interceptor) ──► SI5b (ownership + device flow)
perf track:         SI6.3+SI7 (single-flight, background load, eviction, auto-warm)
                       └─ with ─► SI6.1 (serialized-response cache) + SI19.1.3 (arenas) — one benchmark
events track:       SI8 (WS events channel) ──after/with──► SI7 (its first events are load lifecycle)

Two coupling rules worth stating explicitly:

  1. SI6.1, SI7, and SI19.1.3 all touch the same serialize/parse hot path. Plan them as one measurement campaign even if they ship as separate PRs; otherwise each change invalidates the others’ benchmarks.
  2. SI5a must precede SI5b and should precede any public exposure enabled by SI4 — TLS without authentication still leaves every design readable by anyone who can reach the port.

Open decisions

# Decision Status
1 SI2 branch set for published coverage: development+release (recommended) vs all four vs “not main” literal three Decided 2026-09-10 — Option B, {development, release}
2 SI5 IdP: Keycloak-on-k3s (recommended) vs server-issued tokens vs managed IdP Decided 2026-09-10 — Keycloak on k3s (Option 1)
3 REST TLS cert source A–E (feeds SI4’s shared cert Secret) Decided 2026-09-10 — Option C (cert-manager + private CA, IP SANs for the k3s VM); https-tls-options.md status header updated
4 SI3 branch topology: keep main (recommended) Decided 2026-09-10 — keep main, no changes
i believe all decisions have been resolved by my per-item remarks.