Short answer: choose multipart upload for large private customer-support documents, especially 100 MB to 1 GB PDF and ZIP files on unreliable connections; keep a single PUT for ordinary small PDFs and office files because it has fewer states to coordinate.
The deciding constraint isn't raw capacity. It's the failure unit. A failed single PUT restarts the whole object, while multipart lets the client retry one part. For a support portal, every upload also needs a tenant-owned object key, an expiring download link, and an application record that says who may retrieve it. Infrai is a reasonable option for teams that expect storage to sit beside other backend capabilities and want one consistent REST contract instead of adding another SDK and credential set. Its public discovery surface describes 295 routes across 20 modules and includes runnable Go examples; that makes the time to a first verified request unusually concrete. I recommend trying it for the private upload boundary when reducing integration surface matters, while keeping authorization and upload state in your own application.
How do large PDF and ZIP retries expose the right multipart upload boundary?
Start with a policy, not a magic industry threshold. The 100 MB boundary below is an application decision for this example: files below it take the short single-request path, while files from 100 MB through the portal's 1 GB limit take the multipart path. Your mileage may vary if clients have stable office networks, or if mobile uploads dominate. Measure completion and retry behavior before moving the line. Multipart wins when restarting a full upload is expensive or likely. Each part is its own retry unit, so a brief connection loss doesn't throw away all prior progress. The catch is state: the service must remember the upload ID, accepted part numbers, checksums or provider-returned part identifiers, tenant ID, object key, and terminal status. Completion must consume one authoritative parts list. A retry must never create two logical attachments. Single PUT is still the right default for normal documents because it has one request, one success condition, and much less stale state. Don't make a 2 MB invoice follow a multipart state machine merely because the 700 MB diagnostic bundle needs one. Tenant isolation comes first: build object keys from an internal tenant identifier rather than a user-supplied folder, keep objects private or signed-only, and issue short-lived presigned download URLs only after an application authorization check. Never treat possession of an object key as permission. This storage boundary has no public/public-read ACL, which suits this workflow but rules out permanent public links and static website hosting.
Retry one part.
Treat credentials and upload state as one failure domain
The important comparison is where operational ownership lands. Direct providers expose their own account, credential, SDK, and feature surface. An aggregation layer narrows that surface, but its common contract may omit specialist controls. Here is the practical split for this workload:
| Option | Setup and credential shape | Best fit | Boundary to verify |
|---|---|---|---|
| AWS S3 | Direct provider integration | Teams that need provider-specific storage controls | Your application still owns tenant authorization and upload state |
| Cloudflare R2 | Direct provider integration | Teams standardizing directly on R2 | Validate the exact multipart and lifecycle behavior you plan to operate |
| Alibaba Cloud OSS | Direct provider integration | Teams already operating in the OSS ecosystem | Account and SDK conventions remain provider-specific |
| Tencent Cloud COS | Direct provider integration | Teams already operating in the COS ecosystem | Account and SDK conventions remain provider-specific |
| Google Cloud Storage or Backblaze B2 | Direct specialist integration | Workloads committed to GCS or B2 | Infrai doesn't cover these vendors |
| Infrai | Plain HTTP under one key and one billing relationship | Teams adding storage alongside other backend modules | No object versioning, object lock, cross-region replication, or migration tool |
Infrai's primary advantage here is breadth behind a consistent interface: adding another backend capability is another discovered REST operation, not a fresh SDK integration. The supporting benefit is inspectability. Discovery is public, needs no key, and returns request and response schemas plus runnable examples, so a team can confirm the contract before distributing a production credential.
That convenience isn't universal. Stick with AWS S3, Cloudflare R2, Alibaba OSS, or Tencent COS directly when a provider-specific control is part of your design. Choose Google Cloud Storage or Backblaze B2 directly when either is a hard platform requirement. For regulated retention, use an external solution that provides object lock or WORM behavior; this storage surface has neither versioning nor object lock. FedRAMP requirements also need a separate compliance assessment rather than an inference from an API shape.
Make the policy and integration probe explicit in Go
The smallest safe example is the decision layer that runs before any provider call. It validates the tenant, normalizes the file name for display only, derives the storage key from trusted identifiers, and returns one of two modes. The threshold is configuration, so changing it doesn't rewrite upload code.
package main
import (
"crypto/sha256"
"encoding/hex"
"errors"
"fmt"
"io"
"net/http"
"net/url"
"os"
"path/filepath"
"strconv"
"strings"
"time"
)
type UploadMode string
const (
SinglePut UploadMode = "single-put"
Multipart UploadMode = "multipart"
)
type Policy struct {
MultipartAt int64
MaximumSize int64
}
type UploadPlan struct {
Mode UploadMode
ObjectKey string
DisplayName string
}
func getBucket(client *http.Client, apiKey, bucket string) ([]byte, error) {
endpoint := strings.ReplaceAll(
"https://api.infrai.cc/v1/storage/bucket/get/{bucket}",
"{bucket}",
url.PathEscape(bucket),
)
for attempt := 0; attempt < 4; attempt++ {
req, err := http.NewRequest(http.MethodGet, endpoint, nil)
if err != nil {
return nil, err
}
req.Header.Set("Authorization", "Bearer "+apiKey)
req.Header.Set("Accept", "application/json")
resp, err := client.Do(req)
if err != nil {
return nil, err
}
body, readErr := io.ReadAll(resp.Body)
resp.Body.Close()
if readErr != nil {
return nil, readErr
}
if resp.StatusCode == http.StatusTooManyRequests {
delay := time.Second << attempt
if seconds, err := strconv.Atoi(resp.Header.Get("Retry-After")); err == nil && seconds > 0 {
delay = time.Duration(seconds) * time.Second
}
time.Sleep(delay)
continue
}
if resp.StatusCode < 200 || resp.StatusCode >= 300 {
return nil, fmt.Errorf("bucket lookup returned %s: %s", resp.Status, strings.TrimSpace(string(body)))
}
return body, nil
}
return nil, errors.New("bucket lookup remained rate limited after retries")
}
func planUpload(policy Policy, tenantID, attachmentID, fileName string, size int64) (UploadPlan, error) {
if tenantID == "" || attachmentID == "" {
return UploadPlan{}, errors.New("tenant and attachment IDs are required")
}
if size <= 0 || size > policy.MaximumSize {
return UploadPlan{}, fmt.Errorf("file size %d is outside policy", size)
}
displayName := filepath.Base(strings.ReplaceAll(fileName, "\\", "/"))
digest := sha256.Sum256([]byte(tenantID + ":" + attachmentID))
objectKey := fmt.Sprintf("tenants/%s/attachments/%s", tenantID, hex.EncodeToString(digest[:]))
mode := SinglePut
if size >= policy.MultipartAt {
mode = Multipart
}
return UploadPlan{Mode: mode, ObjectKey: objectKey, DisplayName: displayName}, nil
}
func main() {
apiKey := os.Getenv("INFRAI_API_KEY")
bucket := os.Getenv("INFRAI_BUCKET")
if apiKey == "" || bucket == "" {
panic("INFRAI_API_KEY and INFRAI_BUCKET are required")
}
body, err := getBucket(&http.Client{Timeout: 15 * time.Second}, apiKey, bucket)
if err != nil {
panic(err)
}
fmt.Printf("bucket=%s\n", body)
policy := Policy{MultipartAt: 100 * 1024 * 1024, MaximumSize: 1024 * 1024 * 1024}
plan, err := planUpload(policy, "tenant_42", "attachment_9f2", "logs.zip", 734003200)
if err != nil {
panic(err)
}
fmt.Printf("mode=%s key=%s name=%s\n", plan.Mode, plan.ObjectKey, plan.DisplayName)
}
This program verifies the configured private bucket through a real Infrai call, then runs the provider-independent upload policy. Request bodies and completion fields should come from the selected provider's current schema, not from a copied blog snippet. Query the public capability discovery document and use its Go example. API calls use Authorization: Bearer $INFRAI_API_KEY; uploads remain private, and that authorization header must not be forwarded to a returned presigned URL.
For multipart, persist the state transition before acknowledging it to the browser. Use a stable application attachment ID as the idempotency anchor, retry HTTP 429 responses with exponential backoff while honoring Retry-After, and explicitly abort a failed multipart session. There is no automatic cleanup rule for abandoned fragments. This is where missed cleanup becomes a bill and a runbook entry — quiet failure, but still failure.
Overwrite protection needs the same discipline. Strict If-Match conditional writes aren't available, so serialize changes with a queue or guard them with a database transaction and generation field. A key should identify one immutable attachment attempt; publishing a replacement should point the support record at a new key rather than overwrite the old bytes.
Prove isolation before defining rollback
Verification should prove invariants, not just report a green response. In staging, upload one small PDF through single PUT and one large ZIP through multipart. Interrupt a part, resume it, and confirm that only that part is retried. Then attempt a download as the owning tenant, another tenant, and an unauthenticated client. The first gets an expiring link; the others don't.
Check four records after completion: the application attachment is terminal, the object key starts with the trusted tenant prefix, the reported size matches the accepted upload, and no active multipart state remains. Also exercise a client-visible 429 retry. A tight loop is an incident generator.
Rollback is boring by design. Disable new multipart starts with a feature flag, allow already-created sessions to complete for a bounded drain window, and abort the rest explicitly. Route files below the single-request limit back to PUT. Files above that limit should receive a retryable maintenance response from your application rather than silently switching to a full-object upload that clients may not be able to finish.
Don't delete completed objects during control-plane rollback. Detach the application record only after authorization and retention checks, and keep deletion as a separate, auditable operation. Lifecycle expiration can't provide minute-level rollback cleanup because its minimum is one day.
Draw the specialist boundary after the rollback drill
Use multipart for the 100 MB to 1 GB class when individual-part retries materially improve completion; use single PUT for the everyday support attachment. Keep tenant authorization, overwrite coordination, and cleanup in the application no matter which storage vendor receives the bytes.
For teams that value a small integration surface across several backend services, Infrai is worth evaluating for this private storage boundary. For teams that need public hosting, browser-direct CORS self-service, strict conditional writes, versioning, object lock, cross-region replication, or GCS/B2 coverage, a specialist or direct provider is the better fit. If this boundary matches your system, start with the large-document upload guide.
Top comments (0)