encore-dev 2.0.0a7__py3-none-any.whl

encore/shutdown/__init__.py

@@ -0,0 +1,164 @@
+"""Start Encore shutdown and observe its progress."""
+
+from enum import Enum
+
+from ..internal.runtime import EncoreError, runtime, _native
+
+
+class ShutdownError(EncoreError):
+    """Encore cleanup failed or shutdown progress could not be observed."""
+
+
+class ShutdownPhase(Enum):
+    """A phase of the Encore runtime's shutdown process.
+
+    Attributes:
+        NOT_STARTED: Shutdown has not started.
+        STARTED: Pub/Sub intake is stopping and active work is draining.
+            The host remains responsible for its HTTP server.
+        CLEANUP: Encore is cleaning up resources and flushing telemetry.
+        COMPLETED: Cleanup has finished, including if it failed. Inspect
+            the result or exception to determine the outcome.
+    """
+
+    NOT_STARTED = "NOT_STARTED"
+    STARTED = "started"
+    CLEANUP = "cleanup"
+    COMPLETED = "completed"
+
+    @classmethod
+    def _from_native(cls, native: _native.ShutdownPhase) -> "ShutdownPhase":
+        if native == _native.ShutdownPhase.NotStarted:
+            return cls.NOT_STARTED
+        if native == _native.ShutdownPhase.Started:
+            return cls.STARTED
+        if native == _native.ShutdownPhase.Cleanup:
+            return cls.CLEANUP
+        if native == _native.ShutdownPhase.Completed:
+            return cls.COMPLETED
+        raise ValueError(f"Unknown shutdown phase: {native!r}")
+
+
+class ShutdownResult(Enum):
+    """The outcome of completed shutdown.
+
+    Native cleanup failures raise ShutdownError.
+
+    Attributes:
+        SUCCESS: Cleanup finished before the deadline.
+        TIMEOUT: The deadline expired before cleanup finished.
+        FAILED: A failure value; native failures raise ShutdownError instead.
+    """
+
+    SUCCESS = "success"
+    TIMEOUT = "timeout"
+    FAILED = "failed"
+
+    def code(self) -> int:
+        """Return 0 for success or 1 for any other outcome."""
+        return 0 if self is ShutdownResult.SUCCESS else 1
+
+    @classmethod
+    def _from_native(cls, native: _native.ShutdownResult) -> "ShutdownResult":
+        if native == _native.ShutdownResult.Success:
+            return cls.SUCCESS
+        if native == _native.ShutdownResult.Timeout:
+            return cls.TIMEOUT
+        if native == _native.ShutdownResult.Failed:
+            raise ShutdownError("Encore resource cleanup failed")
+
+        raise ValueError(f"Unknown shutdown result: {native!r}")
+
+
+def begin(cooperative: bool = False) -> None:
+    """Start shutdown and stop accepting new Pub/Sub messages.
+
+    All callers share one shutdown process. Calls are safe concurrently and
+    idempotent: the first call chooses the mode, and later calls do not restart
+    shutdown or reset its deadline.
+
+    Args:
+        cooperative: Whether to wait for mark_application_drained() before
+            entering CLEANUP, unless the shutdown deadline expires first.
+    """
+    runtime().begin_shutdown(cooperative=cooperative)
+
+
+async def completed() -> ShutdownResult:
+    """Wait for actual cleanup completion, even after a timeout.
+
+    Call begin() first. Cancelling this wait does not cancel shutdown.
+
+    Returns:
+        The shared shutdown outcome after cleanup has finished. A timeout
+        remains a timeout even if cleanup later finishes successfully.
+
+    Raises:
+        ShutdownError: Shutdown has not begun, cleanup fails, or completion
+            cannot be observed.
+    """
+    try:
+        result = await runtime().completed()
+    except EncoreError as exc:
+        raise ShutdownError(str(exc)) from exc
+    return ShutdownResult._from_native(result)
+
+
+def phase() -> ShutdownPhase:
+    """Return the current shutdown phase, including before shutdown begins."""
+    return ShutdownPhase._from_native(runtime().phase())
+
+
+async def started() -> None:
+    """Wait until shutdown has reached or passed STARTED.
+
+    Call begin() first. Cancelling this wait does not cancel shutdown.
+
+    Raises:
+        ShutdownError: Shutdown has not begun or progress cannot be observed.
+    """
+    try:
+        await runtime().started()
+    except EncoreError as exc:
+        raise ShutdownError(str(exc)) from exc
+
+
+async def cleanup() -> None:
+    """Wait until shutdown has reached or passed CLEANUP.
+
+    Call begin() first. Cancelling this wait does not cancel shutdown.
+
+    Raises:
+        ShutdownError: Shutdown has not begun or progress cannot be observed.
+    """
+    try:
+        await runtime().cleanup()
+    except EncoreError as exc:
+        raise ShutdownError(str(exc)) from exc
+
+
+def force_cleanup() -> None:
+    """Request CLEANUP without waiting for active work to drain.
+
+    Call begin() first. Repeated calls are harmless. Await cleanup() to
+    observe the transition and completed() to await completion. Active
+    handlers are not terminated and may lose access to closing resources.
+    Forcing cleanup alone does not change the result to TIMEOUT.
+
+    Raises:
+        ShutdownError: Shutdown has not begun or cleanup cannot be forced.
+    """
+    try:
+        runtime().force_cleanup()
+    except EncoreError as exc:
+        raise ShutdownError(str(exc)) from exc
+
+
+def mark_application_drained() -> None:
+    """Notify Encore that all application-initiated work has completed.
+
+    This includes work such as processing incoming HTTP requests. Call this
+    when begin(cooperative=True) was used to advance from STARTED to CLEANUP
+    without waiting for the deadline. Repeated calls are harmless.
+    """
+    runtime().mark_application_drained()

encore/storage/__init__.py

@@ -0,0 +1,5 @@
+"""Infrastructure storage APIs."""
+
+from . import objects, postgres, redis
+
+__all__ = ["objects", "postgres", "redis"]

encore/storage/objects/__init__.py

@@ -0,0 +1,396 @@
+"""Object storage buckets declared at module scope and provisioned by Encore.
+
+Use the bucket's async methods to upload, download, inspect, and remove objects.
+Listing returns an async iterator; public URL construction is synchronous.
+"""
+
+from __future__ import annotations
+
+from collections.abc import AsyncGenerator, AsyncIterable
+from dataclasses import dataclass
+
+from ...internal.lazy import Lazy
+from ...internal.runtime import _native, runtime
+from ...tracing._context import active_ctx_bytes
+
+ObjectsError = _native.ObjectsError
+ObjectNotFound = _native.ObjectNotFound
+PreconditionFailed = _native.PreconditionFailed
+InvalidArgument = _native.InvalidArgument
+
+
+@dataclass(frozen=True)
+class ObjectAttrs:
+    """Metadata for a stored object.
+
+    Attributes:
+        name: The object's logical key.
+        version: The stored version identifier, if available.
+        size: The object's size in bytes.
+        content_type: The MIME type, if available.
+        etag: The opaque entity tag.
+    """
+
+    name: str
+    version: str | None
+    size: int
+    content_type: str | None
+    etag: str
+
+    @classmethod
+    def _from_native(cls, attrs: _native.ObjectAttrs) -> ObjectAttrs:
+        return cls(
+            attrs.name, attrs.version, attrs.size, attrs.content_type, attrs.etag
+        )
+
+
+@dataclass(frozen=True)
+class ListEntry:
+    """Metadata for an object returned by a bucket listing.
+
+    Attributes:
+        name: The object's logical key.
+        size: The object's size in bytes.
+        etag: The opaque entity tag.
+    """
+
+    name: str
+    size: int
+    etag: str
+
+
+def _validate_ttl(ttl: int) -> None:
+    if not 1 <= ttl <= 604800:
+        raise InvalidArgument("ttl must be between 1 and 604800 seconds")
+
+
+class Bucket:
+    """An object-storage bucket.
+
+    Declare at module scope so Encore can discover and provision the bucket.
+    ``versioned`` retains previous object versions; ``public`` makes objects
+    publicly accessible. Both default to False.
+
+    Storage failures raise ObjectsError or its subclasses. A missing object
+    raises ObjectNotFound, except for exists(), which returns False.
+    """
+
+    def __init__(
+        self, name: str, *, versioned: bool = False, public: bool = False
+    ) -> None:
+        """Declare an object-storage bucket at module scope.
+
+        Args:
+            name: The bucket's resource name.
+            versioned: Whether to retain previous object versions.
+            public: Whether objects are publicly accessible.
+        """
+        self._name = name
+        self._versioned = versioned
+        self._public = public
+        self._handle = Lazy(lambda: runtime().bucket(name))
+
+    @property
+    def _impl(self) -> _native.Bucket:
+        return self._handle.get()
+
+    @classmethod
+    def named(cls, name: str) -> Bucket:
+        """Reference an existing bucket configured for this service by name."""
+        return cls(name)
+
+    @property
+    def name(self) -> str:
+        """The declared bucket name."""
+        return self._name
+
+    async def upload(
+        self,
+        name: str,
+        data: bytes,
+        *,
+        content_type: str | None = None,
+        if_not_exists: bool = False,
+    ) -> ObjectAttrs:
+        """Upload bytes, replacing any existing object, and return metadata.
+
+        Versioned buckets retain previous versions.
+
+        Args:
+            name: The object's logical key.
+            data: The bytes to store.
+            content_type: The optional MIME type.
+            if_not_exists: Whether to reject overwriting an existing object.
+
+        Returns:
+            Metadata for the uploaded object.
+
+        Raises:
+            PreconditionFailed: The object exists and if_not_exists is True.
+            ObjectsError: The storage operation fails.
+        """
+        options = _native.UploadOptions(
+            content_type=content_type,
+            preconditions=(
+                _native.UploadPreconditions(not_exists=True) if if_not_exists else None
+            ),
+        )
+        attrs = await self._impl.object(name).upload(
+            data, options, source=active_ctx_bytes()
+        )
+        return ObjectAttrs._from_native(attrs)
+
+    async def upload_stream(
+        self,
+        name: str,
+        data: AsyncIterable[bytes],
+        *,
+        content_type: str | None = None,
+        if_not_exists: bool = False,
+    ) -> ObjectAttrs:
+        """Upload an asynchronous iterable of bytes with backpressure.
+
+        Chunks are consumed in order without buffering the whole object. Empty
+        chunks are allowed. Producer exceptions and cancellation abort the
+        upload; the caller owns and closes the input iterable, if necessary.
+        Like upload(), supports content_type and if_not_exists and returns the
+        stored object's metadata. Storage failures raise ObjectsError.
+        """
+        options = _native.UploadOptions(
+            content_type=content_type,
+            preconditions=(
+                _native.UploadPreconditions(not_exists=True) if if_not_exists else None
+            ),
+        )
+        stream = self._impl.object(name).upload_stream(
+            options, source=active_ctx_bytes()
+        )
+        try:
+            async for chunk in data:
+                if not isinstance(chunk, bytes):
+                    raise TypeError("upload_stream chunks must be bytes")
+                # Bound copies across the native boundary even if the producer
+                # hands us a very large chunk. Await each write for backpressure.
+                for offset in range(0, len(chunk), 65536):
+                    await stream.write(chunk[offset : offset + 65536])
+            return ObjectAttrs._from_native(await stream.finish())
+        finally:
+            await stream.close()
+
+    async def download_stream(
+        self,
+        name: str,
+        *,
+        version: str | None = None,
+        offset: int = 0,
+        length: int | None = None,
+    ) -> AsyncGenerator[bytes, None]:
+        """Yield an object's bytes as chunks, without collecting it in memory.
+
+        Version and byte-range options have the same meaning as download().
+        Chunk sizes are provider-dependent. Consume with async for; when
+        stopping early, use contextlib.aclosing or call aclose() to release the
+        response promptly. Exhaustion, errors, and cancellation close it.
+        Storage failures raise ObjectsError, including ObjectNotFound.
+        """
+        if offset < 0 or (length is not None and length <= 0):
+            raise InvalidArgument(
+                "offset must be nonnegative and length must be positive"
+            )
+        options = _native.DownloadOptions(
+            version=version,
+            range=(
+                _native.ByteRange(offset=offset, length=length)
+                if offset != 0 or length is not None
+                else None
+            ),
+        )
+        stream = await self._impl.object(name).download_stream(
+            options, source=active_ctx_bytes()
+        )
+        try:
+            while True:
+                chunk = await stream.next()
+                if chunk is None:
+                    break
+                yield chunk
+        finally:
+            await stream.close()
+
+    async def download(
+        self,
+        name: str,
+        *,
+        version: str | None = None,
+        offset: int = 0,
+        length: int | None = None,
+    ) -> bytes:
+        """Download an object or byte range into memory.
+
+        Args:
+            name: The object's logical key.
+            version: The stored version to read, or None for the latest version.
+            offset: The nonnegative, zero-based starting byte offset.
+            length: The positive maximum byte count, or None to read to the end.
+
+        Returns:
+            The requested object bytes.
+
+        Raises:
+            InvalidArgument: The range is invalid or starts beyond the object.
+            ObjectNotFound: The object or requested version does not exist.
+            ObjectsError: The storage operation fails.
+        """
+        if offset < 0 or (length is not None and length <= 0):
+            raise InvalidArgument(
+                "offset must be nonnegative and length must be positive"
+            )
+        options = _native.DownloadOptions(
+            version=version,
+            range=(
+                _native.ByteRange(offset=offset, length=length)
+                if offset != 0 or length is not None
+                else None
+            ),
+        )
+        return await self._impl.object(name).download_all(
+            options, source=active_ctx_bytes()
+        )
+
+    async def attrs(self, name: str, *, version: str | None = None) -> ObjectAttrs:
+        """Return object metadata, defaulting to the latest version.
+
+        Args:
+            name: The object's logical key.
+            version: The version to inspect, or None for the latest version.
+
+        Raises:
+            ObjectNotFound: The object or requested version does not exist.
+            ObjectsError: The storage operation fails.
+        """
+        attrs = await self._impl.object(name).attrs(
+            _native.AttrsOptions(version=version), source=active_ctx_bytes()
+        )
+        return ObjectAttrs._from_native(attrs)
+
+    async def exists(self, name: str, *, version: str | None = None) -> bool:
+        """Return whether the object or selected version exists.
+
+        Args:
+            name: The object's logical key.
+            version: The version to inspect, or None for the latest version.
+
+        Returns:
+            False if the object is missing, otherwise True.
+
+        Raises:
+            ObjectsError: A storage failure other than a missing object occurs.
+        """
+        return await self._impl.object(name).exists(
+            _native.ExistsOptions(version=version), source=active_ctx_bytes()
+        )
+
+    async def remove(self, name: str, *, version: str | None = None) -> None:
+        """Remove an object or a selected version.
+
+        Args:
+            name: The object's logical key.
+            version: The stored version to remove, or None for the default deletion.
+
+        Raises:
+            ObjectsError: The storage operation fails.
+        """
+        await self._impl.object(name).delete(
+            _native.DeleteOptions(version=version), source=active_ctx_bytes()
+        )
+
+    async def list(
+        self, *, prefix: str | None = None, limit: int | None = None
+    ) -> AsyncGenerator[ListEntry, None]:
+        """Yield object metadata matching the optional prefix and count limit.
+
+        Consume with async for. If stopping early, close the iterator with
+        aclose() or contextlib.aclosing to release it promptly.
+
+        Args:
+            prefix: The key prefix to match, or None to include all keys.
+            limit: The maximum number of entries, or None for no limit. Zero
+                yields no entries.
+
+        Yields:
+            Metadata for each matching object.
+
+        Raises:
+            InvalidArgument: The limit is negative.
+            ObjectsError: The storage operation fails.
+        """
+        if limit is not None and limit < 0:
+            raise InvalidArgument("limit must be nonnegative")
+        if limit == 0:
+            return
+        iterator = await self._impl.list(
+            _native.ListOptions(prefix=prefix, limit=limit), source=active_ctx_bytes()
+        )
+        try:
+            while True:
+                entry = await iterator.next()
+                if entry is None:
+                    break
+                yield ListEntry(entry.name, entry.size, entry.etag)
+        finally:
+            await iterator.mark_done()
+
+    async def signed_upload_url(self, name: str, *, ttl: int = 3600) -> str:
+        """Return a URL granting temporary upload access to an object.
+
+        Anyone possessing the URL can upload without other authentication.
+
+        Args:
+            name: The object's logical key.
+            ttl: The URL lifetime in seconds, from 1 to 604800 (seven days).
+                Defaults to 3600 (one hour).
+
+        Returns:
+            The signed upload URL.
+
+        Raises:
+            InvalidArgument: The lifetime is outside the supported range.
+            ObjectsError: The storage operation fails.
+        """
+        _validate_ttl(ttl)
+        return await self._impl.object(name).signed_upload_url(
+            _native.UploadUrlOptions(ttl=ttl), source=active_ctx_bytes()
+        )
+
+    async def signed_download_url(self, name: str, *, ttl: int = 3600) -> str:
+        """Return a URL granting temporary download access to an object.
+
+        Anyone possessing the URL can download without other authentication.
+
+        Args:
+            name: The object's logical key.
+            ttl: The URL lifetime in seconds, from 1 to 604800 (seven days).
+                Defaults to 3600 (one hour).
+
+        Returns:
+            The signed download URL.
+
+        Raises:
+            InvalidArgument: The lifetime is outside the supported range.
+            ObjectsError: The storage operation fails.
+        """
+        _validate_ttl(ttl)
+        return await self._impl.object(name).signed_download_url(
+            _native.DownloadUrlOptions(ttl=ttl), source=active_ctx_bytes()
+        )
+
+    def public_url(self, name: str) -> str:
+        """Return an object's public URL.
+
+        Args:
+            name: The object's logical key.
+
+        Raises:
+            ObjectsError: The bucket is private or URL construction fails.
+        """
+        return self._impl.object(name).public_url()