Add generated TUS protocol canary

[kvz]

Experimental Status

Experimental work: this PR is part of an exploratory contract/generated SDK effort, and is intentionally kept as a Draft while the approach is validated.

Why

This adds generated islands and checked-in devdock examples for the API2-owned TUS protocol client generator in tus-go-client. The goal is to prove that a non-TypeScript TUS client can consume the same raw protocol + feature-layer contract as tus-js-client without duplicating endpoint/header/status knowledge in the language generator.

What

• Add generated protocol_generated.go with the default Tus-Resumable wire version.
• Add generated protocol_contract_generated_test.go with TUS wire operations, response shapes, and client feature metadata.
• Use the generated default protocol version in NewClient without changing behavior.
• Add a real create+patch lifecycle test that drives Client.CreateUpload and UploadStream.Write from generated contract facts.
• Add devdock scenario helpers so examples read contract-owned metadata, headers, upload body headers, resume policy, optional URL-storage backend facts, TUS conformance input options, runtime setup, server capability facts, retry decisions, and request gates from scenario JSON.
• Add checked-in examples for custom request headers, request ID headers, upload body headers, deferred-length upload, file URL-storage backend proof, detailed-error proof, abort upload proof, override-PATCH proof, relative Location proof, parallel upload concat proof, retry-state proof, start-option validation proof, protocol-version selection proof, and node-path input-source proof.
• The file URL-storage proof reuses the existing resume example, captures the stored URL-key prefix before resume, captures final storage entry count after cleanup, and reports backend kind from scenario JSON.
• The abort proof runs both create-request abort and stored-upload PATCH abort scenarios. It reads serverCapabilities.extensionNames and serverCapabilities.protocolVersions from the contract scenario and only adapts those facts into tusgo.ServerCapabilities.
• The override-PATCH proof uses a reusable contract-driven local conformance server. It reads endpointUrl, uploadUrl, overridePatchMethod, fingerprint, content, and server capabilities from scenario JSON, then proves HEAD offset recovery followed by POST with X-HTTP-Method-Override: PATCH.
• The relative Location proof uses generated URL normalization sourced from the contract policy relative-to-creation-request-url, so stored URLs, hooks, and subsequent upload requests all use the resolved absolute upload URL.
• The parallel upload concat proof uses the reusable contract-driven local conformance server with parallel request gates, canonicalizes partial URLs inside the final Upload-Concat header, checks request body starts and absent final Upload-Length, and proves public UploadWithURLStorage with ParallelUploads.
• The retry-state proof drives the existing retry callbacks through a contract-declared status sequence and captures retry decisions from the public hook surface.
• The start-option validation proof maps contract-owned input option entries into public SDK options and verifies ParallelUploads plus UploadDataDuringCreation fails before any HTTP request.
• The protocol-version proof uses generated protocol compatibility helpers so Client.ProtocolVersion selects request headers, upload body content type, and upload-complete headers, then proves draft-05 creation-with-upload sends Upload-Draft-Interop-Version, Upload-Complete, and application/partial-upload while omitting Tus-Resumable.
• The node-path input-source proof maps contract inputSource.content into a temporary file, passes an opened file through public UploadWithURLStorage, and captures the contract-declared source-open/success/source-close events plus POST/PATCH request facts.
• The detailed-error proof uses generated DetailedError runtime support and a generated recorder transport to prove both response-status and request-error create-upload failures through public UploadWithURLStorage.
• Go/TUS now has twenty-three live checked examples and no remaining generated protocol feature gaps in the contract QA matrix.
• The reusable conformance server now matches observed requests by method, URL, headers, absent headers, and body facts instead of raw arrival order, so parallel scenarios remain deterministic without hiding protocol knowledge in the test server.

Verification

• go test ./...
• go test -tags api2devdock ./examples/...
• git diff --check
• Local generated scenario smoke for tusAbortUpload
• Local generated scenario smoke for tusAbortUploadAfterStoredUrl
• Local generated scenario smoke for tusOverridePatchMethod
• Local generated scenario smoke for tusRelativeLocationResolution
• Local generated scenario smoke for tusParallelUploadConcat
• Local generated scenario smoke for tusRetryStateTransitions
• Local generated scenario smoke for tusStartOptionValidationParallelUploadsWithUploadDataDuringCreation
• Local generated scenario smoke for tusProtocolVersionSelectionDraft05CreationWithUpload
• Local generated scenario smoke for tusNodePathInputSource
• Local generated scenario smoke for tusDetailedCreateResponseError
• Local generated scenario smoke for tusDetailedCreateRequestError
• From API2: api2/bin/cli.ts contracts sdks --no-motd --target tus --platform go --sdk-root ../tus-go-client --compare-existing
• From API2: api2/bin/cli.ts contracts sdks qa --no-motd --target tus --platform go --dry-run
• API2 live wrapper: core/bin/devdock.ts exec tstrun system/sdk_examples/go-tus-transloadit-assembly-upload.test.ts -vv --max-time-per-test 900

Companion PRs (tus org only)

• tus-js-client: Mark protocol versions as generated tus-js-client#872
• tus-py-client: Add generated TUS protocol canary tus-py-client#114
• tus-java-client: Add generated TUS protocol contract canary tus-java-client#149
• tus-android-client: Add generated TUS protocol contract canary tus-android-client#167

[codecov-commenter]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

Thanks for integrating Codecov - We've got you covered ☂️