Migration and compatibility

Start with the S3-compatible surface when replacing an endpoint in an existing application. Move selected workflows to the native client only when JSON errors, constrained signed URLs, browser CORS, notifications, or the app kit materially simplify the application.

S3 migration checklistCopy Anchor Link

1. Pin a Lockwell server release and the matching first-party SDK release line.
2. Use path-style addressing first; enable virtual-hosted style only after wildcard DNS/TLS validation.
3. Set the region explicitly when it differs from us-east-1.
4. Run the application's real object names, ranges, checksums, multipart sizes, versioning, and Object Lock denial paths.
5. Replace provider-specific IAM/STS/KMS/event-bus features instead of assuming S3 wire compatibility includes them.
6. Verify backup/restore and migration-copy evidence before making a provider-replacement claim.

Lockwell supports the operations in the S3 operations reference. Unsupported subresources fail closed. The compatibility matrix is evidence, not permission to infer an unlisted feature.

Native adoptionCopy Anchor Link

Native clients use /api/v1/ on the public object listener and auto-manage short-lived bearer tokens minted from an access key. Admin clients use /admin/api/v1/ on the private admin listener and an admin token. Do not swap their credentials or expose the admin listener as a public object endpoint.

The app kit composes existing native/admin calls; it does not introduce a fourth wire API. Keep application-owned tenant and ERP mappings in the application database, and use opaque identifiers rather than customer names or tax ids.

Selecting Native Wire during migrationCopy Anchor Link

LNW/1 is an explicit, experimental binary transport for the native data plane. It runs on a separate configured TLS 1.3 listener and has no JSON/S3 fallback. Migrate a server-side workflow only after the target runtime appears in the Native Wire capability index: the currently merged consumers are the Node/Bun shared TypeScript client, SolidStart v2 server adapter, and Spring Boot starter. Keep S3 or HTTP-native JSON as an explicitly selected rollback mode, and do not catch a native error to silently change transports. There is no transparent byte-offset resume; use idempotency keys or committed multipart parts.

Supported native SDK languagesCopy Anchor Link

The currently supported first-party SDK languages are Go, Node/TypeScript, and Java. There is no first-party .NET, Rust, PHP, or Ruby SDK; those languages are explicit product non-goals. Applications in those ecosystems may use a compatible S3 library against the documented S3 surface, but that does not create a native/admin SDK support claim.

Proposal documents, generated OpenAPI experiments, and unexported server handlers are not public SDK APIs. A capability is documented here only when exported source and executable tests support it.

Security differences to preserveCopy Anchor Link

• Buckets remain private; there is no anonymous/public-bucket migration mode.
• S3 presigned GET/PUT/HEAD/DELETE and native signed GET/PUT URLs are bearer capabilities. Keep TTLs short.
• SSE-C is supported on the S3 surface with typed helpers; SSE-KMS is not.
• Retention and legal-hold denials are expected safety behavior, not compatibility bugs.
• Never log access-key secrets, admin/bearer tokens, SSE-C keys, raw object data, or signed URL query strings.

Release and package boundaryCopy Anchor Link

Examples use historical 0.2.2 coordinates. Lockwell is closed source during early access: current packages and a licence come with access (hello@rusticstack.com). Do not infer public package publication from documentation alone.