Repository navigation
feat(generator): build full SDK generation foundation - #11
Draft
nmorgan-cb wants to merge 8 commits into
Draft
nmorgan-cb wants to merge 8 commits into
nmorgan-cb wants to merge 8 commits into
Conversation
Parse the committed spec into a stable, operation-ID sorted inventory and derive one Java binding per operation (service folder, service name, method, request/pagination shape). Config-driven overrides keep the vended SDK names and types; the validator rejects missing path parameters, duplicate methods, and one service name bound to two folders. - SpecParser fails on operations without an operationId. - SpecFetcher replaces the committed spec only after a 2xx response that parses with operations. - JavaTypeResolver maps schemas to vended model/enum types, keeps DTO booleans boxed, and rejects ambiguous inline enums. - operation-inventory.json locks the vended service and method of all 111 current operations; new spec operations are allowed.
Post-process raw OpenAPI models so *ErrorCode/*Subcode enums land in com.coinbase.prime.model.errors and every other enum keeps its vended package. Model output is tracked in a manifest, so stale files are removed only when the previous generation owned them, and enum directory read errors fail generation instead of emitting partial imports.
Emit the client surface from operation bindings: request DTOs with builders, validation, and PrimeListRequest pagination; response DTOs; service interfaces and implementations with /v1 and /v2 routing; and PrimeServiceFactory. Main renders and validates the whole surface before writing any file, and adds isolated --check and --live-diff modes that never mutate the checkout (make check-generated, make generate-live-diff). CoinbasePrimeClient exposes its base URL and keeps an injected HttpClient in withBaseUrl, which generated /v2 calls use.
Converge Java method and type names on the canonical names shared with the .NET, TypeScript, Python, and Go Prime SDKs. Each rename is declared in operations-overrides.json with deprecatedAliases; the generator emits a @deprecated request subclass with a covariant Builder, a @deprecated response subclass, and @deprecated forwarding service methods, so existing callers keep compiling. naming-parity.json and NamingParityTest lock the cross-SDK mapping, and the operation inventory records the 11 renames with their aliases.
Run the model-generator test suite in CI, and add a generated-sdk job that regenerates from the committed spec in the disposable checkout, compiles, and runs the SDK tests. make check-generated replaces this job once a generated baseline is committed.
🟡 Heimdall Review Status
|
3 of 9 tasks
Regenerating from the unchanged committed spec used to rewrite 261 existing SDK files. Make the templates reproduce the vended conventions so only real spec updates and the intended alias renames produce a diff: - License header, @JsonProperty form, required only on path parameters, build() throws CoinbaseClientException, validate() visibility (protected only for classes with deprecated aliases), and the parameterless request shape now match the vended sources. - Builders expose limit() and pagination(); cursor()/sortDirection() only where the vended class already has them. - SourceLayout reads an existing class and keeps its field order, field and class documentation, and service method order/Javadoc. New members append in spec order with spec documentation. A canonical class that renames a vended one inherits the legacy class's layout. - responseTypeOverrides keep the vended List<T> (not T[]) for the cross margin risk parameters and market data responses; configured types may now be generic. - ErrorCode/Subcode enums are opt-in (generateErrorEnums, default false), matching the vended SDK and the previous behavior of main. - --check --expect-changes=<file> fails on any change not in an allowlist.
Adds tools/model-generator/config/expected-generation-changes.txt, the exact set of vended files that generating from the committed spec may add or change: the 11 canonical/alias renames, the real spec updates to CreateQuote and EditOrder, the /v2 base URL change, and the hand-maintained portfolio files. `make check-surface` fails on any other change and on any entry that stops applying, and runs in the generated-sdk CI job. The list shrinks to empty once a generated baseline is committed.
…early Comparing regenerated services method by method with the vended ones found seven operations whose accepted success codes changed: createStake, createUnstake, portfolioStakingInitiate, portfolioStakingUnstake and claimRewards expect 201 then 200, while createWalletTransfer and createWalletWithdrawal expect only 200. The Create/Claim heuristic did not match them. - Pin the vended codes with statusCodes overrides, and keep the configured order instead of sorting it (201 must stay before 200). - operation-inventory.json now also locks the accepted status codes of all 111 operations, taken from the vended implementations. - SourceLayout reads classes, fields and service methods with linear scans instead of backtracking regular expressions (CodeQL flagged the class Javadoc pattern as potentially exponential).
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Adds a deterministic, OpenAPI-driven generator for the full Prime Java client surface (models, requests, responses, services,
PrimeServiceFactory), and converges Java method/type names on the canonical names shared with the .NET, TypeScript, Python, and Go Prime SDKs — generating a@Deprecatedcompatibility alias for every existing public Java name that changes.This PR adds the generator, its config, and tests. It does not include regenerated SDK source; see Generation preview below.
Review guide
Each commit is a self-contained step that builds and passes its tests:
feat(generator): parse the OpenAPI spec into SDK operation bindings: spec parsing and fetching, config and overrides, binding derivation and validation, type resolution, and the operation inventory lock.feat(generator): route error enums and own generated model files: model post-processing, error-enum routing, and the manifest that tracks generated model files.feat(generator): generate requests, responses, services, and factory: the emission phases, theMainCLI (--check/--live-diff), the Makefile, andCoinbasePrimeClient/v2support.feat(generator): generate deprecated Java aliases for canonical names: the alias config, alias emission, and the naming parity fixture.ci: gate generator tests and generated SDK compilation: runs the generator tests in CI, and adds agenerated-sdkjob that regenerates the SDK from the committed spec, compiles it, and runs the SDK tests.feat(generator): match vended conventions and preserve existing layout: templates reproduce the vended conventions,SourceLayoutkeeps the field order, documentation and method order of existing classes,List<T>response overrides, and opt-in error enums.ci: gate generation drift with an expected-changes allowlist:make check-surfaceandexpected-generation-changes.txt.Generator
apiSpec/prime-public-spec.yaml) drives normal generation and CI; live fetch/diff is explicit and non-mutating./v1//v2routing,PrimeXM*naming, and existing model transforms.*ErrorCode/*Subcodeenums intocom.coinbase.prime.model.errors(generateErrorEnums, off by default like the vended SDK).config/expected-generation-changes.txt(the 11 alias renames, the realCreateQuote/EditOrderspec updates, the/v2base URL change). Everything else regenerates byte-for-byte;make check-surfaceenforces it in CI.make fetch-spec,make generate,make check-generated,make generate-live-diff— check/live-diff render only in isolated temp dirs, never mutate the checkout.Boolean), and primitive fields such asCreateOrderRequest.isRaiseExact/isBuyExactare kept via overrides.operation-inventory.jsonlocks the service and method of all 111 current operations. New spec operations generate automatically, while renames or removals failOperationInventoryTest.fetch-specnever overwrites the committed spec. MissingoperationIds, ambiguous inline enums, and duplicate service names are rejected.CoinbasePrimeClient.withBaseUrlnow keeps an injectedHttpClient(used by generated/v2calls).Canonical naming + generated deprecated aliases
Every alias is declared in
operations-overrides.json, never hand-written:{ "operationId": "PrimeRESTAPI_CreateWalletTransfer", "sdkMethod": "CreateTransfer", "deprecatedAliases": [{ "sdkMethod": "CreateWalletTransfer", "message": "Use createTransfer instead." }] }For each entry, the generator emits a
@Deprecatedrequest subclass (with a covariantBuildersubclass, sonew LegacyRequest.Builder()...build()still compiles and returns the legacy type), a@Deprecatedresponse subclass, and@Deprecatedforwarding methods on the service interface and implementation.createTransfercreateWalletTransfercreateWithdrawalcreateWalletWithdrawalgetOrdergetOrderByOrderIdclaimStakingRewardsclaimRewardscreatePortfolioStakeportfolioStakingInitiatecreatePortfolioUnstakeportfolioStakingUnstakelistEntityPaymentMethodslistPaymentMethodsgetEntityPaymentMethodgetPaymentMethodDetailslistActivitieslistPortfolioActivitiesgetAddressBooklistAddressBookgetAllocationsByClientNettingIdlistAllocationsByNettingIdlistEntityUsers,getEntityFcmBalance, andgetPortfolioCounterpartyIdstay canonical as-is.config/naming-parity.jsonplusNamingParityTestlock this mapping in-repo, without cloning other SDK repositories in CI.Tests
DeprecatedAliasGenerationTest,NamingParityTest,OperationInventoryTest, andSpecFetcherTest.CoinbasePrimeClientTest.Generation preview
Ran
make generatein an isolatedgit worktree, then compiled and tested the generated SDK (287 tests passing), including existing example programs, which compile with deprecation warnings on legacy calls.make check-generatedreports new canonical types as additions and legacy names as converted alias files. The preview caught a real bug: aliasBuilder.build()initially skipped the canonical (private)validate(); it's nowprotectedand called viasuper.validate().The generated SDK baseline itself (models, DTOs, services, factory, error enums, manifest) will be committed in a follow-up, after a public API diff review, then
make check-generatedbecomes a required CI gate.Type of Change
Checklist