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

encore_dev-2.0.0a17/README.md → encore_dev-2.0.0b5/PKG-INFO

@@ -1,3 +1,23 @@
+Metadata-Version: 2.3
+Name: encore-dev
+Version: 2.0.0b5
+Summary: Encore SDK for Python — infrastructure resources
+Author: Encore
+License: MPL-2.0
+Classifier: Programming Language :: Python :: 3
+Requires-Dist: opentelemetry-api>=1.27
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: aiohttp>=3.14.4 ; python_full_version >= '3.10' and extra == 'aiohttp'
+Requires-Dist: httpx>=0.27 ; extra == 'httpx'
+Requires-Dist: niquests>=3.19 ; extra == 'niquests'
+Requires-Dist: requests>=2.34 ; python_full_version >= '3.10' and extra == 'requests'
+Requires-Python: >=3.9
+Provides-Extra: aiohttp
+Provides-Extra: httpx
+Provides-Extra: niquests
+Provides-Extra: requests
+Description-Content-Type: text/markdown
+
 # Encore SDK for Python
 
 The Python SDK for [Encore](https://encore.dev) — **infrastructure resources only**.
@@ -40,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:
@@ -58,6 +101,184 @@ Looking up a service's URL makes the calling service depend on it, which Encore
 reads from the code: pass the name as a string literal, call `base_url` directly
 rather than passing it around, and call it in a service.
 
+### Calling services
+
+To call a service, use the adapter for your HTTP client. Each adapter re-exports
+`encore.services` and adds `client(service)`, a client whose relative URLs are
+the service's: the async one where the library has both kinds, with
+`sync_client(service)` for the other:
+
+```python
+from encore.services import httpx as services
+
+billing = services.client("billing")
+
+
+async def invoices():
+    response = await billing.get("/invoices")
+    return response.json()
+```
+
+| Adapter | Install | `client` returns | `sync_client` returns |
+|---|---|---|---|
+| `encore.services.httpx` | `encore-dev[httpx]` | `httpx.AsyncClient` | `httpx.Client` |
+| `encore.services.requests` | `encore-dev[requests]` | `requests.Session` | |
+| `encore.services.aiohttp` | `encore-dev[aiohttp]` | `aiohttp.ClientSession` | |
+| `encore.services.niquests` | `encore-dev[niquests]` | `niquests.AsyncSession` | `niquests.Session` |
+
+The `requests` and `aiohttp` extras need Python 3.10: on 3.9 they install
+nothing, as their releases for 3.9 have known vulnerabilities, and the adapters
+use the client the app installed.
+
+A generated client takes an `httpx.Client` as its `http_client`, so give it
+`sync_client`. Their other arguments go to the client's constructor, as keywords. The same
+rules as `base_url` apply to the service's name. aiohttp joins relative URLs as
+links are, so write them without the leading slash there: `get("invoices")`;
+and it creates a session only in a running event loop, so call its `client` in
+a coroutine, such as a lifespan handler.
+
+The clients send the Request Context of the calls made with them to the app's
+services, and never to anything else, redirects included. A client you build
+yourself can do the same with the adapter's hook: `Transport` and
+`AsyncTransport` for httpx, the requests `Adapter`, the aiohttp `middleware`, or the
+niquests `pre_request` hook.
+
+## Request Context
+
+Request Context fields are typed values that travel with a request to every
+service it reaches, such as the user it is made for. Declare a field once, at
+module scope, with its name and the type of its value:
+
+```python
+from dataclasses import dataclass
+
+from encore import reqctx
+
+
+@dataclass
+class User:
+    id: str
+    admin: bool = False
+
+
+current_user = reqctx.Field[User]("user")
+tenant = reqctx.Field[str]("tenant", trace=True)
+```
+
+Read a field while handling a request, and set or clear one for the calls made
+in a block:
+
+```python
+user = current_user.get()  # None when not set
+
+with current_user.set(User(id="system")):
+    await billing.get("/invoices")
+
+with tenant.unset():
+    ...
+```
+
+Reference a field declared elsewhere, in any language, by name and with its
+value's type: `current_user = reqctx.Field[User].named("user")`. Encore checks
+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.
+- `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.
+
+A request keeps every field it carries, including ones the service never
+declares, and passes them on to the services it calls through the
+`encore.services` clients. Fields are never sent to anything else. A field's
+value may encode to at most 4 KiB (1 KiB with `pubsub`), and a request's fields
+to at most 8 KiB in all: setting a value beyond that raises `ValueError`.
+
+## Running the service
+
+`encore.run(app)` runs the service: it serves an ASGI app (FastAPI, Starlette,
+...) with Encore's server, built on hyper, Rust's HTTP library, and handles its
+lifecycle.
+
+```python
+import encore
+from fastapi import FastAPI
+
+app = FastAPI()
+
+if __name__ == "__main__":
+    encore.run(app)
+```
+
+- **Startup**: it binds the address Encore assigns the service, runs the app's
+  lifespan startup, starts listening, and starts Encore's Pub/Sub
+  subscriptions. A failed startup exits with 1.
+- **Requests**: HTTP/1.1 and HTTP/2 (h2c). Each request has its Request Context
+  and a span continuing its trace, with no OpenTelemetry setup in the app. The
+  server records the span itself, from the request's arrival to its response,
+  named after the route the app matched; the app's code reaches it as
+  `trace.get_current_span()`.
+- **Shutdown**: on SIGTERM or SIGINT it stops accepting connections and taking
+  Pub/Sub messages, lets the requests in flight finish, runs the app's lifespan
+  shutdown, and lets Encore clean up the resources the app used, all within
+  Encore's shutdown deadline. A request waiting for its client to go away, as a
+  stream of events does, is told it did. A second Ctrl-C stops waiting.
+
+A service without an HTTP API, as one that only handles Pub/Sub messages, calls
+`encore.run()`: the same, without the server.
+
+- `workers=N` runs N event loops on threads, sharing the app. It needs
+  free-threaded Python with the GIL disabled (`python3.14t`), where they run in
+  parallel. Each worker runs the app's lifespan with its own `state`, so
+  resources bound to an event loop stay on theirs.
+- `max_concurrency` caps the requests the app handles at once.
+- `read_timeout` (30 seconds) bounds how long a client may take to send a
+  request's headers, a body of up to 64 KiB (answered with 408 when it takes
+  longer), or each part of a longer one (after which its request reads as its
+  client gone).
+- `tracing=False` takes only the Request Context.
+- WebSockets are not supported yet.
+
+A WSGI app (Flask, Django's WSGI application) runs through a WSGI-to-ASGI
+adapter, such as `a2wsgi`'s, which calls it on a thread pool in the request's
+context, so its code reads the Request Context and its calls carry it on:
+
+```python
+import encore
+from a2wsgi import WSGIMiddleware
+from flask import Flask
+
+app = Flask(__name__)
+
+if __name__ == "__main__":
+    encore.run(WSGIMiddleware(app))
+```
+
+Its spans are not named after its routes: WSGI frameworks don't say which one
+they matched.
+
+FastAPI records spans of its own once a tracer provider is set, as `run` sets
+Encore's: a second server span for each request, and spans of dependencies,
+endpoints and serialization. `run` turns them off for its requests; pass
+`server_spans=False` to leave the request's span, and those, to FastAPI.
+
+An app served by a server of its own adds Encore's middleware instead, for the
+same Request Context and tracing:
+
+```python
+from encore.server import asgi, wsgi
+
+app.add_middleware(asgi.Middleware)  # FastAPI, Starlette
+app = wsgi.Middleware(app)  # Flask, Django's WSGI application
+```
+
+Both make Encore's tracer provider OpenTelemetry's global one, unless the app
+set its own. The middleware works beside OpenTelemetry's own: inside it, as
+`FastAPIInstrumentor` arranges, the request's span is that one's; outside it,
+OpenTelemetry's records an internal span under Encore's. The ASGI middleware
+names the span after the route FastAPI or Starlette matched; WSGI frameworks
+don't say which route they matched.
+
 ## Postgres queries and handles
 
 Declare `postgres.Database("orders", migrations="./migrations")` at module scope.
@@ -76,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()
@@ -157,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.0a17/PKG-INFO → encore_dev-2.0.0b5/README.md

@@ -1,16 +1,3 @@
-Metadata-Version: 2.3
-Name: encore-dev
-Version: 2.0.0a17
-Summary: Encore SDK for Python — infrastructure resources
-Author: Encore
-License: MPL-2.0
-Classifier: Programming Language :: Python :: 3
-Requires-Dist: opentelemetry-api>=1.27
-Requires-Dist: opentelemetry-semantic-conventions>=0.62b1
-Requires-Dist: typing-extensions>=4.12
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-
 # Encore SDK for Python
 
 The Python SDK for [Encore](https://encore.dev) — **infrastructure resources only**.
@@ -53,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:
@@ -71,6 +81,184 @@ Looking up a service's URL makes the calling service depend on it, which Encore
 reads from the code: pass the name as a string literal, call `base_url` directly
 rather than passing it around, and call it in a service.
 
+### Calling services
+
+To call a service, use the adapter for your HTTP client. Each adapter re-exports
+`encore.services` and adds `client(service)`, a client whose relative URLs are
+the service's: the async one where the library has both kinds, with
+`sync_client(service)` for the other:
+
+```python
+from encore.services import httpx as services
+
+billing = services.client("billing")
+
+
+async def invoices():
+    response = await billing.get("/invoices")
+    return response.json()
+```
+
+| Adapter | Install | `client` returns | `sync_client` returns |
+|---|---|---|---|
+| `encore.services.httpx` | `encore-dev[httpx]` | `httpx.AsyncClient` | `httpx.Client` |
+| `encore.services.requests` | `encore-dev[requests]` | `requests.Session` | |
+| `encore.services.aiohttp` | `encore-dev[aiohttp]` | `aiohttp.ClientSession` | |
+| `encore.services.niquests` | `encore-dev[niquests]` | `niquests.AsyncSession` | `niquests.Session` |
+
+The `requests` and `aiohttp` extras need Python 3.10: on 3.9 they install
+nothing, as their releases for 3.9 have known vulnerabilities, and the adapters
+use the client the app installed.
+
+A generated client takes an `httpx.Client` as its `http_client`, so give it
+`sync_client`. Their other arguments go to the client's constructor, as keywords. The same
+rules as `base_url` apply to the service's name. aiohttp joins relative URLs as
+links are, so write them without the leading slash there: `get("invoices")`;
+and it creates a session only in a running event loop, so call its `client` in
+a coroutine, such as a lifespan handler.
+
+The clients send the Request Context of the calls made with them to the app's
+services, and never to anything else, redirects included. A client you build
+yourself can do the same with the adapter's hook: `Transport` and
+`AsyncTransport` for httpx, the requests `Adapter`, the aiohttp `middleware`, or the
+niquests `pre_request` hook.
+
+## Request Context
+
+Request Context fields are typed values that travel with a request to every
+service it reaches, such as the user it is made for. Declare a field once, at
+module scope, with its name and the type of its value:
+
+```python
+from dataclasses import dataclass
+
+from encore import reqctx
+
+
+@dataclass
+class User:
+    id: str
+    admin: bool = False
+
+
+current_user = reqctx.Field[User]("user")
+tenant = reqctx.Field[str]("tenant", trace=True)
+```
+
+Read a field while handling a request, and set or clear one for the calls made
+in a block:
+
+```python
+user = current_user.get()  # None when not set
+
+with current_user.set(User(id="system")):
+    await billing.get("/invoices")
+
+with tenant.unset():
+    ...
+```
+
+Reference a field declared elsewhere, in any language, by name and with its
+value's type: `current_user = reqctx.Field[User].named("user")`. Encore checks
+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.
+- `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.
+
+A request keeps every field it carries, including ones the service never
+declares, and passes them on to the services it calls through the
+`encore.services` clients. Fields are never sent to anything else. A field's
+value may encode to at most 4 KiB (1 KiB with `pubsub`), and a request's fields
+to at most 8 KiB in all: setting a value beyond that raises `ValueError`.
+
+## Running the service
+
+`encore.run(app)` runs the service: it serves an ASGI app (FastAPI, Starlette,
+...) with Encore's server, built on hyper, Rust's HTTP library, and handles its
+lifecycle.
+
+```python
+import encore
+from fastapi import FastAPI
+
+app = FastAPI()
+
+if __name__ == "__main__":
+    encore.run(app)
+```
+
+- **Startup**: it binds the address Encore assigns the service, runs the app's
+  lifespan startup, starts listening, and starts Encore's Pub/Sub
+  subscriptions. A failed startup exits with 1.
+- **Requests**: HTTP/1.1 and HTTP/2 (h2c). Each request has its Request Context
+  and a span continuing its trace, with no OpenTelemetry setup in the app. The
+  server records the span itself, from the request's arrival to its response,
+  named after the route the app matched; the app's code reaches it as
+  `trace.get_current_span()`.
+- **Shutdown**: on SIGTERM or SIGINT it stops accepting connections and taking
+  Pub/Sub messages, lets the requests in flight finish, runs the app's lifespan
+  shutdown, and lets Encore clean up the resources the app used, all within
+  Encore's shutdown deadline. A request waiting for its client to go away, as a
+  stream of events does, is told it did. A second Ctrl-C stops waiting.
+
+A service without an HTTP API, as one that only handles Pub/Sub messages, calls
+`encore.run()`: the same, without the server.
+
+- `workers=N` runs N event loops on threads, sharing the app. It needs
+  free-threaded Python with the GIL disabled (`python3.14t`), where they run in
+  parallel. Each worker runs the app's lifespan with its own `state`, so
+  resources bound to an event loop stay on theirs.
+- `max_concurrency` caps the requests the app handles at once.
+- `read_timeout` (30 seconds) bounds how long a client may take to send a
+  request's headers, a body of up to 64 KiB (answered with 408 when it takes
+  longer), or each part of a longer one (after which its request reads as its
+  client gone).
+- `tracing=False` takes only the Request Context.
+- WebSockets are not supported yet.
+
+A WSGI app (Flask, Django's WSGI application) runs through a WSGI-to-ASGI
+adapter, such as `a2wsgi`'s, which calls it on a thread pool in the request's
+context, so its code reads the Request Context and its calls carry it on:
+
+```python
+import encore
+from a2wsgi import WSGIMiddleware
+from flask import Flask
+
+app = Flask(__name__)
+
+if __name__ == "__main__":
+    encore.run(WSGIMiddleware(app))
+```
+
+Its spans are not named after its routes: WSGI frameworks don't say which one
+they matched.
+
+FastAPI records spans of its own once a tracer provider is set, as `run` sets
+Encore's: a second server span for each request, and spans of dependencies,
+endpoints and serialization. `run` turns them off for its requests; pass
+`server_spans=False` to leave the request's span, and those, to FastAPI.
+
+An app served by a server of its own adds Encore's middleware instead, for the
+same Request Context and tracing:
+
+```python
+from encore.server import asgi, wsgi
+
+app.add_middleware(asgi.Middleware)  # FastAPI, Starlette
+app = wsgi.Middleware(app)  # Flask, Django's WSGI application
+```
+
+Both make Encore's tracer provider OpenTelemetry's global one, unless the app
+set its own. The middleware works beside OpenTelemetry's own: inside it, as
+`FastAPIInstrumentor` arranges, the request's span is that one's; outside it,
+OpenTelemetry's records an internal span under Encore's. The ASGI middleware
+names the span after the route FastAPI or Starlette matched; WSGI frameworks
+don't say which route they matched.
+
 ## Postgres queries and handles
 
 Declare `postgres.Database("orders", migrations="./migrations")` at module scope.
@@ -89,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()
@@ -170,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: