sillo-framework 0.2.0__tar.gz → 0.3.0__tar.gz

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-08-21
+
+### Added
+
+- `sillo.storage.current_storage()` and `sillo.storage.bucket(name)` — reach the `Storage` `setup_storage` registered, from a handler, a queue job, or a script, without the application object or a request.
+- `sillo.mail.current_mail()` and `sillo.mail.send_email(...)` — same shape, for the `MailClient` `setup_mail` registered.
+- `sillo._internals.registry.InstanceRegistry`, the shared internal mechanism behind both: a plain slot filled once at startup and read from anywhere, raising `NotConfiguredError` — not `None` — when asked before `setup_x` has run. Documented in [Instance Registry](https://sillo.build/advanced/context-binding/).
+- `useAuth(unauthorized=..., forbidden=...)` — per-route hooks that answer a failed gate directly instead of raising `AuthenticationFailed`/`PermissionDenied` for the global exception handler to catch. Each is called as `hook(request, response)`, sync or async, and its return value is sent as the response with the route handler never reached. Unset, a gate behaves exactly as before.
+
+## [0.2.1] - 2026-08-19
+
+### Changed
+
+- Replaced `itsdangerous` with an internal `sillo.helpers.signing` implementation for CSRF tokens and signed session cookies.
+- Moved `sillo.utils` modules into `sillo.helpers`.
+- Fixed `typing-extensions` dependency marker to require the package on Python < 3.13.
+
 ## [0.2.0] - 2026-08-18
 
 A minor release, not a patch: `sillo.env` is new public API, and `.env` now

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: sillo-framework
-Version: 0.2.0
+Version: 0.3.0
 Summary: Python with the pieces already in place: an async web framework whose ORM, auth, admin, queues, scheduler and WebSockets share one configuration model.
 Project-URL: Homepage, https://github.com/sillohq/core
 Project-URL: Repository, https://github.com/sillohq/core
@@ -29,10 +29,9 @@ Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
 Requires-Dist: anyio==4.14.1
-Requires-Dist: itsdangerous>=2.1.2
 Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: python-multipart>=0.0.6
-Requires-Dist: typing-extensions>=4.12.2; python_version < '3.10'
+Requires-Dist: typing-extensions>=4.12.2; python_version < '3.13'
 Requires-Dist: uvicorn>=0.27.0
 Provides-Extra: all
 Requires-Dist: argon2-cffi>=21.2.0; extra == 'all'
@@ -96,6 +95,8 @@ Provides-Extra: jwt
 Requires-Dist: pyjwt>=2.7.0; extra == 'jwt'
 Provides-Extra: record
 Requires-Dist: tortoise-orm>=1.0; extra == 'record'
+Provides-Extra: storage-s3
+Requires-Dist: httpx>=0.23.3; extra == 'storage-s3'
 Provides-Extra: templating
 Requires-Dist: jinja2>=3.1.6; extra == 'templating'
 Description-Content-Type: text/markdown
@@ -186,42 +187,22 @@ async def home(request, response):
     return response.json({"message": "Hello from Sillo"})
 ```
 
-Run it with Sillo's own server:
+Run it with uvicorn:
 
 ```bash
-uv run sillo serve --reload
+uv run uvicorn app:app --reload
 ```
 
-```
-  ● sillo 0.2.0
-
-    app       main:app
-    url       http://127.0.0.1:8000
-    routes    4
-    inspect   http://127.0.0.1:8000/__sillo/requests
-    mode      serving
-    pid       5716
-
-    ready in 7ms  ·  press ctrl-c to stop
-
-  22:48:04  GET     200  /                                      409us
-```
-
-No import string is needed. `sillo serve` looks for `app.main:app`, `main:app`
+No import string is needed. `uvicorn` looks for `app.main:app`, `main:app`
 and `app:app`, and you can pin it with the `SILLO_APP` environment variable or
 a `[tool.sillo] app` entry in `pyproject.toml`. Pass one explicitly when you
 want something else:
 
 ```bash
-uv run sillo serve api.main:app --port 9000 --workers 4
+uv run uvicorn api.main:app --port 9000 --workers 4
 ```
 
-Each request is logged with the time it took, and the address in the `inspect`
-line is a clickable request log you can open while developing. Add
-`--no-inspect` to leave it out, or `--plain` to see the underlying server's own
-output instead.
-
-`sillo serve` is built for development. For production, run the application
+`uvicorn` is built for development. For production, run the application
 under a process supervisor with a reverse proxy in front of it.
 
 ## Request Validation

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/README.md

@@ -84,42 +84,22 @@ async def home(request, response):
     return response.json({"message": "Hello from Sillo"})
 ```
 
-Run it with Sillo's own server:
+Run it with uvicorn:
 
 ```bash
-uv run sillo serve --reload
+uv run uvicorn app:app --reload
 ```
 
-```
-  ● sillo 0.2.0
-
-    app       main:app
-    url       http://127.0.0.1:8000
-    routes    4
-    inspect   http://127.0.0.1:8000/__sillo/requests
-    mode      serving
-    pid       5716
-
-    ready in 7ms  ·  press ctrl-c to stop
-
-  22:48:04  GET     200  /                                      409us
-```
-
-No import string is needed. `sillo serve` looks for `app.main:app`, `main:app`
+No import string is needed. `uvicorn` looks for `app.main:app`, `main:app`
 and `app:app`, and you can pin it with the `SILLO_APP` environment variable or
 a `[tool.sillo] app` entry in `pyproject.toml`. Pass one explicitly when you
 want something else:
 
 ```bash
-uv run sillo serve api.main:app --port 9000 --workers 4
+uv run uvicorn api.main:app --port 9000 --workers 4
 ```
 
-Each request is logged with the time it took, and the address in the `inspect`
-line is a clickable request log you can open while developing. Add
-`--no-inspect` to leave it out, or `--plain` to see the underlying server's own
-output instead.
-
-`sillo serve` is built for development. For production, run the application
+`uvicorn` is built for development. For production, run the application
 under a process supervisor with a reverse proxy in front of it.
 
 ## Request Validation

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/docs/docs/astro.config.mjs

@@ -296,6 +296,7 @@ export default defineConfig({
                         { label: 'Application Lifecycle', link: '/advanced/application-lifecycle/' },
                         { label: 'Configuration System', link: '/advanced/configuration/' },
                         { label: 'Type System & Encoding', link: '/advanced/types-and-encoding/' },
+                        { label: 'Instance Registry', link: '/advanced/context-binding/' },
                     ],
                 },
                 {
@@ -375,6 +376,7 @@ export default defineConfig({
                         { label: 'Cache System', link: '/advanced/cache/' },
                         { label: 'Templating', link: '/advanced/templating/' },
                         { label: 'Mail Service', link: '/advanced/mail/' },
+                        { label: 'Storage', link: '/advanced/storage/' },
                         { label: 'Console Framework', link: '/advanced/console/' },
                         { label: 'Admin Panel', link: '/advanced/admin/' },
                         { label: 'Pagination', link: '/advanced/pagination/' },
@@ -505,6 +507,7 @@ export default defineConfig({
                         { label: 'Startup & Shutdown', link: '/guides/startups-and-shutdowns/' },
                         { label: 'Concurrency & Thread Pool', link: '/guides/concurrency/' },
                         { label: 'Caching', link: '/guides/cache/' },
+                        { label: 'Storage', link: '/guides/storage/' },
                         { label: 'Event System', link: '/guides/events/' },
                         { label: 'OpenAPI Overview', link: '/guides/openapi/' },
                         { label: 'Documentation UI', link: '/guides/openapi/documentation-ui/' },

sillo_framework-0.3.0/docs/docs/src/content/docs/advanced/context-binding.md

@@ -0,0 +1,152 @@
+---
+title: "Instance Registry"
+description: "The shared mechanism behind current_storage(), current_mail(), and every setup_x() that follows — a plain slot filled at startup, reachable from anywhere"
+---
+
+> Internal engineering reference for a small piece of infrastructure shared
+> across subsystems.
+>
+> Source: `core/sillo/_internals/registry.py` (~90 lines)
+
+---
+
+## 1. The problem
+
+Every `setup_x(app, config)` in the framework follows the same shape: build
+one long-lived instance, put it on `app.state`, register lifecycle hooks,
+return it. `setup_record`, `setup_work`, `setup_mail`, `setup_storage` all do
+exactly this.
+
+Getting the instance back is where they used to diverge. A handler could hold
+a closure over it, or reach through `request.base_app.state["storage"]` — both
+fine when there is a request in hand and the code holding it does not mind an
+import shaped by that. Neither works well for the routes module that wants to
+call `bucket(...)` without importing the application that built it (a
+circular import, since the application is what registers the routes), and
+neither works *at all* for a queue job or a script, where there is no request
+and often no `app` object lying around either.
+
+The keys were also picked independently per subsystem —
+`app.state["storage"]`, `app.state["mail_client"]`, `app.state["record"]` —
+untyped strings a typo in either the write or the read silently breaks.
+
+## 2. What this is, and what it deliberately is not
+
+`InstanceRegistry` is a plain slot: `register(instance)` fills it,
+`current(...)` reads it back, and asking before anything was registered raises
+a `NotConfiguredError` naming the `setup_x` call that was skipped, rather than
+returning `None` for code to accept as if it were valid.
+
+```python
+class InstanceRegistry(Generic[T]):
+    def __init__(self, label: str) -> None:
+        self._label = label
+        self._instance: T | None = None
+
+    def register(self, instance: T) -> None:
+        self._instance = instance
+
+    def current(self, *, setup: str, example: str) -> T:
+        if self._instance is None:
+            raise NotConfiguredError(...)
+        return self._instance
+```
+
+That is the whole mechanism. Two things it is not, on purpose:
+
+**Not a `ContextVar`.** An earlier version of this bound the instance per
+request, with a small ASGI middleware setting and resetting a
+`contextvars.ContextVar` around each call — the same trick
+[`sillo_inertia`](https://github.com/sillohq/inertia) uses for
+`current_inertia()`, where it is the right answer: an Inertia response *is* a
+function of the request answering it, and there is no such thing as rendering
+one outside of one. Mail and storage are different — a queue job sending a
+receipt or a script backfilling a bucket has no request to bind from, and
+those are not edge cases for either subsystem, they are close to half its
+traffic. Tying the lookup to the request lifecycle would have solved the
+import problem and reintroduced the exact "how do I reach this from a
+background job" problem the design was meant to remove. Registering once, at
+startup, removes the request from the question entirely.
+
+**Not per-application.** The registry holds one instance at a time, whichever
+`setup_x` call registered most recently — there is no key, no lookup by
+`app`. This is the same assumption `app.state["storage"]` already made *for
+that application* (one `Storage` per app), made explicit at process scope
+instead: one registered `Storage` at a time, full stop. A process serving two
+applications with two different storage configurations — most often a test
+suite building app after app — gets whichever was set up last, and that is a
+deliberate trade for never needing an application object to do the lookup,
+not an oversight. It has not needed to be anything more: sillo applications
+are one per process in every deployment shape the framework targets.
+
+## 3. Who uses it
+
+| Subsystem | Registry label | Reader |
+|---|---|---|
+| `sillo.storage` | `"storage"` | `current_storage()`, `bucket(name)` |
+| `sillo.mail` | `"mail client"` | `current_mail()`, `send_email(...)` |
+
+Each subsystem owns one `InstanceRegistry[T]` at module scope in its own
+`context.py`, and calls `register(instance)` from its `setup_x` function —
+that is the entire integration cost. `app.state["storage"]` and
+`app.state["mail_client"]` are untouched; this is an addition, not a
+replacement, for code that already holds the application object and would
+rather use it.
+
+```python
+# sillo/storage/context.py
+_registry: InstanceRegistry[Storage] = InstanceRegistry("storage")
+
+def register(storage: Storage) -> None:
+    _registry.register(storage)
+
+def current_storage() -> Storage:
+    return _registry.current(setup="setup_storage", example=_EXAMPLE)
+```
+
+```python
+# sillo/storage/storage.py — inside setup_storage
+storage = Storage(config, secret=secret or _app_secret(app))
+app.state["storage"] = storage
+app.on_shutdown(storage.close)
+register(storage)          # ← the one line each setup_x adds
+```
+
+## 4. The failure mode this was built to avoid
+
+A cache miss that returns `None` — instead of a sentinel distinct from every
+valid cached value — invites code to accept `None` as data. The same shape
+would happen here if `current_storage()` returned `None` before startup: a
+handler that forgot to call `setup_storage` would get an `AttributeError` on
+whatever it tried to do with `None`, three call frames away from the actual
+mistake and looking nothing like it.
+
+`NotConfiguredError` is raised at the point of the mistake, and names the
+`setup_x` call that should have run first:
+
+```
+No storage has been set up yet.
+
+This reads the storage setup_storage registers. Call it during startup,
+before anything asks for the storage back:
+
+    storage = setup_storage(app, StorageConfig(default="attachments", buckets={...}))
+
+If it already runs somewhere, check that this code path executes after it —
+module import order, not request order, decides whether that has happened.
+```
+
+The last line is the one worth reading twice: because registration happens at
+`setup_x` time and not on first request, the failure this actually catches in
+practice is an import-order bug — a module reading `current_storage()` at its
+own import time, before the application module that calls `setup_storage` has
+run.
+
+## 5. Testing
+
+`tests/test_internals/test_registry.py` covers the primitive alone — no app,
+no request, nothing async unless the test itself needs to be — proving
+`register`/`current` work as a plain function call would. `tests/test_storage/test_context.py`
+and `tests/test_mail/test_context.py` cover the wiring: that `setup_storage`
+and `setup_mail` actually call `register`, that the last call in a process
+wins, and that a `NotConfiguredError` names the right subsystem.

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/docs/docs/src/content/docs/advanced/glossary.md

@@ -1265,22 +1265,7 @@ Jinja2-based template engine.
 
 ---
 
-## Frontend & Static Files
-
-### FrontendApp
-
-**Module:** `sillo.frontend`
-
-SPA build directory serving with fallback routing.  Inherits `BaseRouter`.
-
-**Attributes:** `directory` (Path), `fallback` ("auto" | str | bool | None),
-`cache_control`.
-
-**Fallback behaviour:** `"auto"` tries `404.html` then `index.html`.
-
-**Related:** `StaticFiles`, `SilloApp.frontend()`
-
----
+## Static Files
 
 ### StaticFiles
 
@@ -1288,8 +1273,6 @@ SPA build directory serving with fallback routing.  Inherits `BaseRouter`.
 
 Static file serving middleware/router.
 
-**Related:** `FrontendApp`
-
 ---
 
 ## WebSocket

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/docs/docs/src/content/docs/advanced/mail.md

@@ -619,21 +619,53 @@ def get_mail_client(request) -> MailClient:
 ```
 
 Accesses the client stored in `app.state.mail_client` via the request's state
-proxy.
+proxy. Requires a request — `current_mail()` below does not.
+
+### `send_email(...)`
+
+**File:** `core/sillo/mail/client.py`
+
+The way to send mail from a handler, a queue job, or a script — nothing to
+fetch first, no request required:
+
+```python
+from sillo.mail import send_email
+
+async def process_signup(user):  # a queue job, not a handler
+    await send_email(user.email, "Welcome", body="...")
+```
+
+### `current_mail()`
+
+**File:** `core/sillo/mail/context.py`
+
+The client itself, for the two things `send_email(...)` doesn't cover:
+`send_message(message)` for a prebuilt `EmailMessage`, and
+`send_template_email(...)` when its distinct signature reads better than
+`send_email`'s `template_name=`/`template_context=` kwargs. Most code never
+needs this — `send_email(...)` already is `current_mail().send_email(...)`.
+
+`setup_mail` registers the client with `sillo._internals.registry`, the same
+[instance registry](/advanced/context-binding/) `sillo.storage` uses — a
+plain slot filled at startup, not scoped to a request, because mail is sent
+from queue jobs and scripts at least as often as from a handler. The trade
+that makes explicit: the registry holds one client at a time, whichever
+`setup_mail` call registered last. That is exactly the assumption
+`app.state.mail_client` already made — one mail client per application — made
+visible rather than implicit in a lookup key.
 
 ### Usage Pattern
 
 ```python
-from sillo.mail import setup_mail, get_mail_client, MailConfig
+from sillo.mail import setup_mail, send_email, MailConfig
 
 # At startup
 config = MailConfig.for_gmail("user@gmail.com", "app-password")
 setup_mail(app, config)
 
-# In handler
-async def send_welcome(request, response):
-    client = get_mail_client(request)
-    result = await client.send_template_email(
+# In handler, a queue job, or a script
+async def send_welcome(user):
+    result = await send_email(
         to="newuser@example.com",
         subject="Welcome!",
         template_name="welcome",

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/docs/docs/src/content/docs/advanced/security.md

@@ -348,14 +348,14 @@ class CSRFConfig:
 
 ### Token Generation
 
-The middleware uses `itsdangerous.URLSafeSerializer` to sign tokens:
+The middleware uses an internal `URLSafeSerializer` to sign tokens:
 
 ```python
 def _generate_csrf_token(self) -> str:
     return self.serializer.dumps(secrets.token_urlsafe(32))
 ```
 
-A random token is generated with `secrets.token_urlsafe(32)`, then signed with itsdangerous. The signed token is stored in a cookie and must be submitted back in the `X-CSRFToken` header.
+A random token is generated with `secrets.token_urlsafe(32)`, then signed with HMAC-SHA256. The signed token is stored in a cookie and must be submitted back in the `X-CSRFToken` header.
 
 ### Double-Submit Cookie Pattern
 

{sillo_framework-0.2.0 → sillo_framework-0.3.0}/docs/docs/src/content/docs/advanced/sessions.md

@@ -303,12 +303,28 @@ Three methods control when a session expires:
 
 - **`set_expiration_time(expiration: datetime)`** (line 200): Explicit
   override.
-- **`get_expiration_time()`** (line 209): Resolution order:
+- **`get_expiration_time()`**: Resolution order:
   1. Explicit override from `set_expiration_time`
-  2. If `session_permanent` is `False`: `now(utc) + session_expiration_time`
-  3. If `session_permanent` is `True`: `datetime.max` (effectively never)
-  4. Fallback: 7 days if config is unreachable
-- **`has_expired()`** (line 251): `now(utc) > get_expiration_time()`
+  2. If `session_permanent` is `True` (the default):
+     `now(utc) + session_expiration_time`
+  3. If `session_permanent` is `False`: `None` — the cookie goes out with no
+     `Expires` at all, so the browser drops it when it closes
+  4. Fallback: `session_expiration_time`'s default of 86400 if config is
+     unreachable
+- **`has_expired()`**: `now(utc) > get_expiration_time()`, and `False` for a
+  session with no expiry
+
+This used to be inverted — a permanent session got `datetime.max`, so the
+**default** configuration issued a cookie that never expired, and
+`session_expiration_time` applied only to the non-permanent case that did not
+need it.
+
+:::caution[The cookie's expiry is not what protects you]
+`Expires` is a request to the browser. Anyone replaying a captured cookie
+simply does not honour it. For the signed-cookie backend the real bound is
+`SignedSessionManager.max_age`, which is checked against a timestamp inside
+the signature and defaults to `session_expiration_time`.
+:::
 
 ### should_set_cookie
 
@@ -495,11 +511,11 @@ def __init__(self, config=None, secret_key: str | None = None):
     )
 ```
 
-Uses `itsdangerous.URLSafeTimedSerializer` which:
+Uses an internal `URLSafeTimedSerializer` which:
 - Serialises the payload to JSON, then base64url-encodes it.
 - Appends a timestamp.
 - Signs the whole thing with HMAC-SHA256 using the secret key and salt.
-- The salt prevents signature reuse across different itsdangerous contexts.
+- The salt prevents signature reuse across different signing contexts.
 
 ### Signing and Verification
 
@@ -813,7 +829,7 @@ app.use(SessionMiddleware(secret_key="your-secret-key"))
 config = SessionConfig(
     session_cookie_name="app_session",
     session_expiration_time=3600,       # 1 hour
-    session_permanent=False,            # expires with expiration_time
+    session_permanent=False,            # browser-session cookie, no Expires
     session_refresh_each_request=False, # don't refresh on each request
     session_cookie_secure=True,         # HTTPS only
     session_cookie_httponly=True,       # no JavaScript access