aliyun-oss-go-sdk

aliyun-oss-go-sdk is Alibaba Cloud’s official Go client for Object Storage Service (OSS), Alibaba’s S3-equivalent cloud storage. It exposes a Client for bucket-level administration (create/delete/list buckets, ACLs, lifecycle, logging, replication) and a Bucket type for object-level operations (put/get/copy/delete, multipart upload, symlinks, live-channel streaming), all built on a shared request-signing and HTTP transport layer.

The SDK also ships a client-side encryption module (oss/crypto) that wraps standard bucket operations with AES-CTR encryption under an RSA or Alibaba KMS master key, letting applications encrypt objects before they leave the client. It’s aimed at Go services that read and write data to Alibaba Cloud OSS buckets, whether for file storage, static asset hosting, or backups within China-region or global Alibaba Cloud deployments.

What You Get

• Client type for bucket-level operations — create/delete/list buckets, ACLs, lifecycle rules, logging, CORS, and replication.
• Bucket type for object-level operations — put/get/copy/delete, streaming to/from files, symlinks, and object tagging.
• Multipart upload and download support for large objects, plus resumable copy across buckets.
• Client-side encryption package (oss/crypto) wrapping bucket calls with AES-CTR encryption under RSA or Alibaba KMS master keys.
• Live-channel APIs for publishing and consuming RTMP media streams stored in OSS.

Common Use Cases

• Storing and serving user-uploaded files (images, video, backups) from Go backends deployed on Alibaba Cloud.
• Migrating S3-style storage workloads to Alibaba Cloud OSS for China-region deployments.
• Encrypting sensitive objects client-side before upload using RSA or KMS-managed keys.
• Building media pipelines that publish/consume live video via OSS live-channel support.

Under The Hood

Architecture The SDK splits responsibility into two top-level types built atop a shared Conn transport: Client (client.go) handles bucket-level administration — create/delete/list buckets, ACL, lifecycle, logging, CORS, replication — while Bucket (bucket.go) handles object-level operations — put/get/copy/delete, multipart transfers, symlinks, and live-channel streaming. Both route every request through Conn.Do/DoWithContext (conn.go), which builds the canonicalized resource, applies auth.go’s request signing (supporting both the legacy header scheme and the newer V4 signature), and executes the HTTP call via net/http. Request-specific behavior (headers, query params, context, progress callbacks) is threaded through a uniform functional-options system (option.go) rather than per-method parameter lists. A separate oss/crypto subpackage (crypto_bucket.go) wraps Bucket as a decorator, transparently encrypting/decrypting object bodies with AES-CTR under a pluggable MasterCipher (RSA or Alibaba KMS) before delegating to the underlying Bucket methods. Because every API call funnels through Conn’s signing and transport logic, a breaking change to request signing or the HTTP client would ripple through the entire public surface — a deliberate single-choke-point design for a REST-wrapping SDK.

Tech Stack The SDK predates Go modules internally — there is no go.mod at the repo root (the registry resolves it as a v3.0.2+incompatible pseudo-module) — and it depends almost entirely on the Go standard library: net/http for transport, encoding/xml for OSS’s XML request/response bodies, and crypto/hmac, crypto/sha1, crypto/sha256 for request signing and the client-side AES-CTR cipher. The only external dependency is github.com/aliyun/alibaba-cloud-sdk-go/services/kms, pulled in solely by the optional KMS master-cipher implementation in oss/crypto. There’s no web framework, ORM, or build tooling beyond go build/go get; CI is a single .travis.yml running go test against the module. This is a deliberately dependency-light REST client rather than a framework with its own toolchain.

Code Quality Roughly a third of the files under oss/ are test files (25 of 65), covering bucket, client, connection, crypto, multipart, upload/download, and error paths with Go’s standard testing package and table-driven assertions — no gocheck/testify usage visible. Errors are explicit and typed: ServiceError captures OSS’s XML error response (code, message, request ID, endpoint), and UnexpectedStatusCodeError distinguishes transport-level failures from service-level ones, both satisfying the standard error interface rather than being swallowed or logged silently. Naming is consistent (Do-prefixed low-level methods, verb-first public methods), and doc comments precede nearly every exported function. There’s no linter config or static-analysis step, and CI only runs tests, not lint — modest by modern standards but solid for a decade-old SDK.

API Design The public API is verb-first and consistent — every Bucket method mirrors its REST counterpart closely (PutObject, GetObject, DeleteObject, CopyObject), and optional behavior (headers, params, progress, context) is composed via variadic Option arguments rather than sprawling parameter lists or config structs, keeping call sites concise. Getting started requires only oss.New(endpoint, key, secret) followed by client.Bucket(name) — no separate config object or builder chain. Documentation is doc-comment-heavy on every exported symbol, and the 40+ files under sample/ cover nearly every operation with runnable examples, lowering the barrier to first integration. The main friction point is XML-based configuration types (lifecycle, CORS, replication) that require constructing nested structs matching OSS’s XML schema rather than a fluent builder.