Skip to content

Commit 88c75c6

Browse files
committed
refactor(sdk): name the v0 modules for the surface they serve
Every SDK ended 0.6.0 with the v1 code in `*_v1` files and the v0 code still in the unsuffixed ones it had before there was anything to distinguish it from. So "unsuffixed file" meant v0 while "unsuffixed class" meant v1, and a reader opening `dstack_client.rs` landed on the legacy surface. The v0 modules now say so: `dstack_client.rs` -> `dstack_client_v0.rs` and types `dstack.rs` -> `dstack_v0.rs` in Rust, `dstack_client.py` -> `dstack_client_v0.py` in Python, `client.go` -> `client_v0.go` in Go. The JS SDK had both clients and their shared helpers in one `index.ts`; it is split into `client-v0.ts`, `client-v1.ts` and `shared.ts`, with `index.ts` kept as a barrel exporting exactly what it exported before. No compatibility aliases for the old module paths. 0.6.0 is already the release where the unsuffixed client name changed meaning, and the whole point of that decision was that an unmigrated caller fails at build time rather than silently binding the frozen surface; a module alias would reopen the hole the rename closes. Deprecation is now visible to each language's tooling rather than only to a reader. Go and JS already carried `// Deprecated:` and `@deprecated`; Rust had no attribute at all and Python only a docstring note. `DstackClientV0` and `TappdClient` now carry `#[deprecated]`, with `#[allow(deprecated)]` at the internal use sites so the attribute reaches downstream callers instead of being blanket-suppressed, and the Python v0 clients warn at construction through the helper the file already had for `TappdClient`. Two tests pin that warning, which nothing did before. `.claude/agents/sdk-sync-checker.md` listed the old paths and now lists both surfaces' files, since a rename that leaves the agent looking at the wrong file makes it quietly useless.
1 parent c3b5f96 commit 88c75c6

34 files changed

Lines changed: 1111 additions & 972 deletions

.claude/agents/sdk-sync-checker.md

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -67,10 +67,10 @@ Details:
6767

6868
## Locations
6969
- Protos: `dstack/guest-agent/rpc/proto/*.proto`
70-
- Python: `sdk/python/src/dstack_sdk/dstack_client.py`
71-
- Go: `sdk/go/dstack/client.go`
72-
- Rust: `sdk/rust/types/src/dstack.rs`
73-
- JS: `sdk/js/src/index.ts`
70+
- Python: `sdk/python/src/dstack_sdk/dstack_client_v0.py`, `dstack_client_v1.py`
71+
- Go: `sdk/go/dstack/client_v0.go`, `client_v1.go`
72+
- Rust: `sdk/rust/types/src/dstack_v0.rs`, `dstack_v1.rs`
73+
- JS: `sdk/js/src/client-v0.ts`, `client-v1.ts`
7474
- Docs: `sdk/curl/api.md`, `sdk/curl/api-tappd.md`
7575

7676
Focus on API surface differences. Provide specific file paths and line numbers.

CHANGELOG.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -61,6 +61,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
6161
- sdk: the Go SDK's v1 `IssueCert` defaults `usage_server_auth` to true, as the Rust, Python and JavaScript v1 clients already did. Go was the odd one out, so the same argument-free call produced a certificate that could serve TLS in three languages and one that could not in the fourth — and a certificate you cannot serve with is useless to most callers. `WithCertUsageServerAuth(false)` opts out. v0's `GetTlsKey` keeps its `false` default deliberately: that is what the released 0.5.x Go SDK sent, and `DstackClientV0` mirrors released behaviour rather than the better choice
6262
- sdk: the JavaScript v1 `issueCert` response no longer carries a raw-bytes accessor. `asUint8Array()` is **removed rather than renamed**: it existed to feed the private key into the blockchain adapters, and v1 has no chain-flavoured surface. `IssueCert` returns TLS material, PEM is the form a TLS stack takes, and a caller who genuinely needs DER converts it with a standard library. The Rust, Python and Go v1 clients already returned the PEM string and the chain alone, so all four now agree. v0's `GetTlsKeyResponse.asUint8Array` is untouched — released API, and the viem and solana adapters depend on its truncating behaviour
6363
- sdk: the JavaScript v1 GPU evidence bundle's `asUint8Array()` is renamed `decodeEvidence()`, matching Python's and Rust's `decode_evidence` and Go, which hands back the decoded `Evidence` bytes directly. The name now says what the bytes are — the vendor's evidence, hex off the wire and decoded byte-exact, because sha256 over precisely those bytes is what the measured `gpu-attestation` event commits to
64+
- sdk: the v0 modules carry a `_v0` suffix, so the file a reader opens matches the client it holds. Rust's `dstack_sdk::dstack_client` becomes `dstack_sdk::dstack_client_v0` and `dstack_sdk_types::dstack` becomes `dstack_sdk_types::dstack_v0`; Python's `dstack_sdk.dstack_client` becomes `dstack_sdk.dstack_client_v0`; Go's `client.go`/`client_test.go` become `client_v0.go`/`client_v0_test.go`; and the JavaScript `index.ts`, which held both surfaces in one file, splits into `client-v0.ts`, `client-v1.ts` and a `shared.ts`, leaving `index.ts` as a barrel that re-exports exactly the names it always did. Until now the unsuffixed *file* meant v0 while the unsuffixed *class* meant v1, so a reader opening `dstack_client.rs` for the recommended client found the legacy one instead. **There are deliberately no backward-compat module aliases**: 0.6.0 is the loud-break release, and an import of an old module path fails at build time rather than silently binding the frozen surface under a name that now means something else. Package-level exports are untouched in every SDK — `dstack_sdk::DstackClient`, `from dstack_sdk import DstackClientV0` and `@phala/dstack-sdk`'s public surface are exactly what they were; only a deep import of the module path moves. In Go this is file naming alone, since it is all one `package dstack`
65+
- sdk: the v0 clients are deprecated in the way each language's tooling understands, not only in prose. Rust's `DstackClientV0` and `TappdClient` carry `#[deprecated(since = "0.6.0")]`, so a downstream build warns at the `use` and at every call; Python's `DstackClientV0` and `AsyncDstackClientV0` emit a `DeprecationWarning` on construction, through the same helper `TappdClient` already used, alongside the `.. deprecated:: 0.6.0` docstring note they already carried. Go's `// Deprecated:` markers and JavaScript's `@deprecated` JSDoc were already in place; a few Go ones sat mid-comment rather than as their own trailing paragraph, which is the only form the tooling recognises, and are repaired. Nothing is removed and no behaviour changes — the frozen surface stays reachable under its explicit name, it just says what it is at build time now
6466

6567

6668
### Removed
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -575,12 +575,14 @@ func (c *DstackClientV0) EmitEvent(ctx context.Context, event string, payload []
575575
// Legacy methods for backward compatibility with warnings
576576

577577
// DeriveKey is deprecated. Use GetKey instead.
578+
//
578579
// Deprecated: Use GetKey instead.
579580
func (c *DstackClientV0) DeriveKey(path string, subject string, altNames []string) (*GetTlsKeyResponse, error) {
580581
return nil, fmt.Errorf("deriveKey is deprecated, please use GetKey instead")
581582
}
582583

583584
// TdxQuote is deprecated. Use GetQuote instead.
585+
//
584586
// Deprecated: Use GetQuote instead.
585587
func (c *DstackClientV0) TdxQuote(ctx context.Context, reportData []byte, hashAlgorithm string) (*GetQuoteResponse, error) {
586588
c.logger.Warn("tdxQuote is deprecated, please use GetQuote instead")
@@ -601,6 +603,7 @@ type TappdClient struct {
601603
}
602604

603605
// NewTappdClient creates a new deprecated TappdClient.
606+
//
604607
// Deprecated: Use NewDstackClient instead.
605608
func NewTappdClient(opts ...DstackClientOption) *TappdClient {
606609
// Create a modified option to use TAPPD_SIMULATOR_ENDPOINT
@@ -632,6 +635,7 @@ func NewTappdClient(opts ...DstackClientOption) *TappdClient {
632635
// Override deprecated methods to use proper tappd RPC paths
633636

634637
// DeriveKey is deprecated. Use GetKey instead.
638+
//
635639
// Deprecated: Use GetKey instead.
636640
func (tc *TappdClient) DeriveKey(ctx context.Context, path string, subject string, altNames []string) (*GetTlsKeyResponse, error) {
637641
tc.logger.Warn("deriveKey is deprecated, please use GetKey instead")
@@ -661,6 +665,7 @@ func (tc *TappdClient) DeriveKey(ctx context.Context, path string, subject strin
661665
}
662666

663667
// TdxQuote is deprecated. Use GetQuote instead.
668+
//
664669
// Deprecated: Use GetQuote instead.
665670
func (tc *TappdClient) TdxQuote(ctx context.Context, reportData []byte, hashAlgorithm string) (*GetQuoteResponse, error) {
666671
tc.logger.Warn("tdxQuote is deprecated, please use GetQuote instead")

0 commit comments

Comments
 (0)