leblob 0.4.0.dev1__py3-none-any.whl

leblob/handlers.py

@@ -0,0 +1,1119 @@
+"""One async function per S3 operation: the orchestration of everything else."""
+
+from __future__ import annotations
+
+import asyncio
+import re
+import secrets
+import time
+from contextlib import aclosing
+from dataclasses import dataclass, replace
+from typing import TYPE_CHECKING
+from urllib.parse import quote, urlencode
+
+from leblob import blobstore, meta, streams
+from leblob.model import (
+    NULL_VERSION_ID,
+    ByteSpan,
+    ObjectRecord,
+    ObjectRef,
+    UploadExtras,
+    UploadRef,
+)
+from leblob.s3 import (
+    access,
+    conditions,
+    cors,
+    errors,
+    listing,
+    multipart,
+    payload,
+    post_form,
+    routing,
+    sigv4,
+    sse,
+    tagging,
+    xml,
+    xml_config,
+)
+from leblob.s3.access import Level
+from leblob.s3.errors import S3Error
+from leblob.s3.routing import Operation
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncGenerator, Awaitable, Callable, Mapping
+    from pathlib import Path
+    from typing import Any
+
+    from leblob.blobstore import BlobStore
+    from leblob.meta import Database
+    from leblob.model import (
+        Blob,
+        Checksum,
+        CorsRule,
+        DeleteOutcome,
+    )
+    from leblob.s3.access import Scope
+    from leblob.s3.sigv4 import StreamSeed
+
+MAX_XML_BYTES = 4 * 1024 * 1024
+MAX_METADATA_BYTES = 2048
+
+_STORED_HEADERS = (
+    "cache-control",
+    "content-disposition",
+    "content-language",
+    "content-type",
+    "expires",
+)
+_DEFAULT_CONTENT_TYPE = "binary/octet-stream"
+_META_PREFIX = "x-amz-meta-"
+_XML_CONTENT_TYPE = "application/xml"
+# Tab and printable Latin-1. Anything else couldn't be sent as a header.
+_VALID_HEADER_VALUE = re.compile(r"[\t\x20-\x7e\x80-\xff]*")
+_UPLOAD_ID_BYTES = 24
+_RESPONSE_OVERRIDES = {
+    "response-cache-control": "cache-control",
+    "response-content-disposition": "content-disposition",
+    "response-content-encoding": "content-encoding",
+    "response-content-language": "content-language",
+    "response-content-type": "content-type",
+    "response-expires": "expires",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class _CopySource:
+    """What a copy reads: the object, where it is, and the version named, if any."""
+
+    bucket: str
+    version_id: str | None
+    record: ObjectRecord
+    key: sse.CustomerKey | None
+
+
+@dataclass(frozen=True, slots=True)
+class Context:
+    db: Database
+    blobs: BlobStore
+    data_dir: Path
+    lifecycle_day_ms: int = meta.DAY_MS
+    sse_over_http: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class Request:
+    """A request that has passed authentication."""
+
+    headers: Mapping[str, str]
+    query: Mapping[str, str]
+    receive: Callable[[], Awaitable[Mapping[str, Any]]]
+    stream_seed: StreamSeed | None  # None when it carries no signature.
+    scope: Scope
+    secure: bool = False
+
+
+@dataclass(frozen=True, slots=True)
+class Response:
+    status: int = 200
+    headers: tuple[tuple[str, str], ...] = ()
+    body: bytes | AsyncGenerator[bytes] = b""
+
+
+#
+# Service and buckets
+#
+async def list_buckets(ctx: Context, request: Request) -> Response:
+    buckets = await meta.list_buckets(ctx.db)
+    visible = [bucket for bucket in buckets if request.scope.sees(bucket.name)]
+    return _xml_response(xml.render_buckets(visible))
+
+
+async def create_bucket(ctx: Context, request: Request, bucket: str) -> Response:
+    # The body only names a region, and a single store has one location.
+    await _read_small_body(request)
+    await meta.create_bucket(
+        ctx.db, bucket, public=request.headers.get("x-amz-acl") == "public-read"
+    )
+    return Response(headers=(("location", f"/{bucket}"),))
+
+
+async def delete_bucket(ctx: Context, _request: Request, bucket: str) -> Response:
+    await meta.delete_bucket(ctx.db, bucket)
+    return Response(status=204)
+
+
+async def head_bucket(ctx: Context, _request: Request, bucket: str) -> Response:
+    await meta.require_bucket(ctx.db, bucket)
+    return Response()
+
+
+async def get_bucket_location(ctx: Context, _request: Request, bucket: str) -> Response:
+    await meta.require_bucket(ctx.db, bucket)
+    return _xml_response(xml.render_location())
+
+
+async def get_bucket_versioning(
+    ctx: Context, _request: Request, bucket: str
+) -> Response:
+    return _xml_response(
+        xml.render_versioning(await meta.get_versioning(ctx.db, bucket))
+    )
+
+
+async def put_bucket_versioning(
+    ctx: Context, request: Request, bucket: str
+) -> Response:
+    state = xml.parse_versioning(await _read_small_body(request))
+    if state is None:
+        await meta.require_bucket(ctx.db, bucket)
+    else:
+        await meta.set_versioning(ctx.db, bucket, state)
+    return Response()
+
+
+async def get_bucket_lifecycle(
+    ctx: Context, _request: Request, bucket: str
+) -> Response:
+    configuration = await meta.get_lifecycle(ctx.db, bucket)
+    return _xml_response(configuration.encode())
+
+
+async def put_bucket_lifecycle(ctx: Context, request: Request, bucket: str) -> Response:
+    rules = xml_config.parse_lifecycle(await _read_small_body(request))
+    await meta.set_lifecycle(
+        ctx.db, bucket, xml_config.render_lifecycle(rules).decode()
+    )
+    return Response()
+
+
+async def delete_bucket_lifecycle(
+    ctx: Context, _request: Request, bucket: str
+) -> Response:
+    await meta.set_lifecycle(ctx.db, bucket, None)
+    return Response(status=204)
+
+
+async def get_bucket_acl(ctx: Context, _request: Request, bucket: str) -> Response:
+    await meta.require_bucket(ctx.db, bucket)
+    public = await meta.bucket_is_public(ctx.db, bucket)
+    return _xml_response(xml_config.render_acl(public=public))
+
+
+async def put_bucket_acl(ctx: Context, request: Request, bucket: str) -> Response:
+    await meta.set_bucket_public(
+        ctx.db, bucket, public=await _public_in_acl_request(request)
+    )
+    return Response()
+
+
+async def _public_in_acl_request(request: Request) -> bool:
+    """Read an ACL from its header, or if there is none, from the body."""
+    canned = request.headers.get("x-amz-acl")
+    if canned is not None:
+        return canned == "public-read"
+    return xml_config.parse_acl(await _read_small_body(request))
+
+
+async def get_bucket_cors(ctx: Context, _request: Request, bucket: str) -> Response:
+    await meta.require_bucket(ctx.db, bucket)
+    configuration = await meta.get_cors(ctx.db, bucket)
+    if configuration is None:
+        raise S3Error(errors.NO_SUCH_CORS)
+    return _xml_response(configuration.encode())
+
+
+async def put_bucket_cors(ctx: Context, request: Request, bucket: str) -> Response:
+    rules = xml_config.parse_cors(await _read_small_body(request))
+    await meta.set_cors(ctx.db, bucket, xml_config.render_cors(rules).decode())
+    return Response()
+
+
+async def delete_bucket_cors(ctx: Context, _request: Request, bucket: str) -> Response:
+    await meta.set_cors(ctx.db, bucket, None)
+    return Response(status=204)
+
+
+async def cors_preflight(
+    ctx: Context, headers: Mapping[str, str], bucket: str
+) -> Response:
+    """Answer a browser asking whether it may send a request. It can't sign this."""
+    origin = headers.get("origin")
+    method = headers.get("access-control-request-method")
+    if origin is None or method is None:
+        raise S3Error(errors.INVALID_REQUEST, "This isn't a CORS preflight request.")
+    wanted = cors.split_header_names(headers.get("access-control-request-headers", ""))
+    rule = cors.find_rule(await _cors_rules(ctx, bucket), origin, method, wanted)
+    if rule is None:
+        raise S3Error(errors.ACCESS_FORBIDDEN)
+    return Response(headers=cors.preflight_headers(rule, origin, wanted))
+
+
+async def cors_headers_for(
+    ctx: Context, method: str, origin: str, bucket: str
+) -> tuple[tuple[str, str], ...]:
+    """What a browser needs to be allowed to read the answer to a request.
+
+    With rules, an answer depends on the origin, allowed or not, so it says so to
+    caches. Otherwise a cache could give one origin what was meant for another.
+    """
+    rules = await _cors_rules(ctx, bucket)
+    if not rules:
+        return ()
+    rule = cors.find_rule(rules, origin, method)
+    return cors.VARY if rule is None else cors.response_headers(rule, origin)
+
+
+async def _cors_rules(ctx: Context, bucket: str) -> tuple[CorsRule, ...]:
+    configuration = await meta.get_cors(ctx.db, bucket)
+    return (
+        () if configuration is None else xml_config.parse_cors(configuration.encode())
+    )
+
+
+async def list_objects_v1(ctx: Context, request: Request, bucket: str) -> Response:
+    query = request.query
+    list_query = _list_query(query, query.get("marker", ""))
+    page = await meta.list_objects(ctx.db, bucket, list_query)
+    return _xml_response(xml.render_list_v1(bucket, query, page, list_query.max_keys))
+
+
+async def list_objects_v2(ctx: Context, request: Request, bucket: str) -> Response:
+    query = request.query
+    after = (
+        listing.decode_token(query["continuation-token"])
+        if "continuation-token" in query
+        else query.get("start-after", "")
+    )
+    list_query = _list_query(query, after)
+    page = await meta.list_objects(ctx.db, bucket, list_query)
+    next_token = (
+        listing.encode_token(page.next_marker) if page.next_marker is not None else None
+    )
+    return _xml_response(
+        xml.render_list_v2(bucket, query, page, list_query.max_keys, next_token)
+    )
+
+
+async def list_object_versions(ctx: Context, request: Request, bucket: str) -> Response:
+    query = request.query
+    list_query = _list_query(query, query.get("key-marker", ""))
+    page = await meta.list_versions(
+        ctx.db, bucket, list_query, query.get("version-id-marker", "")
+    )
+    return _xml_response(xml.render_versions(bucket, query, page, list_query.max_keys))
+
+
+async def delete_objects(ctx: Context, request: Request, bucket: str) -> Response:
+    targets, quiet = xml.parse_delete(await _read_small_body(request))
+    if any(target.version_id is not None for target in targets):
+        access.require(request.scope, bucket, Level.ADMIN)  # As for one such delete.
+    parsed = [
+        replace(target, key=routing.parse_decoded_key(target.key.encode()))
+        for target in targets
+    ]
+    outcomes = await meta.delete_objects(ctx.db, bucket, parsed)
+    return _xml_response(xml.render_deleted(outcomes, quiet=quiet))
+
+
+#
+# Objects
+#
+async def put_object(ctx: Context, request: Request, bucket: str, key: str) -> Response:
+    await meta.require_bucket(ctx.db, bucket)
+    condition = conditions.parse_write_condition(request.headers)
+    headers = _headers_to_store(request.headers)
+    tags = _tags_in_header(request)
+    public = _public_on_write(request, bucket)
+    key_sent = streams.customer_key(ctx, request)
+    blob, checksum = await streams.receive_blob(ctx, request, None, key_sent)
+    record = ObjectRecord(
+        key,
+        streams.client_size(blob, key_sent),
+        blob.md5,
+        meta.now_ms(),
+        headers,
+        checksum,
+        (blob,),
+        tags=tags,
+        public=public,
+        sse_check=key_sent.check if key_sent else None,
+    )
+    version_id = await _commit_new_blob(ctx, bucket, record, condition)
+    return Response(
+        headers=(
+            *_etag_headers(blob.md5, checksum),
+            *_new_version_headers(version_id),
+            *streams.key_headers(key_sent),
+        )
+    )
+
+
+async def copy_object(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    copied = await _load_copy_source(ctx, request)
+    source = copied.record
+    new_metadata = request.headers.get("x-amz-metadata-directive") == "REPLACE"
+    # Copying an older version onto its key is how one is restored.
+    restoring = copied.version_id is not None
+    onto_itself = (copied.bucket, source.key) == (bucket, key)
+    if onto_itself and not (new_metadata or restoring):
+        raise S3Error(
+            errors.INVALID_REQUEST,
+            "Copying an object onto itself must change its metadata.",
+        )
+    if source.size > streams.MAX_OBJECT_BYTES:
+        raise S3Error(errors.INVALID_REQUEST, "The source is too large for CopyObject.")
+    await meta.require_bucket(ctx.db, bucket)
+
+    condition = conditions.parse_write_condition(request.headers)
+    headers = _headers_to_store(request.headers) if new_metadata else source.headers
+    tags = _tags_of_a_copy(request, source)
+    public = _public_on_write(request, bucket)  # As asked: a copy doesn't inherit it.
+    key_sent = streams.customer_key(ctx, request)
+    blob, _ = await streams.copy_to_new_blob(
+        ctx,
+        streams.plain_bytes(ctx, source, ByteSpan(0, source.size), copied.key),
+        None,
+        key_sent,
+    )
+
+    record = ObjectRecord(
+        key,
+        streams.client_size(blob, key_sent),
+        blob.md5,
+        meta.now_ms(),
+        headers,
+        None,
+        (blob,),
+        tags=tags,
+        public=public,
+        sse_check=key_sent.check if key_sent else None,
+    )
+    version_id = await _commit_new_blob(ctx, bucket, record, condition)
+    return _xml_response(
+        xml.render_copy_result(blob.md5, record.modified_at),
+        (
+            *_new_version_headers(version_id),
+            *_copy_source_headers(copied),
+            *streams.key_headers(key_sent),
+        ),
+    )
+
+
+async def get_object(ctx: Context, request: Request, bucket: str, key: str) -> Response:
+    record = await _record_to_read(ctx, request, bucket, key)
+    return _object_response(ctx, request, record, include_body=True)
+
+
+async def head_object(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    record = await _record_to_read(ctx, request, bucket, key)
+    return _object_response(ctx, request, record, include_body=False)
+
+
+async def _record_to_read(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> ObjectRecord:
+    """Find what a read asks for, if whoever is asking may read it.
+
+    In one read with the object, so a private version can't slip in after the check.
+    Only those who may list a bucket learn that a key isn't in it.
+    """
+    version_id = request.query.get("versionId")
+    if request.scope is not access.ANONYMOUS:
+        return await meta.get_object(ctx.db, bucket, key, version_id)
+    if not _RESPONSE_OVERRIDES.keys().isdisjoint(request.query):
+        # A stranger's link shouldn't choose how a browser treats someone's object.
+        raise S3Error(errors.INVALID_REQUEST, "Only a signed request can do that.")
+    try:
+        record = await meta.get_object(ctx.db, bucket, key, version_id)
+    except S3Error as error:
+        if await meta.bucket_is_public(ctx.db, bucket):
+            raise S3Error(error.error, error.message) from None
+        raise S3Error(errors.ACCESS_DENIED) from None
+    if not record.public:
+        raise S3Error(errors.ACCESS_DENIED)
+    return record
+
+
+async def post_object(ctx: Context, request: Request, bucket: str) -> Response:
+    """Store a browser's form. The form signs itself, so nothing is trusted before."""
+    boundary = post_form.parse_boundary(request.headers.get("content-type", ""))
+    async with aclosing(_form_events(request, boundary)) as events:
+        fields, filename = await _read_form_fields(events)
+        access_key = sigv4.post_form_access_key(fields)
+        secret, scope = await meta.get_access_key(ctx.db, access_key)
+        sigv4.verify_post_form(fields, secret)
+        access.require(scope, bucket, Level.WRITE)
+        if "key" not in fields:
+            raise S3Error(errors.INVALID_ARGUMENT, "A form must name a key.")
+        fields["key"] = fields["key"].replace("${filename}", filename)
+        limits = post_form.check_policy({**fields, "bucket": bucket}, time.time())
+        routing.refuse_unsupported_headers(fields)
+        key = routing.parse_decoded_key(fields["key"].encode())
+        public = _public_in_form(fields)
+        if public:
+            access.require(scope, bucket, Level.ADMIN)
+        await meta.require_bucket(ctx.db, bucket)
+        record = await _store_form_file(
+            ctx, ObjectRef(bucket, key), fields, events, limits
+        )
+        record = replace(record, public=public)
+    version_id = await _commit_new_blob(
+        ctx, bucket, record, conditions.WriteCondition()
+    )
+    return _post_response(fields, bucket, key, record.etag, version_id)
+
+
+async def _form_events(
+    request: Request, boundary: bytes
+) -> AsyncGenerator[post_form.Event]:
+    parser = post_form.FormParser(boundary)
+    decoder = payload.new_decoder(payload.parse_spec({}), request.stream_seed)
+    async for chunk in streams.decoded_body(request, decoder):
+        for event in parser.feed(chunk):
+            yield event
+    parser.finish()
+
+
+async def _read_form_fields(
+    events: AsyncGenerator[post_form.Event],
+) -> tuple[dict[str, str], str]:
+    """Read up to the file, and leave it unread. Returns the fields and its name."""
+    fields: dict[str, str] = {}
+    async for event in events:
+        if isinstance(event, post_form.Field):
+            if event.name in fields:
+                raise S3Error(errors.MALFORMED_POST, f"Two fields: {event.name}.")
+            fields[event.name] = event.value
+        elif isinstance(event, post_form.FileStart):
+            return fields, event.filename
+    raise S3Error(errors.INVALID_ARGUMENT, "A form must hold a file.")
+
+
+def _public_in_form(fields: Mapping[str, str]) -> bool:
+    acl = fields.get("acl", "private")
+    if "x-amz-acl" in fields or acl not in {"private", "public-read"}:
+        raise S3Error(errors.NOT_IMPLEMENTED, f"acl: {acl} is not implemented.")
+    return acl == "public-read"
+
+
+async def _store_form_file(
+    ctx: Context,
+    target: ObjectRef,
+    fields: Mapping[str, str],
+    events: AsyncGenerator[post_form.Event],
+    limits: post_form.SizeLimits,
+) -> ObjectRecord:
+    """Make the file a blob, once the form has been seen to end properly."""
+    if any(name.startswith(sse.HEADER_PREFIX) for name in fields):
+        raise S3Error(errors.NOT_IMPLEMENTED, "A form can't be encrypted yet.")
+    tags = (
+        xml_config.parse_tagging(fields["tagging"].encode())
+        if "tagging" in fields
+        else {}
+    )
+    headers = _headers_to_store(fields)
+    spec = payload.parse_spec({
+        name: value
+        for name, value in fields.items()
+        if name == "content-md5" or name.startswith("x-amz-checksum-")
+    })
+    largest = streams.MAX_OBJECT_BYTES if limits.largest is None else limits.largest
+
+    async def file_data() -> AsyncGenerator[bytes]:
+        async for event in events:
+            if isinstance(event, post_form.FileEnd):
+                return
+            if isinstance(event, post_form.FileData):
+                yield event.data
+
+    with ctx.blobs.writer(payload.new_hashers(spec)) as writer:
+        await blobstore.write_stream(
+            writer, file_data(), min(largest, streams.MAX_OBJECT_BYTES)
+        )
+        async for _ in events:  # Up to the closing delimiter, or the error of its lack.
+            pass
+        if writer.size < limits.smallest:
+            raise S3Error(
+                errors.ENTITY_TOO_SMALL, "The file is below the policy's minimum."
+            )
+        checksum = payload.verify(spec, writer.digests(), writer.size, {})
+        blob = await asyncio.to_thread(writer.commit)
+    return ObjectRecord(
+        target.key,
+        blob.size,
+        blob.md5,
+        meta.now_ms(),
+        headers,
+        checksum,
+        (blob,),
+        tags=tags,
+    )
+
+
+def _post_response(
+    fields: Mapping[str, str],
+    bucket: str,
+    key: str,
+    etag: str,
+    version_id: str | None,
+) -> Response:
+    location = f"/{bucket}/{quote(key)}"
+    headers = (
+        ("etag", f'"{etag}"'),
+        ("location", location),
+        *_new_version_headers(version_id),
+    )
+    redirect = fields.get("success_action_redirect", "")
+    if redirect.startswith(("http://", "https://")):
+        separator = "&" if "?" in redirect else "?"
+        query = urlencode({"bucket": bucket, "key": key, "etag": f'"{etag}"'})
+        target = f"{redirect}{separator}{query}"
+        if not _VALID_HEADER_VALUE.fullmatch(target):
+            raise S3Error(errors.INVALID_ARGUMENT, "That redirect is not valid.")
+        return Response(status=303, headers=(("location", target),))
+    status = fields.get("success_action_status")
+    if status == "201":
+        body = xml.render_post_result(bucket, key, etag, location)
+        return Response(
+            status=201,
+            headers=(("content-type", _XML_CONTENT_TYPE), *headers),
+            body=body,
+        )
+    return Response(status=200 if status == "200" else 204, headers=headers)
+
+
+async def get_object_acl(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    record = await meta.get_object(ctx.db, bucket, key, request.query.get("versionId"))
+    return _xml_response(
+        xml_config.render_acl(public=record.public),
+        _new_version_headers(record.version_id),
+    )
+
+
+async def put_object_acl(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    public = await _public_in_acl_request(request)
+    if public:
+        access.require(request.scope, bucket, Level.ADMIN)
+    version_id = await meta.set_object_public(
+        ctx.db, ObjectRef(bucket, key), request.query.get("versionId"), public=public
+    )
+    return Response(headers=_new_version_headers(version_id))
+
+
+def _public_on_write(request: Request, bucket: str) -> bool:
+    """Whether a new object is to be public, which takes more than writing it."""
+    public = request.headers.get("x-amz-acl") == "public-read"
+    if public:
+        access.require(request.scope, bucket, Level.ADMIN)
+    return public
+
+
+async def delete_object(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    condition = conditions.parse_write_condition(request.headers)
+    outcome = await meta.delete_object(ctx.db, bucket, key, condition)
+    return Response(status=204, headers=_delete_headers(outcome))
+
+
+async def delete_object_version(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    outcome = await meta.delete_object_version(
+        ctx.db, bucket, key, request.query["versionId"]
+    )
+    return Response(status=204, headers=_delete_headers(outcome))
+
+
+async def get_object_tagging(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    record = await meta.get_object(ctx.db, bucket, key, request.query.get("versionId"))
+    return _xml_response(
+        xml_config.render_tagging(record.tags), _new_version_headers(record.version_id)
+    )
+
+
+async def put_object_tagging(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    tags = xml_config.parse_tagging(await _read_small_body(request))
+    return Response(headers=await _set_tags(ctx, request, ObjectRef(bucket, key), tags))
+
+
+async def delete_object_tagging(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    headers = await _set_tags(ctx, request, ObjectRef(bucket, key), {})
+    return Response(status=204, headers=headers)
+
+
+async def _set_tags(
+    ctx: Context,
+    request: Request,
+    target: ObjectRef,
+    tags: Mapping[str, str],
+) -> tuple[tuple[str, str], ...]:
+    named = request.query.get("versionId")
+    if named is not None:
+        # A rule that filters on tags could then erase a version already kept.
+        access.require(request.scope, target.bucket, Level.ADMIN)
+    version_id = await meta.set_object_tags(
+        ctx.db, target.bucket, target.key, named, tags
+    )
+    return _new_version_headers(version_id)
+
+
+def _tags_in_header(request: Request) -> dict[str, str]:
+    return tagging.parse_header(request.headers.get("x-amz-tagging", ""))
+
+
+def _tags_of_a_copy(request: Request, source: ObjectRecord) -> Mapping[str, str]:
+    directive = request.headers.get("x-amz-tagging-directive", "COPY")
+    if directive == "COPY":
+        return source.tags
+    if directive == "REPLACE":
+        return _tags_in_header(request)
+    raise S3Error(errors.INVALID_ARGUMENT, f"Bad tagging directive: {directive!r}.")
+
+
+#
+# Multipart uploads
+#
+async def create_multipart_upload(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    plan = multipart.parse_checksum_plan(request.headers)
+    upload = UploadRef(secrets.token_urlsafe(_UPLOAD_ID_BYTES), bucket, key)
+    key_sent = streams.customer_key(ctx, request)
+    await meta.create_upload(
+        ctx.db,
+        upload,
+        _headers_to_store(request.headers),
+        plan,
+        UploadExtras(
+            _tags_in_header(request),
+            _public_on_write(request, bucket),
+            key_sent.check if key_sent else None,
+        ),
+    )
+    extra = (
+        (
+            ("x-amz-checksum-algorithm", plan.algorithm.upper()),
+            ("x-amz-checksum-type", plan.checksum_type),
+        )
+        if plan
+        else ()
+    )
+    return _xml_response(
+        xml.render_initiate(bucket, key, upload.upload_id),
+        (*extra, *streams.key_headers(key_sent)),
+    )
+
+
+async def upload_part(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    upload = UploadRef(request.query["uploadId"], bucket, key)
+    number = multipart.parse_part_number(request.query.get("partNumber", ""))
+    started = await meta.require_upload(ctx.db, upload)
+    key_sent = streams.customer_key(ctx, request)
+    sse.check_key(started.sse_check, key_sent)
+
+    blob, checksum = await streams.receive_blob(
+        ctx, request, started.checksum, key_sent
+    )
+    await _commit_new_part(ctx, upload, number, blob, checksum)
+    return Response(
+        headers=(*_etag_headers(blob.md5, checksum), *streams.key_headers(key_sent))
+    )
+
+
+async def upload_part_copy(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    number = multipart.parse_part_number(request.query.get("partNumber", ""))
+    # The source first: a refusal shouldn't say whether the upload exists.
+    copied = await _load_copy_source(ctx, request)
+    upload = UploadRef(request.query["uploadId"], bucket, key)
+    started = await meta.require_upload(ctx.db, upload)
+    key_sent = streams.customer_key(ctx, request)
+    sse.check_key(started.sse_check, key_sent)
+    start, length = conditions.resolve_copy_range(
+        request.headers.get("x-amz-copy-source-range"), copied.record.size
+    )
+    if length > streams.MAX_OBJECT_BYTES:
+        raise S3Error(errors.INVALID_REQUEST, "The source is too large for one part.")
+
+    blob, checksum = await streams.copy_to_new_blob(
+        ctx,
+        streams.plain_bytes(ctx, copied.record, ByteSpan(start, length), copied.key),
+        started.checksum,
+        key_sent,
+    )
+    await _commit_new_part(ctx, upload, number, blob, checksum)
+    return _xml_response(
+        xml.render_copy_part_result(blob.md5, meta.now_ms(), checksum),
+        (*_copy_source_headers(copied), *streams.key_headers(key_sent)),
+    )
+
+
+async def complete_multipart_upload(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    body = await _read_small_body(
+        request, payload.without_object_checksums(request.headers)
+    )
+    completed = await meta.complete_upload(
+        ctx.db,
+        UploadRef(request.query["uploadId"], bucket, key),
+        multipart.parse_completion(xml.parse_complete(body), request.headers),
+        conditions.parse_write_condition(request.headers),
+    )
+    return _xml_response(
+        xml.render_complete(bucket, key, completed.etag, completed.checksum),
+        _new_version_headers(completed.version_id),
+    )
+
+
+async def abort_multipart_upload(
+    ctx: Context, request: Request, bucket: str, key: str
+) -> Response:
+    await meta.abort_upload(ctx.db, UploadRef(request.query["uploadId"], bucket, key))
+    return Response(status=204)
+
+
+async def list_parts(ctx: Context, request: Request, bucket: str, key: str) -> Response:
+    query = request.query
+    upload = UploadRef(query["uploadId"], bucket, key)
+    max_parts = listing.parse_max_keys(query, "max-parts")
+    marker_text = query.get("part-number-marker", "0")
+    if not marker_text.isdecimal():
+        raise S3Error(errors.INVALID_ARGUMENT, "part-number-marker is not valid.")
+    marker = int(marker_text)
+    parts = await meta.list_parts(ctx.db, upload, marker, max_parts + 1)
+    if (await meta.require_upload(ctx.db, upload)).sse_check is not None:
+        # A client knows a part by what it sent, not by what encrypting it takes.
+        parts = [
+            replace(part, blob=replace(part.blob, size=sse.plain_size(part.blob.size)))
+            for part in parts
+        ]
+    shown = tuple(parts[:max_parts])
+    next_marker = shown[-1].number if len(parts) > max_parts and shown else None
+    return _xml_response(
+        xml.render_parts(upload, xml.PartsPage(shown, max_parts, marker, next_marker))
+    )
+
+
+async def list_multipart_uploads(
+    ctx: Context, request: Request, bucket: str
+) -> Response:
+    query = request.query
+    max_uploads = listing.parse_max_keys(query, "max-uploads")
+    # ponytail: no delimiter roll-up here. Add it if a client needs folders of
+    # in-progress uploads; the object listing's scan shows how.
+    uploads = await meta.list_uploads(
+        ctx.db,
+        bucket,
+        query.get("prefix", ""),
+        (query.get("key-marker", ""), query.get("upload-id-marker", "")),
+        max_uploads + 1,
+    )
+    page = uploads[:max_uploads]
+    next_position = (
+        (page[-1].key, page[-1].upload_id)
+        if len(uploads) > max_uploads and page
+        else None
+    )
+    return _xml_response(
+        xml.render_uploads(bucket, query, page, max_uploads, next_position)
+    )
+
+
+SERVICE_HANDLERS = {Operation.LIST_BUCKETS: list_buckets}
+BUCKET_HANDLERS = {
+    Operation.CREATE_BUCKET: create_bucket,
+    Operation.DELETE_BUCKET: delete_bucket,
+    Operation.HEAD_BUCKET: head_bucket,
+    Operation.GET_BUCKET_LOCATION: get_bucket_location,
+    Operation.GET_BUCKET_VERSIONING: get_bucket_versioning,
+    Operation.PUT_BUCKET_VERSIONING: put_bucket_versioning,
+    Operation.GET_BUCKET_LIFECYCLE: get_bucket_lifecycle,
+    Operation.PUT_BUCKET_LIFECYCLE: put_bucket_lifecycle,
+    Operation.DELETE_BUCKET_LIFECYCLE: delete_bucket_lifecycle,
+    Operation.GET_BUCKET_ACL: get_bucket_acl,
+    Operation.PUT_BUCKET_ACL: put_bucket_acl,
+    Operation.GET_BUCKET_CORS: get_bucket_cors,
+    Operation.PUT_BUCKET_CORS: put_bucket_cors,
+    Operation.DELETE_BUCKET_CORS: delete_bucket_cors,
+    Operation.LIST_OBJECTS: list_objects_v1,
+    Operation.LIST_OBJECTS_V2: list_objects_v2,
+    Operation.LIST_MULTIPART_UPLOADS: list_multipart_uploads,
+    Operation.LIST_OBJECT_VERSIONS: list_object_versions,
+    Operation.DELETE_OBJECTS: delete_objects,
+    Operation.POST_OBJECT: post_object,
+}
+OBJECT_HANDLERS = {
+    Operation.PUT_OBJECT: put_object,
+    Operation.COPY_OBJECT: copy_object,
+    Operation.GET_OBJECT: get_object,
+    Operation.HEAD_OBJECT: head_object,
+    Operation.DELETE_OBJECT: delete_object,
+    Operation.GET_OBJECT_ACL: get_object_acl,
+    Operation.PUT_OBJECT_ACL: put_object_acl,
+    Operation.GET_OBJECT_TAGGING: get_object_tagging,
+    Operation.PUT_OBJECT_TAGGING: put_object_tagging,
+    Operation.DELETE_OBJECT_TAGGING: delete_object_tagging,
+    Operation.DELETE_OBJECT_VERSION: delete_object_version,
+    Operation.CREATE_MULTIPART_UPLOAD: create_multipart_upload,
+    Operation.UPLOAD_PART: upload_part,
+    Operation.UPLOAD_PART_COPY: upload_part_copy,
+    Operation.COMPLETE_MULTIPART_UPLOAD: complete_multipart_upload,
+    Operation.ABORT_MULTIPART_UPLOAD: abort_multipart_upload,
+    Operation.LIST_PARTS: list_parts,
+}
+
+
+#
+# Shared pieces
+#
+def _list_query(query: Mapping[str, str], after: str) -> listing.ListQuery:
+    return listing.ListQuery(
+        query.get("prefix", ""),
+        query.get("delimiter", ""),
+        after,
+        listing.parse_max_keys(query),
+    )
+
+
+async def _load_copy_source(ctx: Context, request: Request) -> _CopySource:
+    """Find what a copy reads, if the key may read it and its conditions hold."""
+    bucket, key, version_id = _parse_copy_source(request.headers["x-amz-copy-source"])
+    access.require(request.scope, bucket, Level.READ)
+    record = await meta.get_object(ctx.db, bucket, key, version_id)
+    source_key = streams.customer_key(ctx, request, sse.COPY_SOURCE_PREFIX)
+    sse.check_key(record.sse_check, source_key)
+    if conditions.read_is_not_modified(
+        request.headers, record.etag, record.modified_at, prefix="x-amz-copy-source-"
+    ):
+        raise S3Error(errors.PRECONDITION_FAILED, "The source was not modified.")
+    return _CopySource(bucket, version_id, record, source_key)
+
+
+async def _commit_new_part(
+    ctx: Context,
+    upload: UploadRef,
+    number: int,
+    blob: Blob,
+    checksum: Checksum | None,
+) -> None:
+    """Commit, and remove the blob if the commit refuses it: no one can refer to it."""
+    try:
+        await meta.commit_part(ctx.db, upload, number, blob, checksum)
+    except S3Error:
+        ctx.blobs.delete(blob.blob_id, blob.volume_ids)
+        raise
+
+
+async def _read_small_body(
+    request: Request, headers: Mapping[str, str] | None = None
+) -> bytes:
+    """Read a bounded XML body, holding it to the same promises as any upload."""
+    spec = payload.parse_spec(request.headers if headers is None else headers)
+    decoder = payload.new_decoder(spec, request.stream_seed)
+    hashers = payload.new_hashers(spec)
+    body = bytearray()
+    async with aclosing(streams.decoded_body(request, decoder)) as chunks:
+        async for chunk in chunks:
+            body += chunk
+            if len(body) > MAX_XML_BYTES:
+                raise S3Error(errors.MALFORMED_XML, "The XML body is too large.")
+    complete_body = bytes(body)
+    for hasher in hashers.values():
+        hasher.update(complete_body)
+    digests = {name: hasher.digest() for name, hasher in hashers.items()}
+    payload.verify(spec, digests, len(complete_body), decoder.finish())
+    return complete_body
+
+
+async def _commit_new_blob(
+    ctx: Context,
+    bucket: str,
+    record: ObjectRecord,
+    condition: conditions.WriteCondition,
+) -> str | None:
+    """Commit, and remove the blob if the commit refuses it: no one can refer to it."""
+    try:
+        return await meta.commit_object(ctx.db, bucket, record, condition)
+    except S3Error:
+        for blob in record.blobs:
+            ctx.blobs.delete(blob.blob_id, blob.volume_ids)
+        raise
+
+
+def _refuse_unless_reachable(
+    ctx: Context, record: ObjectRecord, start: int, length: int
+) -> None:
+    """Say so while a client can still retry: after the headers, a read can only break.
+
+    A worker can be without its volumes for moments, as when it starts on a full disk.
+    """
+    blobs = (
+        (piece.blob for piece in conditions.slice_blobs(record.blobs, start, length))
+        if record.sse_check is None
+        else record.blobs
+    )
+    if not all(map(ctx.blobs.can_read, blobs)):
+        raise S3Error(errors.SERVICE_UNAVAILABLE)
+
+
+def _object_response(
+    ctx: Context,
+    request: Request,
+    record: ObjectRecord,
+    *,
+    include_body: bool,
+) -> Response:
+    headers = request.headers
+    key_sent = streams.customer_key(ctx, request)
+    sse.check_key(record.sse_check, key_sent)
+    validators = (
+        ("etag", f'"{record.etag}"'),
+        ("last-modified", xml.http_date(record.modified_at)),
+        *(
+            ()
+            if record.version_id == NULL_VERSION_ID
+            else _version_headers(record.version_id)
+        ),
+    )
+    if conditions.read_is_not_modified(headers, record.etag, record.modified_at):
+        return Response(status=304, headers=validators)
+
+    byte_range = conditions.resolve_range(headers.get("range"), record.size)
+    start, length = byte_range or (0, record.size)
+    response_headers = [
+        *validators,
+        *_stored_response_headers(record, request.query),
+        ("accept-ranges", "bytes"),
+        ("content-length", str(length)),
+    ]
+    if record.tags:
+        response_headers.append(("x-amz-tagging-count", str(len(record.tags))))
+    response_headers.extend(streams.key_headers(key_sent))
+    if byte_range is not None:
+        response_headers.append((
+            "content-range",
+            f"bytes {start}-{start + length - 1}/{record.size}",
+        ))
+    # A checksum describes the whole object, so a client would reject it on a range.
+    wants_checksum = headers.get("x-amz-checksum-mode", "").upper() == "ENABLED"
+    if wants_checksum and record.checksum is not None and byte_range is None:
+        response_headers.extend((
+            _checksum_header(record.checksum),
+            ("x-amz-checksum-type", record.checksum.checksum_type),
+        ))
+
+    body: bytes | AsyncGenerator[bytes] = b""
+    if include_body:
+        _refuse_unless_reachable(ctx, record, start, length)
+        body = streams.plain_bytes(ctx, record, ByteSpan(start, length), key_sent)
+    status = 206 if byte_range is not None else 200
+    return Response(status, tuple(response_headers), body)
+
+
+def _stored_response_headers(
+    record: ObjectRecord, query: Mapping[str, str]
+) -> list[tuple[str, str]]:
+    merged = dict(record.headers)
+    for parameter, header in _RESPONSE_OVERRIDES.items():
+        if parameter in query:
+            if not _VALID_HEADER_VALUE.fullmatch(query[parameter]):
+                raise S3Error(errors.INVALID_ARGUMENT, f"{parameter} is not valid.")
+            merged[header] = query[parameter]
+    return list(merged.items())
+
+
+def _headers_to_store(headers: Mapping[str, str]) -> dict[str, str]:
+    """Pick the headers that belong to the object, and enforce the metadata limit."""
+    stored = {name: headers[name] for name in _STORED_HEADERS if name in headers}
+    stored.setdefault("content-type", _DEFAULT_CONTENT_TYPE)
+    encoding = ", ".join(
+        token.strip()
+        for token in headers.get("content-encoding", "").split(",")
+        if token.strip() and token.strip() != "aws-chunked"
+    )
+    if encoding:
+        stored["content-encoding"] = encoding
+
+    user_metadata = {
+        name: value for name, value in headers.items() if name.startswith(_META_PREFIX)
+    }
+    metadata_size = sum(
+        len(name) - len(_META_PREFIX) + len(value)
+        for name, value in user_metadata.items()
+    )
+    if metadata_size > MAX_METADATA_BYTES:
+        raise S3Error(errors.METADATA_TOO_LARGE)
+    return stored | user_metadata
+
+
+def _parse_copy_source(header: str) -> tuple[str, str, str | None]:
+    """Return the bucket, key and, if one is named, version of a copy's source."""
+    path, _, raw_query = header.partition("?")
+    query = routing.parse_query(raw_query.encode("latin-1"))
+    if query.keys() - {"versionId"}:
+        raise S3Error(errors.INVALID_ARGUMENT, "x-amz-copy-source is not valid.")
+    raw_bucket, separator, raw_key = path.removeprefix("/").partition("/")
+    if not separator or not raw_key:
+        raise S3Error(errors.INVALID_ARGUMENT, "x-amz-copy-source is not valid.")
+    return (
+        routing.parse_raw_bucket(raw_bucket.encode()),
+        routing.parse_key(raw_key.encode()),
+        query.get("versionId"),
+    )
+
+
+def _copy_source_headers(copied: _CopySource) -> tuple[tuple[str, str], ...]:
+    version_id = copied.record.version_id
+    unversioned = version_id == NULL_VERSION_ID and copied.version_id is None
+    return () if unversioned else (("x-amz-copy-source-version-id", version_id),)
+
+
+def _version_headers(version_id: str | None) -> tuple[tuple[str, str], ...]:
+    return () if version_id is None else (("x-amz-version-id", version_id),)
+
+
+def _new_version_headers(version_id: str | None) -> tuple[tuple[str, str], ...]:
+    """What a write reports. A suspended bucket's "null" isn't worth naming."""
+    return () if version_id == NULL_VERSION_ID else _version_headers(version_id)
+
+
+def _delete_headers(outcome: DeleteOutcome) -> tuple[tuple[str, str], ...]:
+    marker = (("x-amz-delete-marker", "true"),) if outcome.is_delete_marker else ()
+    return (*marker, *_version_headers(outcome.version_id))
+
+
+def _etag_headers(etag: str, checksum: Checksum | None) -> tuple[tuple[str, str], ...]:
+    extra = (_checksum_header(checksum),) if checksum else ()
+    return (("etag", f'"{etag}"'), *extra)
+
+
+def _checksum_header(checksum: Checksum) -> tuple[str, str]:
+    return (f"x-amz-checksum-{checksum.algorithm}", checksum.value)
+
+
+def _xml_response(
+    body: bytes, extra_headers: tuple[tuple[str, str], ...] = ()
+) -> Response:
+    return Response(
+        headers=(("content-type", _XML_CONTENT_TYPE), *extra_headers), body=body
+    )