up

src/Sdk/StellaOps.Sdk.Generator/go/README.md

@@ -0,0 +1,35 @@
+# Go SDK (SDKGEN-63-003)
+
+Deterministic generator settings for the Go SDK with context-first API design.
+
+## Prereqs
+- `STELLA_OAS_FILE` pointing to the frozen OpenAPI spec.
+- OpenAPI Generator CLI 7.4.0 jar at `tools/openapi-generator-cli-7.4.0.jar` (override with `STELLA_OPENAPI_GENERATOR_JAR`).
+- JDK 21 available on PATH (vendored at `../tools/jdk-21.0.1+12`; set `JAVA_HOME` if needed).
+
+## Generate
+```bash
+cd src/Sdk/StellaOps.Sdk.Generator
+STELLA_OAS_FILE=ts/fixtures/ping.yaml \
+STELLA_SDK_OUT=$(mktemp -d) \
+go/generate-go.sh
+```
+
+Outputs land in `out/go/` and are post-processed to normalize whitespace, inject the banner, and copy shared helpers (`hooks.go`).
+Override `STELLA_SDK_OUT` to keep the repo clean during local runs.
+
+## Design Principles
+
+- **Context-first**: All API methods accept `context.Context` as the first parameter for cancellation and deadline propagation.
+- **Interfaces**: Generated interfaces allow easy mocking in tests.
+- **RoundTripper hooks**: Auth, retry, and telemetry are implemented as composable `http.RoundTripper` wrappers via `hooks.go`.
+- **Deterministic**: Generation is reproducible given the same spec and toolchain lock.
+
+## Helpers
+
+The post-process step copies `hooks.go` into the output directory providing:
+- `AuthRoundTripper`: Injects Authorization header from token provider
+- `RetryRoundTripper`: Retries transient errors with exponential backoff
+- `TelemetryRoundTripper`: Adds client/trace headers
+- `WithClientHooks`: Composes round-trippers onto an `*http.Client`
+- `Paginate[T]`: Generic cursor-based pagination helper