Client configuration

All three SDKs expose S3, native JSON, and admin clients, but the listeners and credentials are deliberately separate. Use the public object endpoint for S3 and native clients; use the private admin endpoint only for admin clients.

Endpoint and path prefixesCopy Anchor Link

An endpoint may include a clean reverse-proxy prefix, such as https://objects.example.com/lockwell. The SDK preserves that prefix in normal requests, SigV4 canonical paths, and presigned URLs. Do not append /api/v1 or /admin/api/v1 yourself unless the proxy exposes that exact mounted URL; duplicate suffixes are normalized once. User information, query strings, fragments, traversal segments, encoded separators, and malformed escapes are rejected.

Path-style S3 addressing is the default. Enable virtual-hosted style only when wildcard bucket DNS and certificates are configured. Dotted bucket names remain part of the signed host.

The S3 signing region defaults to us-east-1; it must match the server-configured region. Native and admin bearer-token requests do not use a signing region.

TLS and a private CACopy Anchor Link

Production endpoints should use TLS. A private CA belongs in the injected transport, not in an SDK-wide “skip verify” flag. Never disable certificate verification.

roots, err := x509.SystemCertPool()
if err != nil { log.Fatal(err) }
pem, err := os.ReadFile("/run/secrets/lockwell-ca.pem")
if err != nil || !roots.AppendCertsFromPEM(pem) { log.Fatal("invalid Lockwell CA") }

httpClient := &http.Client{Transport: &http.Transport{TLSClientConfig: &tls.Config{
    MinVersion: tls.VersionTLS12,
    RootCAs: roots,
}}}
s3, err := lockwellsdk.New(endpoint, creds,
    lockwellsdk.WithHTTPClient(httpClient),
    lockwellsdk.WithRequestTimeout(30*time.Second))

The JVM-wide alternative is -Djavax.net.ssl.trustStore=/path/lockwell-truststore.p12 plus -Djavax.net.ssl.trustStorePassword=...; prefer an injected HttpClient when one process talks to services with different trust roots.

Timeouts, retries, and cancellationCopy Anchor Link

Treat the per-attempt timeout and the caller deadline as different budgets. A retryable operation can consume several attempt timeouts plus backoff; a caller deadline or cancellation stops the whole operation.

Retries are limited to transient transport failures, 429, and bounded 5xx responses when the request is replay-safe. Buffered writes need an idempotency key; one-shot streams and ambiguous admin mutations are not replayed. Authentication, authorization, checksum, retention, legal-hold, quota, and ordinary 4xx failures are not automatic retry candidates.

Progress and streaming recoveryCopy Anchor Link

Progress callbacks run synchronously or are awaited, so a slow callback applies backpressure. Callback failure cancels the request. Go reports cumulative bytes and a known/unknown total. Node and Java also report direction, chunk bytes, and multipart part number where applicable. None of the SDKs claims transparent stream resume: recover with explicit range reads or multipart list/abort APIs and an application-owned checkpoint.

Response metadata and audit correlationCopy Anchor Link

Configure WithResponseMetadata, onResponseMetadata, or responseMetadataListener to observe successful requestId, optional Amazon request id, and optional traceparent. Errors carry their request id on the typed error. Store these identifiers beside an application job id; do not put secrets, bearer tokens, signed URL query strings, or object bytes in logs.

Concurrency and ownershipCopy Anchor Link

Clients are safe for concurrent use. Go clients may be shared between goroutines; Node clients share token minting and pooled transports; Java clients are thread-safe. Individual paginator/iterator instances and streaming bodies are operation-owned and should not be advanced or consumed concurrently. Close download bodies and any transport/executor that the application owns.

RelatedCopy Anchor Link

• Errors and retries
• Operations and observability
• SDK capability index