encore-dev 2.0.0a7__py3-none-any.whl

encore/internal/lazy.py

@@ -0,0 +1,35 @@
+"""Thread-safe initialization for runtime resource handles."""
+
+from threading import Lock
+from typing import Callable, Generic, TypeVar
+
+T = TypeVar("T")
+
+
+class Lazy(Generic[T]):
+    """A thread-safe cache of the first successful factory result.
+
+    None is cached like any other result. Failed initialization can be retried.
+    """
+
+    def __init__(self, factory: Callable[[], T]) -> None:
+        """Initialize an unresolved value.
+
+        Args:
+            factory: A callable invoked on first access and retried if it raises.
+        """
+        self._factory = factory
+        self._value: tuple[T] | None = None
+        self._lock = Lock()
+
+    def get(self) -> T:
+        # The cached tuple is published only after initialization and never replaced.
+        """Return the cached value, initializing it once under a lock if needed."""
+        if (value := self._value) is not None:
+            return value[0]
+
+        with self._lock:
+            # Another caller may have initialized the value while we waited.
+            if self._value is None:
+                self._value = (self._factory(),)
+            return self._value[0]

encore/internal/runtime.py

@@ -0,0 +1,133 @@
+"""The process-wide runtime singleton over the native extension.
+
+This is the Python analogue of ``sdk/ts/infra/internal/runtime/mod.ts``: the
+native module wraps ``encore_sdk_core`` over PyO3, and the rest of the ``encore``
+package builds an ergonomic API on top of the runtime handle.
+
+The runtime is initialized synchronously when this module is imported, matching
+the TypeScript SDK. Encore must supply runtime configuration before application
+imports; initialization errors fail startup before requests are served.
+"""
+
+from __future__ import annotations
+
+import atexit
+import json
+import signal
+import sys
+import threading
+
+from ._loader import _native, _runtime_relative_path  # noqa: F401
+
+# The native error type, re-exported for callers that want to catch it.
+EncoreError = _native.EncoreError
+
+from ..logs._runtime import handle_line as _handle_runtime_line  # noqa: E402
+
+_native.set_runtime_log_handler(_handle_runtime_line)
+
+#: How long the runtime's queued lines may take to reach ``logging`` at exit.
+_RUNTIME_LOG_FLUSH = 1.0
+
+
+def _flush_runtime_log() -> None:
+    """Hand the runtime's queued lines to ``logging`` before exit."""
+    lost = _native.flush_runtime_log(_RUNTIME_LOG_FLUSH)
+    if lost:
+        print(f"encore: lost {lost} of the runtime's log lines", file=sys.stderr)
+
+
+# Registered first, so it runs after the exit handlers registered later.
+atexit.register(_flush_runtime_log)
+
+_runtime = _native.Runtime()
+
+from ..tracing._provider import install as _install_tracing  # noqa: E402
+
+_telemetry = _runtime.telemetry()
+_install_tracing(_telemetry)
+
+
+#: The outcome of the shutdown at exit, once run: whether it completed in time.
+_shutdown_ok: bool | None = None
+
+
+def _shutdown() -> bool:
+    """Drain infrastructure and flush telemetry once.
+
+    Wait for an existing application-initiated shutdown if one has begun.
+
+    Returns:
+        Whether shutdown completed within its deadline.
+    """
+    global _shutdown_ok
+    if _shutdown_ok is not None:
+        return _shutdown_ok
+    import asyncio
+
+    from .. import shutdown
+
+    if threading.current_thread() is threading.main_thread():
+        # A repeated SIGTERM must not interrupt the flush.
+        signal.signal(signal.SIGTERM, signal.SIG_IGN)
+    shutdown.begin()
+    result: list[bool] = []
+
+    def wait() -> None:
+        try:
+            done = asyncio.run(shutdown.completed())
+            result.append(done is shutdown.ShutdownResult.SUCCESS)
+        except Exception as exc:  # noqa: BLE001
+            print(f"encore: shutdown failed: {exc}", file=sys.stderr)
+
+    # Off this thread, which may be running an event loop.
+    waiter = threading.Thread(target=wait, name="encore-shutdown")
+    waiter.start()
+    waiter.join()
+    _shutdown_ok = bool(result and result[0])
+    return _shutdown_ok
+
+
+def _shutdown_at_exit() -> None:
+    _shutdown()
+
+
+def _exit_on_sigterm(signum: int, frame: object) -> None:
+    """Exit with 0 if shutdown completes in time, or 1 otherwise."""
+    raise SystemExit(0 if _shutdown() else 1)
+
+
+def _testing() -> bool:
+    """Whether the process runs tests, where the test runner owns SIGTERM."""
+    meta = json.loads(_runtime.app_meta_json())
+    return (meta.get("environment") or {}).get("type") == "test"
+
+
+atexit.register(_shutdown_at_exit)
+# SIGTERM's default action skips atexit. Servers that handle it themselves
+# replace this handler, and re-raise the signal after restoring it.
+if (
+    threading.current_thread() is threading.main_thread()
+    and signal.getsignal(signal.SIGTERM) is signal.SIG_DFL
+    and not _testing()
+):
+    signal.signal(signal.SIGTERM, _exit_on_sigterm)
+
+
+def runtime() -> _native.Runtime:
+    """Return the process-wide core runtime.
+
+    The runtime is initialized from the ambient ENCORE_* environment when
+    this module is imported. Resources are resolved by name using its config.
+    """
+    return _runtime
+
+
+def run_forever() -> None:
+    """Start draining infrastructure (subscriptions, metrics) and keep serving."""
+    runtime().run_forever()
+
+
+def version() -> str:
+    """The version of the Encore runtime in use."""
+    return _native.Runtime.version()

encore/internal/startup.py

@@ -0,0 +1,24 @@
+"""Application-loop startup for registered Encore resources."""
+
+from .. import pubsub
+
+
+async def start() -> None:
+    """The single Encore startup entrypoint for an application's asyncio loop.
+
+    Start all registered subscriptions and return. Import resource declarations
+    before calling this from your async main or framework startup hook.
+    Repeated calls on the same loop reuse consumers; later calls also start newly
+    imported subscriptions. This does not own the loop or install signal handlers.
+    """
+    subscriptions = list(pubsub._subscriptions)
+
+    # First loop, verify that all subscriptions are available
+    for subscription in subscriptions:
+        subscription._check_loop()
+        subscription._handle.get()
+
+    # Start all subscriptions
+    # This way no partial startup is possible
+    for subscription in subscriptions:
+        subscription._start()

encore/logs/__init__.py

@@ -0,0 +1,19 @@
+"""Log records in the Encore log format.
+
+:class:`ConsoleHandler` is a ``logging`` handler writing each record as one
+line in the Encore log format to stderr, which Encore's log collector reads;
+put it on the root logger::
+
+    import logging
+
+    from encore.logs import ConsoleHandler
+
+    logging.basicConfig(level=logging.INFO, handlers=[ConsoleHandler()])
+
+A record handled while a span is current carries its trace and span ids.
+The runtime's own lines log under the ``encore.runtime`` logger.
+"""
+
+from ._console import ConsoleHandler
+
+__all__ = ["ConsoleHandler"]

encore/logs/_console.py

@@ -0,0 +1,155 @@
+"""The ``logging`` handler printing the Encore log format."""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import traceback
+from typing import Any, Optional, TextIO
+
+from opentelemetry import trace
+
+from ..internal._loader import _native
+
+#: The record attribute holding the ``SpanContext`` a record belongs to, over
+#: the current span's.
+SPAN_CONTEXT_ATTR = "_encore_span_context"
+
+#: The record attribute holding the runtime module a line of the runtime's
+#: own comes from.
+RUNTIME_TARGET_ATTR = "_encore_runtime_target"
+
+#: Attributes every ``LogRecord`` has; the rest come from ``extra``.
+_STANDARD = frozenset(
+    logging.LogRecord("", 0, "", 0, "", (), None).__dict__.keys()
+    | {"message", "asctime", "taskName", SPAN_CONTEXT_ATTR, RUNTIME_TARGET_ATTR}
+)
+
+
+class ConsoleHandler(logging.StreamHandler):
+    """A logging handler that writes one Encore-formatted line per record.
+
+    Records are written to stream, or sys.stderr by default. Each line carries
+    the time, level,
+    message, logger name, the caller as ``code.*``, ``exc_info`` as
+    ``exception.*``, the ``extra`` attributes, and the ids of the span current
+    when the record is handled, with its sampled flag. The SDK core encodes
+    it; it needs the native library, not the runtime. Formatters are not
+    used.
+
+    An attribute named like a reserved key (``message``, ``trace_id``, …)
+    with a value valid for it is that field, in place of the record's; one
+    with an invalid value, or named like a key of the record's caller or
+    exception, is written as ``raw.<key>``.
+    """
+
+    def __init__(
+        self, stream: Optional[TextIO] = None, level: int | str = logging.NOTSET
+    ) -> None:
+        """Initialize an Encore console log handler.
+
+        Args:
+            stream: The text stream to write to, or None to use sys.stderr.
+            level: The minimum logging level as a number or logging level name.
+        """
+        super().__init__(stream)
+        self.setLevel(level)
+
+    def format(self, record: logging.LogRecord) -> str:
+        """Return the record as one Encore log line without a trailing newline.
+
+        Custom logging formatters are ignored.
+
+        Args:
+            record: The log record to encode.
+        """
+        return encode(record)
+
+
+def encode(record: logging.LogRecord) -> str:
+    """Return a record as one Encore log line without a trailing newline.
+
+    Args:
+        record: The record to encode. An explicit span context takes precedence
+            over the current OpenTelemetry span.
+    """
+    sc = getattr(record, SPAN_CONTEXT_ATTR, None)
+    if sc is None:
+        sc = trace.get_current_span().get_span_context()
+    span = None
+    if sc.is_valid:
+        span = (
+            sc.trace_id.to_bytes(16, "big")
+            + sc.span_id.to_bytes(8, "big")
+            + bytes((sc.trace_flags,))
+        )
+    exception_type = exception_message = exception_stacktrace = None
+    exc = record.exc_info
+    if exc and exc[0] is not None:
+        exception_type = _type_name(exc[0])
+        exception_message = str(exc[1])
+        exception_stacktrace = "".join(traceback.format_exception(*exc)).rstrip("\n")
+    return _native.encode_log(
+        _severity(record.levelno),
+        round(record.created * 1_000_000) * 1000,
+        record.getMessage(),
+        logger=record.name or None,
+        span_ctx=span,
+        exception_type=exception_type,
+        exception_message=exception_message,
+        exception_stacktrace=exception_stacktrace,
+        code_function=record.funcName or None,
+        code_file=record.pathname or None,
+        code_line=record.lineno or 0,
+        runtime_target=getattr(record, RUNTIME_TARGET_ATTR, None),
+        attrs_json=json.dumps(
+            _attributes(record), separators=(",", ":"), allow_nan=False
+        ),
+    )
+
+
+def _severity(levelno: int) -> int:
+    """The OpenTelemetry severity number of the range ``levelno`` is in."""
+    if levelno < logging.DEBUG:
+        return 1
+    if levelno < logging.INFO:
+        return 5
+    if levelno < logging.WARNING:
+        return 9
+    if levelno < logging.ERROR:
+        return 13
+    if levelno < logging.CRITICAL:
+        return 17
+    return 21
+
+
+def _attributes(record: logging.LogRecord) -> dict[str, Any]:
+    """The ``extra`` attributes."""
+    return {
+        key: _json(value)
+        for key, value in record.__dict__.items()
+        if key not in _STANDARD
+    }
+
+
+def _type_name(t: type) -> str:
+    if t.__module__ == "builtins":
+        return t.__qualname__
+    return f"{t.__module__}.{t.__qualname__}"
+
+
+def _json(v: object) -> Any:
+    """Return JSON-compatible values, converting unsupported values to strings.
+
+    Non-finite floats are also converted to strings.
+    """
+    if v is None or isinstance(v, (str, bool, int)):
+        return v
+    if isinstance(v, float):
+        return v if math.isfinite(v) else str(v)
+    if isinstance(v, (list, tuple)):
+        return [_json(x) for x in v]
+    if isinstance(v, dict):
+        return {str(k): _json(x) for k, x in v.items()}
+    return str(v)

encore/logs/_runtime.py

@@ -0,0 +1,56 @@
+"""The runtime's own log lines as ``logging`` records."""
+
+from __future__ import annotations
+
+import json
+import logging
+from typing import Optional
+
+from opentelemetry.trace import SpanContext, TraceFlags
+
+from ..internal._loader import _native
+from ._console import RUNTIME_TARGET_ATTR, SPAN_CONTEXT_ATTR
+
+#: The runtime's lines log under ``encore.runtime``, their target an
+#: attribute.
+LOGGER: str = _native.RUNTIME_LOGGER
+
+#: The runtime's TRACE; ``logging`` has none.
+TRACE = 5
+
+# The runtime's levels: 1 ERROR to 5 TRACE.
+_LEVELS = (logging.ERROR, logging.WARNING, logging.INFO, logging.DEBUG, TRACE)
+
+
+def handle_line(
+    level: int,
+    target: str,
+    message: str,
+    fields_json: str,
+    span_ctx: Optional[bytes],
+) -> None:
+    """Log one runtime line from the native log-handler callback.
+
+    Records use the encore.runtime logger. The target is stored in the
+    RUNTIME_TARGET_ATTR record attribute and fields become record attributes.
+    Fields colliding with LogRecord attributes use a raw.<name> key. The
+    25-byte span_ctx supplies the record's span.
+    """
+    levelno = _LEVELS[min(max(level, 1), 5) - 1]
+    logger = logging.getLogger(LOGGER)
+    if not logger.isEnabledFor(levelno):
+        return
+    record = logger.makeRecord(LOGGER, levelno, "", 0, message, (), None)
+    for key, value in json.loads(fields_json).items():
+        while key in record.__dict__ or key in ("message", "asctime"):
+            key = "raw." + key
+        record.__dict__[key] = value
+    record.__dict__[RUNTIME_TARGET_ATTR] = target
+    if span_ctx:
+        record.__dict__[SPAN_CONTEXT_ATTR] = SpanContext(
+            int.from_bytes(span_ctx[:16], "big"),
+            int.from_bytes(span_ctx[16:24], "big"),
+            is_remote=False,
+            trace_flags=TraceFlags(span_ctx[24]),
+        )
+    logger.handle(record)

encore/meta/__init__.py

@@ -0,0 +1,228 @@
+"""Metadata for the running application and its API gateways.
+
+Typical usage example:
+
+    from encore import meta
+
+    md = meta.app_meta()
+    if md.environment.type == "production":
+        ...
+
+    # An app can declare several gateways, so look one up by name.
+    gw = md.gateways.get("api")
+    if gw is not None:
+        print("api is at", gw.base_url)
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Dict, List, Optional
+
+from ..internal.runtime import runtime
+
+__all__ = [
+    "app_meta",
+    "AppMeta",
+    "GatewayMeta",
+    "EnvironmentMeta",
+    "BuildMeta",
+    "DeployMeta",
+    "HostedService",
+]
+
+
+@dataclass(frozen=True)
+class GatewayMeta:
+    """An API gateway serving the application.
+
+    Attributes:
+        name: The name of the gateway, as declared by the application.
+        base_url: The base URL which can be used to call the API of this running
+            application through this gateway.
+
+            For local development it is ``http://localhost:<port>``, typically
+            ``http://localhost:4000``.
+
+            If a custom domain is used for this environment it is returned here,
+            but note that changes only take effect at the time of deployment
+            while custom domains can be updated at any time.
+    """
+
+    name: str
+
+    base_url: str
+
+
+@dataclass(frozen=True)
+class EnvironmentMeta:
+    """The environment the application is running in.
+
+    Attributes:
+        name: The name of the environment. For local development it is
+            ``"local"``.
+        type: The type of environment: ``"production"``, ``"development"``,
+            ``"ephemeral"`` or ``"test"``. For local development it is
+            ``"development"``.
+        cloud: The cloud the environment runs on: ``"aws"``, ``"gcp"``,
+            ``"azure"``, ``"encore"`` or ``"local"``. For local development it
+            is ``"local"``.
+    """
+
+    name: str
+
+    type: str
+
+    cloud: str
+
+
+@dataclass(frozen=True)
+class BuildMeta:
+    """The build that formed the running application.
+
+    Attributes:
+        revision: The VCS revision the deployed application was built from.
+    """
+
+    revision: str
+
+
+@dataclass(frozen=True)
+class HostedService:
+    """A service hosted by this deployment.
+
+    Attributes:
+        name: The name of the service.
+    """
+
+    name: str
+
+
+@dataclass(frozen=True)
+class DeployMeta:
+    """This deployment of the application.
+
+    Attributes:
+        id: The unique id of the deployment. Generated by the Encore Platform.
+        time: The time the Encore Platform deployed this build to the
+            environment.
+        hosted_services: The services hosted by this deployment.
+    """
+
+    id: str
+
+    time: datetime
+
+    hosted_services: List[HostedService] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class AppMeta:
+    """Metadata about the running Encore application.
+
+    Attributes:
+        app_id: The Encore application ID. Empty if the application is not
+            linked to the Encore platform; run ``encore app link`` to link it.
+        app_slug: The application slug — the human-readable identifier shown in
+            the Encore Cloud dashboard and used by the CLI. Empty if the
+            application is not linked to the Encore platform.
+
+            Distinct from :attr:`app_id`: the id is opaque and stable, the slug
+            is readable and may be renamed. Locally the two are the same.
+        gateways: The API gateways that serve this application, keyed by gateway
+            name.
+
+            An application can declare several gateways, so there is no single
+            base URL for the API — look up the gateway you mean by name. A
+            process that serves no gateway (a worker) reports an empty mapping.
+        environment: The environment the app is running in.
+        build: The build the running binary came from.
+        deploy: This deployment of the binary.
+    """
+
+    app_id: str
+
+    app_slug: str
+
+    gateways: Dict[str, GatewayMeta]
+
+    environment: EnvironmentMeta
+
+    build: BuildMeta
+
+    deploy: DeployMeta
+
+
+_cached: Optional[AppMeta] = None
+
+
+def app_meta() -> AppMeta:
+    """Return metadata about the running Encore application.
+
+    The metadata is computed on first use and the same object is returned by every
+    subsequent call.
+    """
+    global _cached
+    if _cached is None:
+        _cached = _decode(json.loads(runtime().app_meta_json()))
+    return _cached
+
+
+def _decode(raw: dict) -> AppMeta:
+    env = raw.get("environment") or {}
+    build = raw.get("build") or {}
+    deploy = raw.get("deploy") or {}
+
+    return AppMeta(
+        app_id=raw.get("app_id", ""),
+        app_slug=raw.get("app_slug", ""),
+        gateways={
+            name: GatewayMeta(
+                name=gw.get("name", name), base_url=gw.get("base_url", "")
+            )
+            for name, gw in (raw.get("gateways") or {}).items()
+        },
+        environment=EnvironmentMeta(
+            name=env.get("name", ""),
+            type=env.get("type", "development"),
+            cloud=env.get("cloud", "local"),
+        ),
+        build=BuildMeta(revision=build.get("revision", "")),
+        deploy=DeployMeta(
+            id=deploy.get("id", ""),
+            time=_parse_time(deploy.get("deploy_time")),
+            hosted_services=[
+                HostedService(name=svc.get("name", ""))
+                for svc in (deploy.get("hosted_services") or [])
+            ],
+        ),
+    )
+
+
+# Matches a fractional-seconds group of any precision, so it can be trimmed to
+# the six digits datetime supports.
+_FRACTION = re.compile(r"\.(\d+)")
+
+
+def _parse_time(value: Optional[str]) -> datetime:
+    """Parse the core's RFC 3339 timestamp.
+
+    ``datetime.fromisoformat`` is only lenient enough on Python 3.11+, and the
+    core emits nanosecond precision and a ``Z`` suffix — both of which older
+    versions reject. Normalize to what every supported version accepts.
+    """
+    if not value:
+        return datetime.fromtimestamp(0, tz=timezone.utc)
+
+    normalized = value
+    if normalized.endswith(("Z", "z")):
+        normalized = normalized[:-1] + "+00:00"
+    normalized = _FRACTION.sub(lambda m: "." + m.group(1)[:6].ljust(6, "0"), normalized)
+
+    try:
+        return datetime.fromisoformat(normalized)
+    except ValueError:
+        return datetime.fromtimestamp(0, tz=timezone.utc)