Object API and HTTP

This is the front of the server: every byte of every S3 request flows through these files. The HTTP listener is started by cmd/server-main.go, the routers are registered in cmd/routers.go, and the actual S3 verbs live in cmd/object-handlers.go, cmd/bucket-handlers.go, and friends.

Purpose

Translate S3 (and Admin/STS/KMS) HTTP requests into calls on the in-process ObjectLayer interface, return correctly-shaped XML/JSON responses, and enforce auth, signature, throttling, and encoding along the way.

Directory layout

cmd/
├── routers.go                  # Composes all sub-routers in order
├── api-router.go               # S3 API routes
├── admin-router.go             # /minio/admin/v3/*
├── kms-router.go               # /minio/kms/v1/*
├── healthcheck-router.go       # /minio/health/*
├── metrics-router.go           # /minio/metrics/v2 and v3
├── generic-handlers.go         # CORS, throttling, request size, header normalisation
├── auth-handler.go             # AuthN: V2/V4 sigs, JWT, presigned URLs, post-policy
├── signature-v4*.go            # AWS Sig v4 implementation
├── signature-v2.go             # Legacy Sig v2 (still required for some clients)
├── object-handlers.go          # PUT/GET/HEAD/DELETE/COPY/Tagging/ACL
├── object-multipart-handlers.go # CreateMpu, UploadPart, CompleteMpu
├── object-lambda-handlers.go   # S3 Object Lambda
├── bucket-handlers.go          # ListBuckets, MakeBucket, DeleteBucket
├── bucket-listobjects-handlers.go
├── bucket-policy-handlers.go, bucket-lifecycle-handlers.go, ...
├── api-errors.go               # Every S3 error code (huge file)
├── api-headers.go              # Header writing helpers
├── api-response.go             # XML/JSON response writers
├── api-resources.go            # Query-param parsing
├── api-utils.go                # Shared helpers (path params, encoding)
└── object-api-interface.go     # The ObjectLayer interface

Key abstractions

Symbol	File	What it does
ObjectLayer	cmd/object-api-interface.go	The 60+ method interface every storage backend implements (erasureServerPools is the runtime).
objectAPIHandlers	cmd/api-router.go	Receiver type for every HTTP handler; holds a function returning the current ObjectLayer.
errorCodes / APIError	cmd/api-errors.go	Source of truth for S3 error codes and their HTTP status mapping.
auth-handler	cmd/auth-handler.go	Determines the auth type and validates it.
validateAdminReq	cmd/admin-handler-utils.go	Auth gate for admin handlers.
generic-handlers	cmd/generic-handlers.go	Per-request middleware (CORS, body limit, max requests).

How it works

sequenceDiagram
    participant Client
    participant Generic as generic-handlers
    participant Router as mux.Router
    participant Auth as auth-handler
    participant Verb as object/bucket/admin handler
    participant Obj as ObjectLayer

    Client->>Generic: HTTP request
    Generic->>Generic: CORS, body limit, max reqs
    Generic->>Router: pass through
    Router->>Auth: route matched
    Auth->>Auth: SigV4/V2/JWT/post-policy validation
    Auth->>Verb: ctx + claims
    Verb->>Verb: parse path/query, lock
    Verb->>Obj: ObjectLayer call
    Obj-->>Verb: result or error
    Verb->>Client: writeSuccessResponse* / writeErrorResponse

Routing order

cmd/routers.go mounts sub-routers in this order so the wildcard S3 path doesn't shadow the structured routes:

1. Health (/minio/health).
2. Metrics (/minio/metrics/v2, /minio/metrics/v3).
3. Admin (/minio/admin/v3).
4. KMS (/minio/kms/v1).
5. STS (/minio/sts).
6. S3 (/{bucket} and /{bucket}/{object:.+}).

S3 verb dispatch

cmd/api-router.go registers handlers in two passes:

1. Bucket-scoped paths — ListObjectsV2, PutBucketPolicy, lifecycle, replication, encryption, tagging — registered as path patterns with query-string predicates (?policy, ?lifecycle, ...).
2. Object-scoped paths — PutObject, HeadObject, multipart, etc.

Several "rejected" S3 features (BitTorrent, accelerate, payment) are intercepted by the rejectedObjAPIs and rejectedBucketAPIs slices in cmd/api-router.go and answered with NotImplemented.

Auth selection

cmd/auth-handler.go looks at the incoming request and chooses one of:

• AuthTypeAnonymous
• AuthTypePresignedV2, AuthTypePresigned (V4)
• AuthTypeSignedV2, AuthTypeSigned (V4)
• AuthTypePostPolicy
• AuthTypeStreamingSigned, AuthTypeStreamingUnsigned, AuthTypeStreamingSignedTrailer
• AuthTypeJWT (browser/console flows)
• AuthTypeSTS (after STS-issued credentials are decoded)

Signature math is in cmd/signature-v4.go and cmd/signature-v2.go. Streaming SigV4 (chunked) lives in cmd/streaming-signature-v4.go and cmd/streaming-v4-unsigned.go.

Response writing

Use the helpers in cmd/api-response.go:

• writeSuccessResponseXML / writeSuccessResponseJSON
• writeSuccessNoContent
• writeErrorResponse / writeErrorResponseHeadersOnly
• setCommonHeaders / setRequestIDInResponseHeader

Errors get stringified through errorCodes.ToAPIErr and produce the canonical <Error>...</Error> body.

Integration points

• Calls ObjectLayer (implemented by cmd/erasure-server-pool.go).
• Acquires locks via cmd/namespace-lock.go.
• Reads identity/credential state from cmd/iam.go.
• Emits notifications through cmd/event-notification.go.
• Emits replication queue entries through cmd/bucket-replication.go.
• Emits audit events through internal/logger/audit/.
• Emits Prometheus stats through cmd/http-stats.go and the v2/v3 metrics collectors.

Entry points for modification

• New S3 verb. Add a method to ObjectLayer (object-api-interface.go), implement it in erasure-server-pool.go, register a handler in api-router.go, write a unit test in object-handlers_test.go. Reuse auth-handler.go for auth.
• New error code. Add to the enum in api-errors.go, run go generate ./... for apierrorcode_string.go, then return via errorCodes.ToAPIErr(...).
• New header behaviour. Update api-headers.go and the related response helpers; tests in api-headers_test.go.