spike: codegen experiments (SDK-1107)

[Tr00d]

Status: 🚧 DRAFT — spike, not for merge

This is an evaluation spike. All generated code lives in isolated, standalone projects that are
in the solution for visibility but are not referenced by Supabase.csproj (analyzers disabled,
separate assemblies) — nothing here affects the product build, analyzers, or quality metrics.

Summary

Evaluates whether the HTTP layer of the C# SDK (Storage / Functions / PostgREST; Auth is blocked by
model coverage) can be generated from the shared Smithy models in supabase/sdk#51, producing
idiomatic C# that a maintainer would own long-term. Input is the committed Smithy→OpenAPI
artifacts; Smithy is never run in the C# toolchain. All evaluated generators are deterministic,
template-based tools — output is a function of the input document and configuration only, with no
generative-AI component.

Two toolchains were run end-to-end (NSwag and Kiota), the rest of the brief's list assessed
with rationale, and both generated clients were exercised against a live local Supabase platform.

What's included

Project (in Supabase.sln)	What
nswag-spike/ (spike-nswag)	NSwag-generated Storage/Functions/Database clients + models; evaluation + findings
kiota-spike/ (spike-kiota)	Kiota-generated clients + models; evaluation
nswag-testrun/ (spike-nswag.TestRun)	Console harness driving the NSwag client against a local platform
kiota-testrun/ (spike-kiota.TestRun)	Same, for Kiota
codegen-comparison.md (root)	Cross-toolchain comparison, cost analysis, and recommendation — start here

Key findings

• Judged against the current SDK (owned working transport, published public model types),
  neither generated client improves on the shipped code: NSwag's client re-implements the existing
  MakeRequest transport; Kiota's replaces it with 4,338 generated LOC plus an 8-package runtime,
  without the current ergonomics (progress reporting, caching, FailureHint mapping). Generated
  models do add value — as drift protection against the shared contract and as the type source
  for new endpoints.
• Separability decides the tool. NSwag's models are plain POCOs (System.Text.Json only) usable
  without its client; Kiota's models implement IParsable, require its runtime, and place
  Microsoft.Kiota.Abstractions on the SDK's public API — there is no models-only adoption path
  for Kiota.
• The live runs surfaced two defects, both located in the shared model (a work in progress), not
  in the generators: the list-response envelope (model wraps arrays the API returns bare — Kiota
  returns empty results silently, NSwag throws) and missing nullable on optional fields (NSwag
  serializes defaults the server rejects; Kiota omits unset fields). Both generators translated
  their input faithfully and deterministically — which means a model fix propagates identically to
  every SDK on regeneration. Validation must target the model; the test-run harnesses are the
  mechanism.
• Confirmed working live for both tools: HttpClient injection and streaming upload
  (FileStream → StreamContent, no buffering). Live runs covered Storage; Functions and Database
  clients were generated and compiled but not exercised.

Recommendation — adapt, with NSwag in models-only mode, in two stages

• Stage 1 (now, no change to existing public API): generate wire DTOs with NSwag (with three
  fixes: WhenWritingNull + nullable value types, source-generated JsonSerializerContext for
  AOT, PascalCase naming); use generated models as the type source for newly implemented endpoints;
  stand up a drift monitor — generated models diffed against the existing public types, with a
  committed baseline, reported and triaged (divergence on implemented surface = defect/contract
  change; unimplemented surface = parity-backlog input), not a build gate; adopt
  HttpCompletionOption.ResponseHeadersRead in Core; raise the model gaps upstream.
• Stage 2 (next major version): decide whether generated types replace the existing public
  model types, bundled with the breaking changes already planned for the feature-parity catch-up,
  conditional on the contract source having proven reliable through Stage-1 monitoring.

Scope of validity: these conclusions are specific to an SDK with owned transport, a published
public API, and a parity backlog. For an SDK built from scratch, the same evaluation favours
whole-client generation (Kiota is the strongest candidate assessed). Invariant in both settings:
generated code is only as correct as the contract it is generated from, and a live contract-test
harness is a required pipeline stage. Full rationale, cost analysis, and reversal criteria in
codegen-comparison.md.

Upstream model gaps to raise on supabase/sdk

1. List-response envelope — model wraps arrays the API returns bare (silent/loud failures,
   affects every SDK).
2. Optional fields not marked nullable — leads generators to serialize defaults the server
   rejects.
3. Streaming byte→binary; required multipart parts; {wildcardPath+} label; Auth unmodelled.

How to run the harnesses

supabase start && supabase status     # copy the API URL + service_role key
cd kiota-testrun   # or nswag-testrun
SUPABASE_URL=http://127.0.0.1:54321 SUPABASE_KEY=<service_role key> dotnet run

🤖 Generated with Claude Code (https://claude.com/claude-code)