# 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