encore-dev 2.0.0b4__tar.gz → 2.0.0b5__tar.gz

{encore_dev-2.0.0b4 → encore_dev-2.0.0b5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: encore-dev
-Version: 2.0.0b4
+Version: 2.0.0b5
 Summary: Encore SDK for Python — infrastructure resources
 Author: Encore
 License: MPL-2.0
@@ -60,6 +60,29 @@ async def place_order(order):
     await events.publish({"id": order.id})
 ```
 
+## Secrets
+
+`secrets.Secret[T]("Name")` belongs to the service that declares it.
+`secrets.SharedSecret[T]("Name")` is one secret for the whole app, given to the
+services that read it, and `secrets.GlobalSecret[T]("Name")` one that every
+service is given. `T` is `str` or `bytes`, and `value` reads the secret decoded
+as that.
+
+A shared secret is declared once in the app. Another Python service can't
+import the declaring service's modules, so it references the secret by name
+instead:
+
+```python
+from encore.secrets import SharedSecret
+
+support_email = SharedSecret[str].named("SupportEmail")
+```
+
+Reading `value` makes the service one the secret is given to. The declaration
+can be in any language, and the type argument is how this service decodes the
+value, whatever the declaration's. Encore reports a reference to a name that
+isn't declared as a shared secret.
+
 ## Service URLs
 
 Use `base_url` to look up a service's configured base URL:
@@ -139,7 +162,7 @@ class User:
 
 
 current_user = reqctx.Field[User]("user")
-tenant = reqctx.Field[str]("tenant", record=True)
+tenant = reqctx.Field[str]("tenant", trace=True)
 ```
 
 Read a field while handling a request, and set or clear one for the calls made
@@ -161,7 +184,7 @@ that the types agree.
 
 - `pubsub=True` also carries the field on the Pub/Sub messages published with
   it set, into the handlers that receive them.
-- `record=True` records the value on the request's spans, as
+- `trace=True` puts the value on the request's spans, as
   `encore.ctx.<name>`. Use it for identifiers worth finding traces by, never
   for secrets.
 
@@ -274,6 +297,16 @@ Entering the context does not execute SQL. Exiting it closes the query.
 `exec(sql, *params)` returns an `ExecResult` with `rows_affected`. Rows are
 dictionaries keyed by column name. Values are bound with `$1`, `$2`, etc.
 
+Column values have the Python types asyncpg and psycopg use. `numeric` is a
+`decimal.Decimal` with the column's scale, so a `numeric(10,2)` holding 7 is
+`Decimal('7.00')`; `NaN` and `±Infinity` are `Decimal('NaN')` and
+`Decimal('Infinity')`. `timestamptz` is an aware `datetime.datetime` in UTC,
+`timestamp` a naive one, and `date` and `time` are `datetime.date` and
+`datetime.time`. `bytea` is `bytes`, arrays are lists of their elements' types,
+JSON is decoded, and `uuid`, `inet` and `cidr` are strings. Parameters accept
+the same types; a naive `datetime` bound to a `timestamptz` is taken as UTC,
+and an aware one may use any `tzinfo`, `zoneinfo.ZoneInfo` included.
+
 ```python
 async def find_order(database: postgres.Queryable, order_id: int):
     return await database.query("SELECT * FROM orders WHERE id = $1", order_id).first()
@@ -355,6 +388,65 @@ in a top-level Pydantic model and pass that class directly. Original bytes remai
 available as `message.raw_data`. Payloads are decoded once before the handler is
 called; decoding errors propagate for normal retry handling.
 
+## Gateway Middleware
+
+A service with a `gateway` section in its `encore.service.json` hosts the app's
+gateway, and its program serves it with Middleware: code that authenticates,
+limits, logs or meters the public requests the gateway serves. Encore runs it on
+the gateway variant of the native runtime.
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+import encore
+from encore import gateway, reqctx
+from encore.errs import ErrCode
+from encore.gateway import match
+
+
+@dataclass
+class User:
+    id: str
+
+
+current_user = reqctx.Field[User]("user")
+
+
+class Authenticate(gateway.Middleware):
+    match = match.path_prefix("/api")
+
+    async def on_request(self, req: gateway.Request) -> None:
+        user = await verify(req.header("authorization"))
+        if user is None:
+            raise gateway.reject(ErrCode.UNAUTHENTICATED, "missing token")
+        req.set(current_user, user)
+
+
+async def main() -> None:
+    await encore.start()
+    await gateway.serve(Authenticate())
+
+
+asyncio.run(main())
+```
+
+A Middleware is called at the hooks it defines (`on_request`, `on_request_body`,
+`on_response`, `on_response_body`, `on_complete`), only for the requests its
+`match` matches: Encore checks that before a request reaches Python. A hook may
+read any header, query parameter or cookie; each reaches Python only as the hook
+reads it. Encore checks a subclass when it is defined, so a misspelt hook raises
+at once.
+
+`on_request` sets the request's Request Context fields with
+`req.set(field, value)`: the services the request reaches read them with
+`field.get()`, and no client can set them. Every hook runs in the request's
+trace and context, so it reads them with `field.get()` too, or `req.get(field)`,
+and the calls it makes to services carry both.
+
+`gateway.serve` handles SIGTERM while it serves, so hooks keep running while the
+gateway drains, and returns once the shutdown has completed.
+
 ## Application-owned shutdown
 
 Without a hook, Encore shuts down non-cooperatively as the interpreter exits:

{encore_dev-2.0.0b4 → encore_dev-2.0.0b5}/README.md

@@ -40,6 +40,29 @@ async def place_order(order):
     await events.publish({"id": order.id})
 ```
 
+## Secrets
+
+`secrets.Secret[T]("Name")` belongs to the service that declares it.
+`secrets.SharedSecret[T]("Name")` is one secret for the whole app, given to the
+services that read it, and `secrets.GlobalSecret[T]("Name")` one that every
+service is given. `T` is `str` or `bytes`, and `value` reads the secret decoded
+as that.
+
+A shared secret is declared once in the app. Another Python service can't
+import the declaring service's modules, so it references the secret by name
+instead:
+
+```python
+from encore.secrets import SharedSecret
+
+support_email = SharedSecret[str].named("SupportEmail")
+```
+
+Reading `value` makes the service one the secret is given to. The declaration
+can be in any language, and the type argument is how this service decodes the
+value, whatever the declaration's. Encore reports a reference to a name that
+isn't declared as a shared secret.
+
 ## Service URLs
 
 Use `base_url` to look up a service's configured base URL:
@@ -119,7 +142,7 @@ class User:
 
 
 current_user = reqctx.Field[User]("user")
-tenant = reqctx.Field[str]("tenant", record=True)
+tenant = reqctx.Field[str]("tenant", trace=True)
 ```
 
 Read a field while handling a request, and set or clear one for the calls made
@@ -141,7 +164,7 @@ that the types agree.
 
 - `pubsub=True` also carries the field on the Pub/Sub messages published with
   it set, into the handlers that receive them.
-- `record=True` records the value on the request's spans, as
+- `trace=True` puts the value on the request's spans, as
   `encore.ctx.<name>`. Use it for identifiers worth finding traces by, never
   for secrets.
 
@@ -254,6 +277,16 @@ Entering the context does not execute SQL. Exiting it closes the query.
 `exec(sql, *params)` returns an `ExecResult` with `rows_affected`. Rows are
 dictionaries keyed by column name. Values are bound with `$1`, `$2`, etc.
 
+Column values have the Python types asyncpg and psycopg use. `numeric` is a
+`decimal.Decimal` with the column's scale, so a `numeric(10,2)` holding 7 is
+`Decimal('7.00')`; `NaN` and `±Infinity` are `Decimal('NaN')` and
+`Decimal('Infinity')`. `timestamptz` is an aware `datetime.datetime` in UTC,
+`timestamp` a naive one, and `date` and `time` are `datetime.date` and
+`datetime.time`. `bytea` is `bytes`, arrays are lists of their elements' types,
+JSON is decoded, and `uuid`, `inet` and `cidr` are strings. Parameters accept
+the same types; a naive `datetime` bound to a `timestamptz` is taken as UTC,
+and an aware one may use any `tzinfo`, `zoneinfo.ZoneInfo` included.
+
 ```python
 async def find_order(database: postgres.Queryable, order_id: int):
     return await database.query("SELECT * FROM orders WHERE id = $1", order_id).first()
@@ -335,6 +368,65 @@ in a top-level Pydantic model and pass that class directly. Original bytes remai
 available as `message.raw_data`. Payloads are decoded once before the handler is
 called; decoding errors propagate for normal retry handling.
 
+## Gateway Middleware
+
+A service with a `gateway` section in its `encore.service.json` hosts the app's
+gateway, and its program serves it with Middleware: code that authenticates,
+limits, logs or meters the public requests the gateway serves. Encore runs it on
+the gateway variant of the native runtime.
+
+```python
+import asyncio
+from dataclasses import dataclass
+
+import encore
+from encore import gateway, reqctx
+from encore.errs import ErrCode
+from encore.gateway import match
+
+
+@dataclass
+class User:
+    id: str
+
+
+current_user = reqctx.Field[User]("user")
+
+
+class Authenticate(gateway.Middleware):
+    match = match.path_prefix("/api")
+
+    async def on_request(self, req: gateway.Request) -> None:
+        user = await verify(req.header("authorization"))
+        if user is None:
+            raise gateway.reject(ErrCode.UNAUTHENTICATED, "missing token")
+        req.set(current_user, user)
+
+
+async def main() -> None:
+    await encore.start()
+    await gateway.serve(Authenticate())
+
+
+asyncio.run(main())
+```
+
+A Middleware is called at the hooks it defines (`on_request`, `on_request_body`,
+`on_response`, `on_response_body`, `on_complete`), only for the requests its
+`match` matches: Encore checks that before a request reaches Python. A hook may
+read any header, query parameter or cookie; each reaches Python only as the hook
+reads it. Encore checks a subclass when it is defined, so a misspelt hook raises
+at once.
+
+`on_request` sets the request's Request Context fields with
+`req.set(field, value)`: the services the request reaches read them with
+`field.get()`, and no client can set them. Every hook runs in the request's
+trace and context, so it reads them with `field.get()` too, or `req.get(field)`,
+and the calls it makes to services carry both.
+
+`gateway.serve` handles SIGTERM while it serves, so hooks keep running while the
+gateway drains, and returns once the shutdown has completed.
+
 ## Application-owned shutdown
 
 Without a hook, Encore shuts down non-cooperatively as the interpreter exits:

{encore_dev-2.0.0b4 → encore_dev-2.0.0b5}/encore/__init__.py

@@ -36,6 +36,8 @@ from . import (
     config,
     cron,
     env,
+    errs,
+    gateway,
     metrics,
     pubsub,
     reqctx,
@@ -55,6 +57,8 @@ __all__ = [
     "pubsub",
     "cron",
     "env",
+    "errs",
+    "gateway",
     "metrics",
     "reqctx",
     "secrets",

encore_dev-2.0.0b5/encore/errs/__init__.py

@@ -0,0 +1,90 @@
+"""Encore's error codes, and the error a request is answered with.
+
+An [APIError] is answered as Encore answers an error: with its code's HTTP
+status, and a JSON body Encore's clients read as the error::
+
+    {"code": "unauthenticated", "message": "missing token", "details": null}
+
+Typical usage example, in a gateway's Middleware::
+
+    from encore.errs import APIError, ErrCode
+
+    async def on_request(self, req):
+        if req.header("authorization") is None:
+            raise APIError(ErrCode.UNAUTHENTICATED, "missing token")
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+__all__ = ["APIError", "ErrCode"]
+
+
+class ErrCode(Enum):
+    """An Encore error code, and the HTTP status it answers with.
+
+    The values are the codes as Encore's error bodies spell them.
+    """
+
+    CANCELED = "canceled"
+    UNKNOWN = "unknown"
+    INVALID_ARGUMENT = "invalid_argument"
+    DEADLINE_EXCEEDED = "deadline_exceeded"
+    NOT_FOUND = "not_found"
+    ALREADY_EXISTS = "already_exists"
+    PERMISSION_DENIED = "permission_denied"
+    RESOURCE_EXHAUSTED = "resource_exhausted"
+    FAILED_PRECONDITION = "failed_precondition"
+    ABORTED = "aborted"
+    OUT_OF_RANGE = "out_of_range"
+    UNIMPLEMENTED = "unimplemented"
+    INTERNAL = "internal"
+    UNAVAILABLE = "unavailable"
+    DATA_LOSS = "data_loss"
+    UNAUTHENTICATED = "unauthenticated"
+
+    @property
+    def http_status(self) -> int:
+        """The HTTP status the code answers with.
+
+        401 for ``UNAUTHENTICATED``, 404 for ``NOT_FOUND``, and so on.
+        """
+        return _HTTP_STATUS[self]
+
+
+_HTTP_STATUS = {
+    ErrCode.CANCELED: 499,
+    ErrCode.UNKNOWN: 500,
+    ErrCode.INVALID_ARGUMENT: 400,
+    ErrCode.DEADLINE_EXCEEDED: 504,
+    ErrCode.NOT_FOUND: 404,
+    ErrCode.ALREADY_EXISTS: 409,
+    ErrCode.PERMISSION_DENIED: 403,
+    ErrCode.RESOURCE_EXHAUSTED: 429,
+    ErrCode.FAILED_PRECONDITION: 400,
+    ErrCode.ABORTED: 409,
+    ErrCode.OUT_OF_RANGE: 400,
+    ErrCode.UNIMPLEMENTED: 501,
+    ErrCode.INTERNAL: 500,
+    ErrCode.UNAVAILABLE: 503,
+    ErrCode.DATA_LOSS: 500,
+    ErrCode.UNAUTHENTICATED: 401,
+}
+
+
+class APIError(Exception):
+    """An error with an Encore error code, answered as Encore answers one.
+
+    Attributes:
+        code: The error's code.
+        message: What went wrong, for the client.
+    """
+
+    def __init__(self, code: ErrCode, message: str) -> None:
+        """Make an error with ``code`` and ``message``."""
+        if not isinstance(code, ErrCode):
+            raise TypeError(f"code must be an ErrCode, not {type(code).__name__}")
+        super().__init__(f"{code.value}: {message}")
+        self.code = code
+        self.message = message