stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 3 Releases Wiki Activity
Files
e950474a770337781dba83b1422a884198c4cfa0
git.stella-ops.org/src/Sdk/StellaOps.Sdk.Generator/go/README.md
master e950474a77
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
Details
AOC Guard CI / aoc-guard (push) Has been cancelled
Details
AOC Guard CI / aoc-verify (push) Has been cancelled
Details
api-governance / spectral-lint (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
up
2025-11-27 15:16:31 +02:00

1.5 KiB
Raw Blame History

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

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