Skip to content

Add apx client verify generate-and-compile gate - #42

Merged
daniel-garcia merged 1 commit into
mainfrom
client-verify-gate
Jul 18, 2026
Merged

daniel-garcia merged 1 commit into
mainfrom
client-verify-gate

Conversation

@daniel-garcia

Copy link
Copy Markdown
Contributor

Closes #40.

Problem

A spec can be valid OpenAPI 3 and pass apx lint + apx breaking, yet produce a client that does not compile. The release pipeline never generated or compiled a client, so a broken module could be tagged and published. Two constructs trigger it (both valid OAS3):

  • redundant _limit/limit (+ _offset/offset) query params — oapi-codegen strips the leading underscore, so each pair collapses to the same Go field (Limit/Offset redeclared);
  • a path parameter named url — the emitted url argument shadows the net/url import (url.Parse undefined).

Fix

Add apx client verify: generate a client and compile it, failing when any generated client does not build. This is the missing release gate.

  • --warn-only (and release.verify_clients.warn_only) downgrades a failure to a warning (exit 0) for staged rollout; the default is to fail the gate.
  • release.verify_clients.generators sets the matrix; default is go + typescript-angular.
  • A generator whose toolchain is absent is skipped (not failed), so the gate covers Go always and TypeScript where Node is present.
  • The Builder-or-npm build dispatch is centralized in internal/client and shared by generate --build, publish, and verify.

Tests

  • Unit tests for client.Verify (pass / build-fail / generate-fail / skip / unknown generator / default matrix), using stub generators — no network.
  • A regression fixture (testdata/goclient/collision.openapi.yaml) reproducing both patterns, plus network-gated E2E tests asserting the gate rejects it and accepts the good fixture.
  • Docs (configuration.md, release-guardrails.md), CHANGELOG.md, and apx.example.yaml updated; schema/doc parity test passes.

Verified end-to-end on the fixture:

$ apx client verify --generator go --input testdata/goclient/collision.openapi.yaml
  go: FAILED — build: go build failed: exit status 1
  ./apxverifyclient.gen.go:21:2: Limit redeclared
  ./apxverifyclient.gen.go:23:2: Offset redeclared
  ./apxverifyclient.gen.go:238:24: url.Parse undefined (type string has no field or method Parse)
client verification failed: one or more generated clients did not build   # exit 1

$ apx client verify --generator go --warn-only --input testdata/goclient/collision.openapi.yaml
Client verification failed, but --warn-only is set — not failing the gate.  # exit 0

A spec can be valid OpenAPI 3 and pass lint/breaking yet produce a client
that does not compile (e.g. redundant _limit/limit query params collapsing
to one Go field, or a path param named url shadowing net/url). Add
'apx client verify', which generates a client and compiles it, failing when
any generated client does not build.

--warn-only (or release.verify_clients.warn_only) downgrades a failure to a
warning for staged rollout; a generator whose toolchain is absent is skipped,
so the gate covers Go always and TypeScript where Node is present.

Centralize the Builder-or-npm build dispatch in internal/client, shared by
generate --build, publish, and verify. Add a regression fixture reproducing
both patterns plus network-gated E2E tests.

Fixes #40
@daniel-garcia
daniel-garcia merged commit 1d1b724 into main Jul 18, 2026
10 checks passed
@daniel-garcia
daniel-garcia deleted the client-verify-gate branch July 18, 2026 16:26
daniel-garcia added a commit to infobloxopen/apx-action that referenced this pull request Jul 18, 2026
For each converted OpenAPI v3 module, generate a client and compile it, so a
spec that passes lint/breaking but produces a non-building SDK is caught before
publish (e.g. a path param named url shadowing net/url, or redundant
limit/offset params colliding with _limit/_offset on one Go field).

Adds a 'verify-clients' input: fail (default) | warn | off. 'fail' stops the
run — in check and publish — before any publish PR is opened; 'warn' reports;
'off' skips. Generators default to go; override per repo via
verify_clients.generators in .apx-publish.yaml.

Because the default is fail, the apx-toolchain image must provide
'apx client verify' (infobloxopen/apx#42); a stale image without it will fail
publishes, by design.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Release pipeline has no generate-and-compile gate — publishes OpenAPI modules whose generated Go client does not build

1 participant