leblob 0.4.0.dev1__py3-none-any.whl

leblob/s3/chunked.py

@@ -0,0 +1,175 @@
+"""Incremental decoder for the aws-chunked upload framing.
+
+Bytes arrive in arbitrary pieces from the network, so the decoder is a state
+machine that never assumes a chunk header or trailer line arrives whole.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import re
+from enum import Enum, auto
+from typing import TYPE_CHECKING
+
+from leblob.s3 import errors, sigv4
+from leblob.s3.errors import S3Error
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    from leblob.s3.sigv4 import StreamSeed
+
+_MAX_LINE_BYTES = 8192
+_CRLF = b"\r\n"
+_CHUNK_HEADER = re.compile(rb"([0-9a-fA-F]{1,16})(?:;chunk-signature=([0-9a-f]{64}))?")
+_TRAILER_SIGNATURE = "x-amz-trailer-signature"
+
+
+class _State(Enum):
+    CHUNK_HEADER = auto()
+    CHUNK_DATA = auto()
+    CHUNK_END = auto()
+    TRAILER = auto()
+    DONE = auto()
+
+
+class PlainDecoder:
+    """A body with no framing: its bytes are the payload."""
+
+    @staticmethod
+    def feed(data: bytes) -> bytes:
+        return data
+
+    @staticmethod
+    def finish() -> Mapping[str, str]:
+        return {}
+
+
+class ChunkedDecoder:
+    """Strip aws-chunked framing, verifying chunk signatures when there is a seed."""
+
+    def __init__(
+        self, seed: StreamSeed | None, *, signed_trailer: bool = False
+    ) -> None:
+        self._seed = seed
+        self._signed_trailer = signed_trailer
+        self._previous_signature = seed.signature if seed else ""
+        self._state = _State.CHUNK_HEADER
+        self._pending = b""
+        self._remaining = 0
+        self._chunk_signature = ""
+        self._chunk_hash = hashlib.sha256()
+        self._trailers: dict[str, str] = {}
+
+    def feed(self, data: bytes) -> bytes:
+        """Consume network bytes and return the payload bytes they contain."""
+        buffer = self._pending + data if self._pending else data
+        self._pending = b""
+        output: list[bytes] = []
+        position = 0
+        while position < len(buffer) and self._state is not _State.DONE:
+            advanced = self._step(buffer, position, output)
+            if advanced is None:
+                self._pending = buffer[position:]
+                self._check_pending_size()
+                break
+            position = advanced
+        return b"".join(output)
+
+    def finish(self) -> Mapping[str, str]:
+        """Return the trailers, or raise if the body stopped early."""
+        if self._state is not _State.DONE:
+            raise S3Error(errors.INCOMPLETE_BODY, "The aws-chunked body is truncated.")
+        return self._trailers
+
+    def _step(self, buffer: bytes, position: int, output: list[bytes]) -> int | None:
+        """Run one state; return the new position, or None if more bytes are needed."""
+        if self._state is _State.CHUNK_DATA:
+            return self._read_data(buffer, position, output)
+        if self._state is _State.CHUNK_END:
+            return self._read_chunk_end(buffer, position)
+
+        end = buffer.find(_CRLF, position)
+        if end < 0:
+            return None
+        line = buffer[position:end]
+        if self._state is _State.CHUNK_HEADER:
+            self._read_chunk_header(line)
+        else:
+            self._read_trailer_line(line)
+        return end + len(_CRLF)
+
+    def _read_chunk_header(self, line: bytes) -> None:
+        match = _CHUNK_HEADER.fullmatch(line)
+        if match is None:
+            raise S3Error(errors.INCOMPLETE_BODY, "Malformed aws-chunked chunk header.")
+        self._remaining = int(match[1], 16)
+        if self._seed is not None and match[2] is None:
+            raise S3Error(errors.SIGNATURE_MISMATCH, "A chunk signature is missing.")
+        self._chunk_signature = match[2].decode() if match[2] else ""
+        self._chunk_hash = hashlib.sha256()
+
+        if self._remaining == 0:
+            self._verify_chunk()
+            self._state = _State.TRAILER
+        else:
+            self._state = _State.CHUNK_DATA
+
+    def _read_data(self, buffer: bytes, position: int, output: list[bytes]) -> int:
+        taken = buffer[position : position + self._remaining]
+        output.append(taken)
+        if self._seed is not None:
+            self._chunk_hash.update(taken)
+        self._remaining -= len(taken)
+        if self._remaining == 0:
+            self._verify_chunk()
+            self._state = _State.CHUNK_END
+        return position + len(taken)
+
+    def _read_chunk_end(self, buffer: bytes, position: int) -> int | None:
+        if len(buffer) - position < len(_CRLF):
+            return None
+        if buffer[position : position + len(_CRLF)] != _CRLF:
+            raise S3Error(errors.INCOMPLETE_BODY, "A chunk is longer than declared.")
+        self._state = _State.CHUNK_HEADER
+        return position + len(_CRLF)
+
+    def _read_trailer_line(self, line: bytes) -> None:
+        if not line:
+            self._verify_trailer_signature()
+            self._state = _State.DONE
+            return
+        name, separator, value = line.decode("latin-1").partition(":")
+        if not separator:
+            raise S3Error(errors.MALFORMED_TRAILER)
+        self._trailers[name.strip().lower()] = value.strip()
+
+    def _verify_chunk(self) -> None:
+        if self._seed is None:
+            return
+        expected = sigv4.chunk_signature(
+            self._seed, self._previous_signature, self._chunk_hash.hexdigest()
+        )
+        if not hmac.compare_digest(expected, self._chunk_signature):
+            raise S3Error(errors.SIGNATURE_MISMATCH, "A chunk signature is wrong.")
+        self._previous_signature = expected
+
+    def _verify_trailer_signature(self) -> None:
+        claimed = self._trailers.pop(_TRAILER_SIGNATURE, None)
+        if self._seed is None or not self._signed_trailer:
+            return
+        if claimed is None or not sigv4.is_signature(claimed):
+            raise S3Error(
+                errors.SIGNATURE_MISMATCH, "The trailer signature is missing."
+            )
+        trailer = "".join(f"{name}:{value}\n" for name, value in self._trailers.items())
+        expected = sigv4.trailer_signature(
+            self._seed, self._previous_signature, trailer.encode("latin-1")
+        )
+        if not hmac.compare_digest(expected, claimed):
+            raise S3Error(errors.SIGNATURE_MISMATCH, "The trailer signature is wrong.")
+
+    def _check_pending_size(self) -> None:
+        if len(self._pending) > _MAX_LINE_BYTES:
+            raise S3Error(errors.INCOMPLETE_BODY, "An aws-chunked line is too long.")

leblob/s3/conditions.py

@@ -0,0 +1,156 @@
+"""Conditional requests and byte ranges."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from email.utils import parsedate_to_datetime
+from typing import TYPE_CHECKING
+
+from leblob.model import BlobSlice
+from leblob.s3 import errors
+from leblob.s3.errors import S3Error
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Mapping
+
+    from leblob.model import Blob
+
+_RANGE = re.compile(r"bytes=(\d*)-(\d*)")
+_COPY_RANGE = re.compile(r"bytes=([0-9]+)-([0-9]+)")
+
+
+@dataclass(frozen=True, slots=True)
+class WriteCondition:
+    """A precondition on the current state of the key being written."""
+
+    if_match: str | None = None
+    if_none_match: str | None = None
+
+
+def parse_write_condition(headers: Mapping[str, str]) -> WriteCondition:
+    return WriteCondition(
+        _strip_etag(headers.get("if-match")), _strip_etag(headers.get("if-none-match"))
+    )
+
+
+def check_write_condition(condition: WriteCondition, current_etag: str | None) -> None:
+    """Raise unless a write is allowed given the key's current ETag."""
+    if current_etag is not None and condition.if_none_match in {"*", current_etag}:
+        raise S3Error(errors.PRECONDITION_FAILED, "If-None-Match did not hold.")
+    if condition.if_match is None:
+        return
+    if current_etag is None:
+        raise S3Error(errors.NO_SUCH_KEY)
+    if condition.if_match not in {"*", current_etag}:
+        raise S3Error(errors.PRECONDITION_FAILED, "If-Match did not hold.")
+
+
+def read_is_not_modified(
+    headers: Mapping[str, str],
+    etag: str,
+    modified_at_ms: int,
+    prefix: str = "",
+) -> bool:
+    """Evaluate read preconditions as RFC 9110 orders them.
+
+    Raise PreconditionFailed, or return True if the answer should be 304.
+    """
+    modified_seconds = modified_at_ms // 1000
+    if_match = headers.get(f"{prefix}if-match")
+    if if_match is not None:
+        if not _etag_matches(if_match, etag):
+            raise S3Error(errors.PRECONDITION_FAILED, "If-Match did not hold.")
+    else:
+        limit = _parse_http_date(headers.get(f"{prefix}if-unmodified-since"))
+        if limit is not None and modified_seconds > limit:
+            raise S3Error(
+                errors.PRECONDITION_FAILED, "If-Unmodified-Since did not hold."
+            )
+
+    if_none_match = headers.get(f"{prefix}if-none-match")
+    if if_none_match is not None:
+        return _etag_matches(if_none_match, etag)
+    since = _parse_http_date(headers.get(f"{prefix}if-modified-since"))
+    return since is not None and modified_seconds <= since
+
+
+def resolve_range(header: str | None, size: int) -> tuple[int, int] | None:
+    """Return (start, length), or None to serve the whole object.
+
+    Syntax that isn't a single byte range is ignored, as RFC 9110 requires.
+    """
+    match = _RANGE.fullmatch(header.strip()) if header else None
+    if match is None:
+        return None
+    first, last = match.groups()
+    if not first and not last:
+        return None
+    if first:
+        start = int(first)
+        end = min(int(last), size - 1) if last else size - 1
+    else:
+        start = max(size - int(last), 0)
+        end = size - 1
+    if start > end or start >= size or (first and last and int(last) < int(first)):
+        raise S3Error(
+            errors.INVALID_RANGE, headers=(("content-range", f"bytes */{size}"),)
+        )
+    return start, end - start + 1
+
+
+def resolve_copy_range(header: str | None, size: int) -> tuple[int, int]:
+    """Return (start, length) of what a part copies from its source.
+
+    Stricter than a read: the source of a part has to be exact, since a shorter part
+    would silently make a wrong object. No range means all of it.
+    """
+    if header is None:
+        return 0, size
+    match = _COPY_RANGE.fullmatch(header)
+    if match is None or int(match[2]) < int(match[1]):
+        raise S3Error(
+            errors.INVALID_ARGUMENT,
+            "x-amz-copy-source-range must be of the form bytes=first-last.",
+        )
+    first, last = int(match[1]), int(match[2])
+    if last >= size:
+        raise S3Error(errors.INVALID_RANGE, f"The source has only {size} bytes.")
+    return first, last - first + 1
+
+
+def slice_blobs(blobs: Iterable[Blob], start: int, length: int) -> list[BlobSlice]:
+    """Translate a byte range of an object into ranges of its blobs."""
+    slices = []
+    position = 0
+    remaining = length
+    for blob in blobs:
+        if remaining == 0:
+            break
+        if start < position + blob.size:
+            offset = max(start - position, 0)
+            taken = min(blob.size - offset, remaining)
+            slices.append(BlobSlice(blob, offset, taken))
+            remaining -= taken
+        position += blob.size
+    return slices
+
+
+def _strip_etag(value: str | None) -> str | None:
+    return value.strip().strip('"') if value else None
+
+
+def _etag_matches(header: str, etag: str) -> bool:
+    candidates = {
+        item.strip().removeprefix("W/").strip('"') for item in header.split(",")
+    }
+    return "*" in candidates or etag in candidates
+
+
+def _parse_http_date(value: str | None) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(parsedate_to_datetime(value).timestamp())
+    except ValueError:
+        return None

leblob/s3/cors.py

@@ -0,0 +1,80 @@
+"""Which browser requests a bucket's CORS rules allow, and what to tell the browser."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from leblob.model import CorsRule
+
+ALLOWED_METHODS = frozenset({"DELETE", "GET", "HEAD", "POST", "PUT"})
+_WILDCARD = "*"
+VARY = (("vary", "Origin"),)
+
+
+def find_rule(
+    rules: Sequence[CorsRule],
+    origin: str,
+    method: str,
+    headers: Sequence[str] = (),
+) -> CorsRule | None:
+    """The first rule that allows all of a request, if any."""
+    for rule in rules:
+        if (
+            method in rule.methods
+            and any(_matches(allowed, origin) for allowed in rule.origins)
+            and all(_header_is_allowed(rule, header) for header in headers)
+        ):
+            return rule
+    return None
+
+
+def split_header_names(value: str) -> list[str]:
+    return [name.strip() for name in value.split(",") if name.strip()]
+
+
+def response_headers(rule: CorsRule, origin: str) -> tuple[tuple[str, str], ...]:
+    """What a browser needs to see in any answer the rule allows."""
+    allowed_origin = _WILDCARD if _WILDCARD in rule.origins else origin
+    expose = (
+        (("access-control-expose-headers", ", ".join(rule.expose)),)
+        if rule.expose
+        else ()
+    )
+    return (
+        ("access-control-allow-origin", allowed_origin),
+        ("access-control-allow-methods", ", ".join(rule.methods)),
+        *VARY,
+        *expose,
+    )
+
+
+def preflight_headers(
+    rule: CorsRule, origin: str, headers: Sequence[str]
+) -> tuple[tuple[str, str], ...]:
+    """What a browser needs to go on to send the request it asked about."""
+    allowed = (("access-control-allow-headers", ", ".join(headers)),) if headers else ()
+    max_age = (
+        () if rule.max_age is None else (("access-control-max-age", str(rule.max_age)),)
+    )
+    return (*response_headers(rule, origin), *allowed, *max_age)
+
+
+def _header_is_allowed(rule: CorsRule, header: str) -> bool:
+    return any(
+        _matches(allowed.lower(), header.lower()) for allowed in rule.allowed_headers
+    )
+
+
+def _matches(pattern: str, value: str) -> bool:
+    """Compare with a pattern holding one wildcard at most, as parsing has ensured."""
+    before, wildcard, after = pattern.partition(_WILDCARD)
+    if not wildcard:
+        return pattern == value
+    return (
+        len(value) >= len(before) + len(after)
+        and value.startswith(before)
+        and value.endswith(after)
+    )

leblob/s3/errors.py

@@ -0,0 +1,144 @@
+"""S3 error codes, and the exception that carries one to the HTTP boundary."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class ErrorCode:
+    code: str
+    status: int
+    message: str
+
+
+ACCESS_DENIED = ErrorCode("AccessDenied", 403, "Access Denied.")
+AUTH_HEADER_MALFORMED = ErrorCode(
+    "AuthorizationHeaderMalformed", 400, "The authorization header is malformed."
+)
+AUTH_QUERY_ERROR = ErrorCode(
+    "AuthorizationQueryParametersError",
+    400,
+    "The presigned URL parameters are malformed.",
+)
+BAD_DIGEST = ErrorCode(
+    "BadDigest", 400, "The checksum you specified did not match what we received."
+)
+BUCKET_ALREADY_OWNED = ErrorCode(
+    "BucketAlreadyOwnedByYou", 409, "You already own this bucket."
+)
+BUCKET_NOT_EMPTY = ErrorCode(
+    "BucketNotEmpty", 409, "The bucket you tried to delete is not empty."
+)
+CONTENT_SHA256_MISMATCH = ErrorCode(
+    "XAmzContentSHA256Mismatch",
+    400,
+    "The body does not match the declared x-amz-content-sha256.",
+)
+ENTITY_TOO_LARGE = ErrorCode(
+    "EntityTooLarge", 400, "Your upload exceeds the maximum allowed size."
+)
+ENTITY_TOO_SMALL = ErrorCode(
+    "EntityTooSmall", 400, "A part other than the last is below the minimum size."
+)
+INCOMPLETE_BODY = ErrorCode(
+    "IncompleteBody", 400, "The body does not have the declared length."
+)
+INTERNAL_ERROR = ErrorCode(
+    "InternalError", 500, "We encountered an internal error. Please try again."
+)
+ACCESS_FORBIDDEN = ErrorCode(
+    "AccessForbidden", 403, "CORSResponse: This CORS request is not allowed."
+)
+SERVICE_UNAVAILABLE = ErrorCode(
+    "ServiceUnavailable", 503, "Please try again: the data is not reachable just now."
+)
+INVALID_ACCESS_KEY = ErrorCode(
+    "InvalidAccessKeyId", 403, "The access key ID does not exist."
+)
+INVALID_ARGUMENT = ErrorCode("InvalidArgument", 400, "Invalid argument.")
+INVALID_BUCKET_NAME = ErrorCode(
+    "InvalidBucketName", 400, "The specified bucket name is not valid."
+)
+INVALID_DIGEST = ErrorCode(
+    "InvalidDigest", 400, "The checksum you specified is not valid."
+)
+INVALID_PART = ErrorCode(
+    "InvalidPart", 400, "A listed part is missing or its ETag does not match."
+)
+INVALID_PART_ORDER = ErrorCode(
+    "InvalidPartOrder", 400, "The list of parts is not in ascending order."
+)
+INVALID_RANGE = ErrorCode(
+    "InvalidRange", 416, "The requested range is not satisfiable."
+)
+INVALID_POLICY = ErrorCode(
+    "InvalidPolicyDocument", 400, "The content of the form's policy is not valid."
+)
+INVALID_TAG = ErrorCode("InvalidTag", 400, "The tag provided was not valid.")
+INVALID_REQUEST = ErrorCode("InvalidRequest", 400, "The request is not valid.")
+KEY_TOO_LONG = ErrorCode(
+    "KeyTooLongError", 400, "Your key is longer than the 1024 bytes allowed."
+)
+MALFORMED_POST = ErrorCode(
+    "MalformedPOSTRequest", 400, "The body of your POST request is not valid."
+)
+MAX_POST_PRE_DATA = ErrorCode(
+    "MaxPostPreDataLengthExceeded",
+    400,
+    "Your POST request fields preceding the upload file were too large.",
+)
+MALFORMED_TRAILER = ErrorCode(
+    "MalformedTrailerError", 400, "The trailing checksum is missing or malformed."
+)
+MALFORMED_XML = ErrorCode("MalformedXML", 400, "The XML you provided is not valid.")
+METADATA_TOO_LARGE = ErrorCode(
+    "MetadataTooLarge", 400, "Your metadata exceeds the 2 KB limit."
+)
+METHOD_NOT_ALLOWED = ErrorCode(
+    "MethodNotAllowed", 405, "The method is not allowed for this resource."
+)
+NO_SUCH_BUCKET = ErrorCode("NoSuchBucket", 404, "The specified bucket does not exist.")
+NO_SUCH_KEY = ErrorCode("NoSuchKey", 404, "The specified key does not exist.")
+NO_SUCH_VERSION = ErrorCode(
+    "NoSuchVersion", 404, "The specified version does not exist."
+)
+NO_SUCH_CORS = ErrorCode(
+    "NoSuchCORSConfiguration", 404, "The CORS configuration does not exist."
+)
+NO_SUCH_LIFECYCLE = ErrorCode(
+    "NoSuchLifecycleConfiguration", 404, "The lifecycle configuration does not exist."
+)
+NO_SUCH_UPLOAD = ErrorCode(
+    "NoSuchUpload", 404, "The specified multipart upload does not exist."
+)
+NOT_IMPLEMENTED = ErrorCode("NotImplemented", 501, "This feature is not implemented.")
+PRECONDITION_FAILED = ErrorCode(
+    "PreconditionFailed", 412, "A condition you specified did not hold."
+)
+TIME_TOO_SKEWED = ErrorCode(
+    "RequestTimeTooSkewed",
+    403,
+    "The difference between the request time and the server time is too large.",
+)
+SIGNATURE_MISMATCH = ErrorCode(
+    "SignatureDoesNotMatch",
+    403,
+    "The request signature we calculated does not match the signature you provided.",
+)
+
+
+class S3Error(Exception):
+    """A failure that S3 clients understand; rendered once, at the HTTP boundary."""
+
+    def __init__(
+        self,
+        error: ErrorCode,
+        message: str | None = None,
+        *,
+        headers: tuple[tuple[str, str], ...] = (),
+    ) -> None:
+        self.error = error
+        self.message = message or error.message
+        self.headers = headers
+        super().__init__(f"{error.code}: {self.message}")

leblob/s3/lifecycle.py

@@ -0,0 +1,119 @@
+"""What lifecycle rules say to do. Pure: `meta.expire_batch` carries it out."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from leblob.model import KeyVerdict
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from leblob.model import LifecycleRule, VersionSummary
+
+
+@dataclass(frozen=True, slots=True)
+class Clock:
+    """The time now, and how long a day lasts, which tests make short."""
+
+    now: int
+    day_ms: int
+
+    def has_passed(self, since: int, days: int) -> bool:
+        return since + days * self.day_ms <= self.now
+
+
+def judge_key(
+    rules: Sequence[LifecycleRule], versions: Sequence[VersionSummary], clock: Clock
+) -> KeyVerdict:
+    """Decide what happens to one key, given all its versions, newest first."""
+    latest, *older = versions
+    applying = [rule for rule in rules if _applies_to_key(rule, latest.key)]
+    expire_current = not latest.is_delete_marker and any(
+        _current_has_expired(rule, latest, clock) for rule in applying
+    )
+    erase = [
+        version.version_id
+        for position, (version, successor) in enumerate(
+            zip(older, versions, strict=False)
+        )
+        if any(
+            _noncurrent_has_expired(rule, version, successor, position, clock)
+            for rule in applying
+        )
+    ]
+    if (
+        latest.is_delete_marker
+        and not older
+        and any(_lone_marker_has_expired(rule, latest, clock) for rule in applying)
+    ):
+        erase.append(latest.version_id)
+    return KeyVerdict(expire_current, tuple(erase))
+
+
+def upload_is_stale(
+    rules: Sequence[LifecycleRule], key: str, created_at: int, clock: Clock
+) -> bool:
+    return any(
+        rule.actions.abort_upload_days is not None
+        and clock.has_passed(created_at, rule.actions.abort_upload_days)
+        for rule in rules
+        if _applies_to_key(rule, key)
+    )
+
+
+def _applies_to_key(rule: LifecycleRule, key: str) -> bool:
+    return rule.enabled and key.startswith(rule.scope.prefix or "")
+
+
+def _applies_to_version(rule: LifecycleRule, version: VersionSummary) -> bool:
+    scope = rule.scope
+    return (
+        (scope.larger_than is None or version.size > scope.larger_than)
+        and (scope.smaller_than is None or version.size < scope.smaller_than)
+        and all(version.tags.get(key) == value for key, value in scope.tags)
+    )
+
+
+def _current_has_expired(
+    rule: LifecycleRule, current: VersionSummary, clock: Clock
+) -> bool:
+    actions = rule.actions
+    if not _applies_to_version(rule, current):
+        return False
+    if actions.expire_at is not None:
+        return actions.expire_at <= clock.now
+    return actions.expire_days is not None and clock.has_passed(
+        current.modified_at, actions.expire_days
+    )
+
+
+def _lone_marker_has_expired(
+    rule: LifecycleRule, marker: VersionSummary, clock: Clock
+) -> bool:
+    """A rule on current objects clears up after them too, as AWS documents."""
+    actions = rule.actions
+    if not _applies_to_version(rule, marker):
+        return False
+    return actions.expire_lone_markers or (
+        actions.expire_days is not None
+        and clock.has_passed(marker.modified_at, actions.expire_days)
+    )
+
+
+def _noncurrent_has_expired(
+    rule: LifecycleRule,
+    version: VersionSummary,
+    successor: VersionSummary,
+    position: int,
+    clock: Clock,
+) -> bool:
+    """A version's age counts from when a newer one replaced it, not its creation."""
+    actions = rule.actions
+    return (
+        actions.noncurrent_days is not None
+        and position >= actions.keep_noncurrent
+        and _applies_to_version(rule, version)
+        and clock.has_passed(successor.modified_at, actions.noncurrent_days)
+    )