tempest-fastapi-sdk 0.320.0__tar.gz → 0.321.0__tar.gz

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/CHANGELOG.md

@@ -7,6 +7,49 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.321.0] — 2026-10-21
+
+### Added
+
+- Upload direto sob o prefixo do titular no `SubjectObjectStorage`:
+  `presign_put(subject_id, name, *, expires=timedelta(minutes=15))` assina o
+  `PUT` de `key(subject_id, name)`; `stat(subject_id, name)` devolve o
+  `ObjectStat`; `read(subject_id, name, *, max_bytes=None)` lê o objeto e,
+  com `max_bytes`, pede ao storage só esse tanto (leitura com `Range` pelo
+  `stream_object(..., length=max_bytes)`) e para de ler ali mesmo se o
+  storage mandar mais — passe `limite + 1` e compare o tamanho para saber se
+  o objeto passou do limite sem trazê-lo inteiro. `max_bytes` menor que `1`
+  é `ValueError`. Os três validam nome e titular como o `put` e o `presign`,
+  propagam o erro do cliente sem tradução (`S3Error` com `NoSuchKey` para
+  objeto que não existe, medido contra MinIO em
+  `tests/privacy/test_storage_live.py`) e, com o storage desligado
+  (`STORAGE_ENABLED=false`), recusam com `IntegrationDisabledException`. O
+  consumidor deixa de chamar `storage.client.presigned_put_url(storage.key(...))`
+  à mão, que contornava o escopo por titular.
+- `FakeObjectStorageClient` ganhou `presigned_put_url` (URL determinística
+  `https://fake-storage/<bucket>/<key>?method=PUT&expires=<s>`),
+  `stat_object` (tamanho, ETag MD5 e o content type/metadata dados ao
+  `put_object`, que agora são guardados; `raw` é `None`) e `stream_object`
+  (respeita `offset`/`length`, em pedaços de `FAKE_STREAM_CHUNK_SIZE`).
+  Chave inexistente nos dois últimos levanta `FileNotFoundError`
+  (`"NoSuchKey: <key>"`), no lugar do `S3Error` do cliente real. O
+  `fail_next` cobre as três chamadas.
+
+### Changed
+
+- **O protocolo `SubjectStorageClient` ganhou três membros:**
+  `presigned_put_url`, `stat_object` e `stream_object` (assinaturas do
+  `AsyncMinIOClient`). `AsyncMinIOClient` e `FakeObjectStorageClient` já
+  cumprem. Um cliente próprio que implemente o protocolo e seja passado ao
+  `SubjectObjectStorage` deixa de passar no type-checker até ganhar os três —
+  em runtime nada muda enquanto os métodos novos do storage não forem
+  chamados.
+
+### Security
+
+- Piso do `pypdf` (extra `pdf-read` e os que o incluem) sobe para `>=6.21.1`:
+  CVE-2026-113786, CVE-2026-113792 e CVE-2026-113793 em 6.20.0. Lock em 6.21.2.
+
 ## [0.320.0] — 2026-10-20
 
 ### Added

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-fastapi-sdk
-Version: 0.320.0
+Version: 0.321.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -63,7 +63,7 @@ Requires-Dist: prometheus-client>=0.26.0; extra == 'all'
 Requires-Dist: psutil>=7.2.2; extra == 'all'
 Requires-Dist: pyjwt>=2.13.0; extra == 'all'
 Requires-Dist: pyotp>=2.10.0; extra == 'all'
-Requires-Dist: pypdf>=6.16.2; extra == 'all'
+Requires-Dist: pypdf>=6.21.1; extra == 'all'
 Requires-Dist: python-multipart>=0.0.32; extra == 'all'
 Requires-Dist: pywebpush>=2.5.0; extra == 'all'
 Requires-Dist: pyyaml>=6.0.3; extra == 'all'
@@ -180,7 +180,7 @@ Requires-Dist: weasyprint>=69.0; extra == 'pdf'
 Provides-Extra: pdf-layout
 Requires-Dist: pdfplumber>=0.11.7; extra == 'pdf-layout'
 Provides-Extra: pdf-read
-Requires-Dist: pypdf>=6.16.2; extra == 'pdf-read'
+Requires-Dist: pypdf>=6.21.1; extra == 'pdf-read'
 Provides-Extra: postgres
 Requires-Dist: asyncpg>=0.31.0; extra == 'postgres'
 Provides-Extra: prometheus
@@ -433,7 +433,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX and the `data-confirm` listener locally, no CDN); `htmx()` / `aria()` / `data()` / `confirm()` (typed builders for the `hx-*` / `aria-*` / `data-*` `attrs` map); `FlashMiddleware` + `flash` / `get_flashes` (signed read-once flash cookie), `redirect_back` (Referer validated against host and prefix), `register_html_error_handlers` (error page on GET, flash + 303 on POST, JSON kept for the API); `make_web_app_router` (serve a compiled static/wasm `tempestweb build` as a router, SPA history fallback, `304 Not Modified` on `If-None-Match` / `If-Modified-Since`, `immutable=` globs or an `immutable.json` in the build for year-long `immutable` caching of content-addressed paths), `build_web_app` (host a server-mode build as a WS/SSE sub-app, `theme=` handing a palette to every session's `App`, which the components its `view` builds resolve against), `detect_build_mode` |
 | `tempest_fastapi_sdk.ui` *(extra: `[ssr]`)* | The interface layer, mirroring a service's `src/ui/`: `ui.pages` (`Page` with class-level `stylesheets` / `head` / `title_suffix`, `ErrorPage`), `ui.layout` (`Shell` with `width="full"`, `Grid`), `ui.components` (`Card`, `Alert`, `DataTable`, `TableColumn`, `Pagination`, `EmptyState`, `FlashMessages`, `NavBar`, `component_stylesheet`), `ui.forms` (`form_for`, `form_spec_for`, `render_form`, `parse_form`, `form_dependency`, `FormResult`, `form_stylesheet` — a form generated from a Pydantic schema and read back into it, hidden fields and `UploadFile` uploads included), `ui.css` (`StyleSheet`, `Rule`, `Media`, `ThemeTokens`, `cls`, `make_css_router`, `StyleSheet.url`), `app_stylesheet` |
 | `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`; download through the app with `download_response(key, request=...)`, which honours `Range` and revalidation, `accel_redirect_response` for nginx `X-Accel-Redirect`, and `serve_object`, which picks between them by the constructor's `accel_redirect` — `STORAGE_ACCEL_REDIRECT` / `STORAGE_ACCEL_PREFIX` through `storage_kwargs()`), `ObjectStat`, `PutObjectItem`, batch delete `remove_objects` → `ObjectDeleteError` — async MinIO/S3 facade |
-| `tempest_fastapi_sdk.privacy` *(`SubjectObjectStorage` needs `[minio]`)* | Data subject export and erasure (LGPD art. 18): `SubjectGraph` derives from `MetaData` the tables a delete of the subject's root row reaches by `ON DELETE CASCADE` — `tables()`, `export(session, id)` (JSON-ready rows, secret columns left out), `count(session, id)`, `condition(table, id)`, and `violations()` listing every foreign key into the closure that neither cascades nor is a justified `SET NULL` in `retained` (`tempest_fastapi_sdk.testing.assert_subject_graph_valid` makes it a CI guard); `SubjectObjectStorage` keeps a subject's objects under `<prefix>/<id>/` and `delete_all` erases the prefix in S3 batch deletes (`SubjectErasureError` lists refused keys) |
+| `tempest_fastapi_sdk.privacy` *(`SubjectObjectStorage` needs `[minio]`)* | Data subject export and erasure (LGPD art. 18): `SubjectGraph` derives from `MetaData` the tables a delete of the subject's root row reaches by `ON DELETE CASCADE` — `tables()`, `export(session, id)` (JSON-ready rows, secret columns left out), `count(session, id)`, `condition(table, id)`, and `violations()` listing every foreign key into the closure that neither cascades nor is a justified `SET NULL` in `retained` (`tempest_fastapi_sdk.testing.assert_subject_graph_valid` makes it a CI guard); `SubjectObjectStorage` keeps a subject's objects under `<prefix>/<id>/`, signs direct uploads under that prefix (`presign_put`), verifies them with `stat` and a bounded `read(max_bytes=...)` (S3 `Range`), and `delete_all` erases the prefix in S3 batch deletes (`SubjectErasureError` lists refused keys) |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`, `enable_heartbeat` for worker/scheduler container healthchecks checked by `python -m tempest_fastapi_sdk.tasks.heartbeat`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); **jobs** — `BaseJobModel` + `JobStore` (one row per unit of long work: `enqueue`/`claim`/`succeed`/`fail`, `watch` for the screen, `reclaim_stale` + `redispatch_queued`, `succeed(values=...)` for project columns); **cancellation** — `JobStore.cancel`/`cancellation_watch` + `run_cancellable` (cooperative: the request writes `CANCELLED`, the worker aborts the in-flight call at a checkpoint) + `JobCancelledError`; **per-record pipelines** — `StageMap`/`StageStatus` (several independent stages on the record the screen already fetches, with an ownership check before writing); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
 | `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils` (root-scoped by default, `error_500` for the SDK's own `500.log`, `exc_info` — `bool` or `"auto"` — on every level method, and a `TypeError` naming any field that shadows a `LogRecord` attribute), `RetryPolicy`, `RetryLogger`, `async_retry`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`/`InMemoryThrottleBackend`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `sign_path`/`verify_path` (short-lived signed URLs for the app's own routes, stdlib only), `get_client_ip`/`get_client_ip_from_scope` (header value must parse as one IP; `parse_client_ip`), `ACCESS_TOKEN_TYPE`/`REFRESH_TOKEN_TYPE`/`MFA_TOKEN_TYPE`/`token_type_allowed`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition`/`INLINE_SAFE_MEDIA_TYPES` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatingField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`, `LocaleField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `MobilePhoneBRField`, `CEPField`, `PixKeyField` — old names without the suffix kept as deprecated aliases — `PixKeyType`/`detect_pix_key_type`/`is_valid_pix_key`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper. `RetryPolicy` now lives in `tempest_fastapi_sdk.utils.retry` (the backoff curve is not an HTTP idea), still importable from here; `async_retry`, which applies a policy to any coroutine, is new there and imports from `tempest_fastapi_sdk.utils` — its `logger=` is typed `RetryLogger`, a `Protocol` with `warning`/`error`, so a `logging.Logger` and a `LogUtils` are both accepted |

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/README.md

@@ -214,7 +214,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX and the `data-confirm` listener locally, no CDN); `htmx()` / `aria()` / `data()` / `confirm()` (typed builders for the `hx-*` / `aria-*` / `data-*` `attrs` map); `FlashMiddleware` + `flash` / `get_flashes` (signed read-once flash cookie), `redirect_back` (Referer validated against host and prefix), `register_html_error_handlers` (error page on GET, flash + 303 on POST, JSON kept for the API); `make_web_app_router` (serve a compiled static/wasm `tempestweb build` as a router, SPA history fallback, `304 Not Modified` on `If-None-Match` / `If-Modified-Since`, `immutable=` globs or an `immutable.json` in the build for year-long `immutable` caching of content-addressed paths), `build_web_app` (host a server-mode build as a WS/SSE sub-app, `theme=` handing a palette to every session's `App`, which the components its `view` builds resolve against), `detect_build_mode` |
 | `tempest_fastapi_sdk.ui` *(extra: `[ssr]`)* | The interface layer, mirroring a service's `src/ui/`: `ui.pages` (`Page` with class-level `stylesheets` / `head` / `title_suffix`, `ErrorPage`), `ui.layout` (`Shell` with `width="full"`, `Grid`), `ui.components` (`Card`, `Alert`, `DataTable`, `TableColumn`, `Pagination`, `EmptyState`, `FlashMessages`, `NavBar`, `component_stylesheet`), `ui.forms` (`form_for`, `form_spec_for`, `render_form`, `parse_form`, `form_dependency`, `FormResult`, `form_stylesheet` — a form generated from a Pydantic schema and read back into it, hidden fields and `UploadFile` uploads included), `ui.css` (`StyleSheet`, `Rule`, `Media`, `ThemeTokens`, `cls`, `make_css_router`, `StyleSheet.url`), `app_stylesheet` |
 | `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`; download through the app with `download_response(key, request=...)`, which honours `Range` and revalidation, `accel_redirect_response` for nginx `X-Accel-Redirect`, and `serve_object`, which picks between them by the constructor's `accel_redirect` — `STORAGE_ACCEL_REDIRECT` / `STORAGE_ACCEL_PREFIX` through `storage_kwargs()`), `ObjectStat`, `PutObjectItem`, batch delete `remove_objects` → `ObjectDeleteError` — async MinIO/S3 facade |
-| `tempest_fastapi_sdk.privacy` *(`SubjectObjectStorage` needs `[minio]`)* | Data subject export and erasure (LGPD art. 18): `SubjectGraph` derives from `MetaData` the tables a delete of the subject's root row reaches by `ON DELETE CASCADE` — `tables()`, `export(session, id)` (JSON-ready rows, secret columns left out), `count(session, id)`, `condition(table, id)`, and `violations()` listing every foreign key into the closure that neither cascades nor is a justified `SET NULL` in `retained` (`tempest_fastapi_sdk.testing.assert_subject_graph_valid` makes it a CI guard); `SubjectObjectStorage` keeps a subject's objects under `<prefix>/<id>/` and `delete_all` erases the prefix in S3 batch deletes (`SubjectErasureError` lists refused keys) |
+| `tempest_fastapi_sdk.privacy` *(`SubjectObjectStorage` needs `[minio]`)* | Data subject export and erasure (LGPD art. 18): `SubjectGraph` derives from `MetaData` the tables a delete of the subject's root row reaches by `ON DELETE CASCADE` — `tables()`, `export(session, id)` (JSON-ready rows, secret columns left out), `count(session, id)`, `condition(table, id)`, and `violations()` listing every foreign key into the closure that neither cascades nor is a justified `SET NULL` in `retained` (`tempest_fastapi_sdk.testing.assert_subject_graph_valid` makes it a CI guard); `SubjectObjectStorage` keeps a subject's objects under `<prefix>/<id>/`, signs direct uploads under that prefix (`presign_put`), verifies them with `stat` and a bounded `read(max_bytes=...)` (S3 `Range`), and `delete_all` erases the prefix in S3 batch deletes (`SubjectErasureError` lists refused keys) |
 | `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`, `enable_heartbeat` for worker/scheduler container healthchecks checked by `python -m tempest_fastapi_sdk.tasks.heartbeat`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); **jobs** — `BaseJobModel` + `JobStore` (one row per unit of long work: `enqueue`/`claim`/`succeed`/`fail`, `watch` for the screen, `reclaim_stale` + `redispatch_queued`, `succeed(values=...)` for project columns); **cancellation** — `JobStore.cancel`/`cancellation_watch` + `run_cancellable` (cooperative: the request writes `CANCELLED`, the worker aborts the in-flight call at a checkpoint) + `JobCancelledError`; **per-record pipelines** — `StageMap`/`StageStatus` (several independent stages on the record the screen already fetches, with an ownership check before writing); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
 | `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils` (root-scoped by default, `error_500` for the SDK's own `500.log`, `exc_info` — `bool` or `"auto"` — on every level method, and a `TypeError` naming any field that shadows a `LogRecord` attribute), `RetryPolicy`, `RetryLogger`, `async_retry`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`/`InMemoryThrottleBackend`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `sign_path`/`verify_path` (short-lived signed URLs for the app's own routes, stdlib only), `get_client_ip`/`get_client_ip_from_scope` (header value must parse as one IP; `parse_client_ip`), `ACCESS_TOKEN_TYPE`/`REFRESH_TOKEN_TYPE`/`MFA_TOKEN_TYPE`/`token_type_allowed`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition`/`INLINE_SAFE_MEDIA_TYPES` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatingField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`, `LocaleField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `MobilePhoneBRField`, `CEPField`, `PixKeyField` — old names without the suffix kept as deprecated aliases — `PixKeyType`/`detect_pix_key_type`/`is_valid_pix_key`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
 | `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper. `RetryPolicy` now lives in `tempest_fastapi_sdk.utils.retry` (the backoff curve is not an HTTP idea), still importable from here; `async_retry`, which applies a policy to any coroutine, is new there and imports from `tempest_fastapi_sdk.utils` — its `logger=` is typed `RetryLogger`, a `Protocol` with `warning`/`error`, so a `logging.Logger` and a `LogUtils` are both accepted |

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/SHIPPED.md

@@ -3304,7 +3304,9 @@ secret_columns=..., secret_markers=...)` com `tables()`, `export(session, id)`,
 `count(session, id)`, `condition(table, id)`, `exported_columns(table)` e
 `violations()`; `assert_subject_graph_valid` em `tempest_fastapi_sdk.testing`.
 `SubjectObjectStorage(client, prefix=..., bucket=...)` com `put`, `presign`,
-`names`, `delete`, `delete_all` (lote) e `SubjectErasureError`. No storage,
+`names`, `delete`, `delete_all` (lote) e `SubjectErasureError`; upload direto
+com `presign_put`, `stat` e `read(max_bytes=...)` (leitura com `Range`)
+na release seguinte à 0.320.0. No storage,
 `AsyncMinIOClient.remove_objects` + `ObjectDeleteError`. Fora: vínculo sem FK
 (audit trail, id em JSON), raiz com PK composta, busca/cache/backup. Receita
 `recipes/subject-data.md`. Testes: `tests/privacy/`,

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/docs/migration.en.md

@@ -2,6 +2,22 @@
 
 Breaking-change walkthroughs grouped by minor release. Stick to the version that matches what you're upgrading **from**. The release sections are listed newest-first, so on a multi-version jump read and apply them bottom-up.
 
+## 0.321.0 — `SubjectStorageClient` gains three methods
+
+The `SubjectStorageClient` protocol (the type of `SubjectObjectStorage.client`)
+now declares `presigned_put_url`, `stat_object` and `stream_object`, which
+`SubjectObjectStorage` uses for direct upload (`presign_put`, `stat`, `read`).
+`AsyncMinIOClient` and `FakeObjectStorageClient` already implement all three.
+
+### What to do
+
+- A custom client implementing the protocol: add the three methods, with
+  `AsyncMinIOClient`'s signatures (without `stream_object`'s `chunk_size`).
+  Without them, the type checker rejects the client.
+- Code calling `storage.client.presigned_put_url(storage.key(...))`,
+  `stat_object` or `stream_object` directly can switch to `presign_put`,
+  `stat` and `read(max_bytes=...)`, which pin the subject prefix.
+
 ## 0.320.0 — production guard for e-mail and links
 
 With `ENV=production` and e-mail on (a missing `EMAIL_ENABLED` counts as on),

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/docs/migration.md

@@ -2,6 +2,23 @@
 
 Passo a passo das mudanças que quebram compatibilidade, agrupadas por release minor. Siga a versão que casa com aquela **de onde** você está atualizando. As seções estão listadas da mais nova para a mais antiga, então num salto de várias versões leia e aplique-as de baixo para cima.
 
+## 0.321.0 — `SubjectStorageClient` ganha três métodos
+
+O protocolo `SubjectStorageClient` (o tipo do `client` do
+`SubjectObjectStorage`) passa a declarar `presigned_put_url`, `stat_object`
+e `stream_object`, que o `SubjectObjectStorage` usa no upload direto
+(`presign_put`, `stat`, `read`). `AsyncMinIOClient` e
+`FakeObjectStorageClient` já implementam os três.
+
+### O que fazer
+
+- Cliente próprio que implementa o protocolo: implemente os três métodos,
+  com as assinaturas do `AsyncMinIOClient` (sem o `chunk_size` do
+  `stream_object`). Sem eles, o type-checker recusa o cliente.
+- Código que chamava `storage.client.presigned_put_url(storage.key(...))`,
+  `stat_object` ou `stream_object` direto pode trocar por `presign_put`,
+  `stat` e `read(max_bytes=...)`, que fixam o prefixo do titular.
+
 ## 0.320.0 — guard de produção do e-mail e dos links
 
 Com `ENV=production` e o e-mail ligado (`EMAIL_ENABLED` ausente conta como

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/docs/recipes/index.en.md

@@ -493,7 +493,7 @@ come back here to plug in each capability as you need it.
 | **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Comments + ratings »](reviews.md)** | `ReviewService`, `make_reviews_router`, 0–5 star scores with aggregation, threaded comments |
 | **[Computer vision (ONNX) »](vision.md)** | `Detector` / `Classifier` / `Segmenter` + prediction schemas |
-| **[Data subject export and erasure (LGPD) »](subject-data.md)** | `SubjectGraph` (the tables a subject's `DELETE` reaches by cascade, derived from `MetaData`), `export` without secret columns, `violations` + `assert_subject_graph_valid` as a CI guard, `SubjectObjectStorage` (per-subject prefix, batch `delete_all`) |
+| **[Data subject export and erasure (LGPD) »](subject-data.md)** | `SubjectGraph` (the tables a subject's `DELETE` reaches by cascade, derived from `MetaData`), `export` without secret columns, `violations` + `assert_subject_graph_valid` as a CI guard, `SubjectObjectStorage` (per-subject prefix, direct upload with `presign_put` + bounded `read`, batch `delete_all`) |
 | **[Database »](database.md)** | `BaseModel`, `AsyncDatabaseManager`, `BaseRepository` (CRUD + filters + bulk), offset/cursor pagination, mixins, `AlembicHelper`, `SlowQueryLogger` |
 | **[Downloads »](downloads.md)** | `DownloadUtils` — `file_response`, `stream`, `build_content_disposition`, path-traversal safe |
 | **[Enum columns (safe on both databases) »](enum-columns.md)** | `Mapped[MyEnum]` storing the `value`, native `ENUM` on PostgreSQL and a `CHECK` on SQLite, `enum_column()`, `op.replace_enum` + `sync_enum_types` for the migration autogenerate cannot see |

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/docs/recipes/index.md

@@ -509,7 +509,7 @@ aqui pra plugar cada capacidade conforme precisar.
 | **[Erros do app (relatados pelo cliente) »](app-errors.md)** | `make_app_error_model` (FK de usuário nullable, `SET NULL`, `created_at` indexado), `AppErrorService` (trunca em vez de recusar), listagem admin opt-in, intervalo de datas semiaberto |
 | **[Erros no OpenAPI (Swagger) »](openapi-errors.md)** | `error_responses`, `@raises`, `TempestAPIRouter`, `ErrorResponseSchema`, `tempest openapi-errors --fix` |
 | **[Escolhendo o modelo »](models.md)** | `TextModel` / `EmbeddingModel` / `RerankerModel` / `VisionModel` / `ImageModel` / `SpeechToTextModel` / `TextToSpeechModel` — ids do Hub com nome, e a tabela de caso de uso por trás de cada escolha |
-| **[Exportação e exclusão de titular (LGPD) »](subject-data.md)** | `SubjectGraph` (tabelas que o `DELETE` do titular alcança por cascata, derivadas da `MetaData`), `export` sem colunas secretas, `violations` + `assert_subject_graph_valid` como guard de CI, `SubjectObjectStorage` (prefixo por titular, `delete_all` em lote) |
+| **[Exportação e exclusão de titular (LGPD) »](subject-data.md)** | `SubjectGraph` (tabelas que o `DELETE` do titular alcança por cascata, derivadas da `MetaData`), `export` sem colunas secretas, `violations` + `assert_subject_graph_valid` como guard de CI, `SubjectObjectStorage` (prefixo por titular, upload direto com `presign_put` + `read` limitado, `delete_all` em lote) |
 | **[Fakes (sem provedor real) »](fakes.md)** | `FakePixProvider`, `FakeCardProvider`, `FakePayoutProvider`, `FakeTextBackend`, `FakeModerationBackend`, `FakePushDispatcher`, `FakeEmailUtils`, `FakeGeocodingBackend`, `FakeRoutingBackend`, `FakeWebSearchBackend`, `FakeObjectStorageClient` — onze costuras sem credencial e sem rede, dirigíveis (`advance`, `flag`, `fail_next`) e inspecionáveis |
 | **[Feature flags »](feature-flags.md)** | `FeatureFlags`, backends env/Redis/composto, `make_flag_dependency` |
 | **[Fila e Tarefas »](queue-tasks.md)** | FastStream (`AsyncBrokerManager`), TaskIQ (`AsyncTaskBrokerManager`), `AsyncTaskScheduler`, outbox transacional |

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/docs/recipes/subject-data.en.md

@@ -488,6 +488,111 @@ asyncio.run(main())
 `client.objects` shows what is left in the default bucket and
 `client.deleted` what went, in order.
 
+### Direct upload under the subject prefix
+
+Evidence photo, document, avatar: the app uploads the file **straight to
+S3**, without the bytes crossing the API. The server signs the URL, the app
+does the `PUT`, and the server then checks what arrived before accepting it.
+All three pieces live on `SubjectObjectStorage`, under the same subject
+prefix — so the uploaded file also shows up in `names` and in `delete_all`:
+
+- **`presign_put(subject_id, name, expires=...)`** returns the `PUT` URL of
+  `key(subject_id, name)`. Defaults to 15 minutes, the same as
+  `AsyncMinIOClient.presigned_put_url`.
+- **`stat(subject_id, name)`** returns the `ObjectStat` (size, content type,
+  ETag, metadata) without downloading the object.
+- **`read(subject_id, name, max_bytes=...)`** reads the object. With
+  `max_bytes`, it asks the store for only that much (a `Range` read) and
+  stops reading there even if the store sends more.
+
+```python
+import asyncio
+from uuid import uuid4
+
+from tempest_fastapi_sdk.privacy import SubjectObjectStorage
+from tempest_fastapi_sdk.testing.fakes import FakeObjectStorageClient
+
+MAX_PHOTO_BYTES: int = 5 * 1024 * 1024
+JPEG_MAGIC: bytes = b"\xff\xd8\xff"
+
+client = FakeObjectStorageClient()
+storage = SubjectObjectStorage(client, prefix="users")
+
+
+async def start_upload(user_id: int) -> tuple[str, str]:
+    """Sign the PUT of a name the server chose."""
+    name = f"uploads/{uuid4().hex}.jpg"
+    return name, await storage.presign_put(user_id, name)
+
+
+async def accept_upload(user_id: int, name: str) -> str | None:
+    """Check what the app uploaded and keep it under a final name."""
+    stat = await storage.stat(user_id, name)
+    if stat.size > MAX_PHOTO_BYTES:
+        return None
+    data = await storage.read(user_id, name, max_bytes=MAX_PHOTO_BYTES + 1)
+    if len(data) > MAX_PHOTO_BYTES or not data.startswith(JPEG_MAGIC):
+        return None
+    key = await storage.put(
+        user_id, "photos/latest.jpg", data, content_type="image/jpeg"
+    )
+    await storage.delete(user_id, name)
+    return key
+
+
+async def main() -> None:
+    """Direct upload, verification and acceptance, with no MinIO."""
+    name, url = await start_upload(42)
+    print(storage.key(42, name) in url, "method=PUT" in url)
+    await client.put_object(
+        storage.key(42, name), JPEG_MAGIC + b"photo", content_type="image/jpeg"
+    )
+    print(await accept_upload(42, name))
+    print(await storage.names(42))
+
+    name, _ = await start_upload(42)
+    await client.put_object(storage.key(42, name), b"x" * (MAX_PHOTO_BYTES + 1))
+    print(await accept_upload(42, name))
+
+
+asyncio.run(main())
+```
+
+```text
+True True
+users/42/photos/latest.jpg
+['photos/latest.jpg']
+None
+```
+
+- **The server picks the name** (`uploads/<uuid>.jpg`). The app never sends
+  a key or a prefix: the URL only reaches the subject prefix the server
+  signed.
+- **Here `client.put_object` plays the app.** In production it is an HTTP
+  `PUT` to the URL, with the file as the body.
+- **`stat` first, bounded `read` after.** `stat` turns down the large file
+  without downloading anything. But between `stat` and `read` the object can
+  be swapped for another one (the URL is still valid), so `read` asks for
+  `MAX_PHOTO_BYTES + 1`: `len(data) > MAX_PHOTO_BYTES` means "too large",
+  without ever pulling the rest into memory.
+- **The URL signs neither size nor content type.** The app sends whatever it
+  wants; the check decides (here, size and the start of a JPEG). That is why
+  the checked bytes go to a final name with `put`, and the provisional
+  upload goes away with `delete`.
+- **A missing object** (the app asked for the URL and never uploaded) makes
+  `stat` and `read` raise the client's error, untranslated: `S3Error` (code
+  `NoSuchKey`) from `AsyncMinIOClient`, `FileNotFoundError` from
+  `FakeObjectStorageClient`.
+- **Storage disabled** (`STORAGE_ENABLED=false`): all three raise
+  `IntegrationDisabledException` (`503`), like `put` and `delete_all`.
+
+!!! warning "`SubjectStorageClient` change"
+    The protocol gained `presigned_put_url`, `stat_object` and
+    `stream_object`. `AsyncMinIOClient` and `FakeObjectStorageClient` already
+    satisfy it; your own client implementing the protocol must add all three
+    to keep passing the type-checker.
+
+
 ## Putting both together in a service
 
 Delete the files **before** the root row. If the store fails, the subject's
@@ -596,3 +701,6 @@ nested `IN (SELECT ...)` along the cascade path. It works in `select`,
   nothing is left.
 - `SubjectObjectStorage` keeps files under `<prefix>/<id>/` and `delete_all`
   deletes the prefix in batch, without touching another subject.
+- Direct upload: `presign_put` signs the `PUT` under the subject prefix,
+  `stat` and `read(max_bytes=limit + 1)` check what arrived without pulling a
+  large file whole into memory.

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/docs/recipes/subject-data.md

@@ -488,6 +488,111 @@ asyncio.run(main())
 `client.objects` mostra o que sobrou no bucket padrão e `client.deleted` o que
 saiu, em ordem.
 
+### Upload direto sob o prefixo do titular
+
+Foto de evidência, documento, avatar: o app sobe o arquivo **direto para o
+S3**, sem os bytes passarem pela API. O servidor assina a URL, o app faz o
+`PUT`, e depois o servidor confere o que chegou antes de aceitar. As três
+peças moram no `SubjectObjectStorage`, sob o mesmo prefixo do titular — então
+o arquivo enviado também sai no `names` e no `delete_all`:
+
+- **`presign_put(subject_id, name, expires=...)`** devolve a URL de `PUT` de
+  `key(subject_id, name)`. Default de 15 minutos, o mesmo do
+  `AsyncMinIOClient.presigned_put_url`.
+- **`stat(subject_id, name)`** devolve o `ObjectStat` (tamanho, content type,
+  ETag, metadata) sem baixar o objeto.
+- **`read(subject_id, name, max_bytes=...)`** lê o objeto. Com `max_bytes`,
+  pede ao storage só esse tanto (leitura com `Range`) e para de ler ali
+  mesmo se o storage mandar mais.
+
+```python
+import asyncio
+from uuid import uuid4
+
+from tempest_fastapi_sdk.privacy import SubjectObjectStorage
+from tempest_fastapi_sdk.testing.fakes import FakeObjectStorageClient
+
+MAX_PHOTO_BYTES: int = 5 * 1024 * 1024
+JPEG_MAGIC: bytes = b"\xff\xd8\xff"
+
+client = FakeObjectStorageClient()
+storage = SubjectObjectStorage(client, prefix="users")
+
+
+async def start_upload(user_id: int) -> tuple[str, str]:
+    """Assina o PUT de um nome que o servidor escolheu."""
+    name = f"uploads/{uuid4().hex}.jpg"
+    return name, await storage.presign_put(user_id, name)
+
+
+async def accept_upload(user_id: int, name: str) -> str | None:
+    """Confere o que o app subiu e guarda sob um nome definitivo."""
+    stat = await storage.stat(user_id, name)
+    if stat.size > MAX_PHOTO_BYTES:
+        return None
+    data = await storage.read(user_id, name, max_bytes=MAX_PHOTO_BYTES + 1)
+    if len(data) > MAX_PHOTO_BYTES or not data.startswith(JPEG_MAGIC):
+        return None
+    key = await storage.put(
+        user_id, "photos/latest.jpg", data, content_type="image/jpeg"
+    )
+    await storage.delete(user_id, name)
+    return key
+
+
+async def main() -> None:
+    """Upload direto, conferência e aceite, sem MinIO."""
+    name, url = await start_upload(42)
+    print(storage.key(42, name) in url, "method=PUT" in url)
+    await client.put_object(
+        storage.key(42, name), JPEG_MAGIC + b"photo", content_type="image/jpeg"
+    )
+    print(await accept_upload(42, name))
+    print(await storage.names(42))
+
+    name, _ = await start_upload(42)
+    await client.put_object(storage.key(42, name), b"x" * (MAX_PHOTO_BYTES + 1))
+    print(await accept_upload(42, name))
+
+
+asyncio.run(main())
+```
+
+```text
+True True
+users/42/photos/latest.jpg
+['photos/latest.jpg']
+None
+```
+
+- **O servidor escolhe o nome** (`uploads/<uuid>.jpg`). O app nunca manda
+  chave nem prefixo: a URL só alcança o prefixo do titular que o servidor
+  assinou.
+- **Aqui o `client.put_object` faz o papel do app.** Em produção é um `PUT`
+  HTTP na URL, com o corpo do arquivo.
+- **`stat` primeiro, `read` limitado depois.** O `stat` recusa o grande sem
+  baixar nada. Mas entre o `stat` e o `read` o objeto pode ser trocado por
+  outro (a URL ainda vale), então o `read` pede `MAX_PHOTO_BYTES + 1`:
+  `len(data) > MAX_PHOTO_BYTES` quer dizer "grande demais", sem nunca trazer
+  o resto para a memória.
+- **A URL não assina tamanho nem content type.** O app manda o que quiser;
+  quem decide se aceita é a conferência (aqui, o tamanho e o começo de um
+  JPEG). Por isso os bytes conferidos vão para um nome definitivo com `put`,
+  e o upload provisório sai com `delete`.
+- **Objeto que não existe** (o app pediu a URL e não subiu) faz o `stat` e o
+  `read` levantarem o erro do cliente, sem tradução: `S3Error` (código
+  `NoSuchKey`) no `AsyncMinIOClient`, `FileNotFoundError` no
+  `FakeObjectStorageClient`.
+- **Storage desligado** (`STORAGE_ENABLED=false`): as três respondem
+  `IntegrationDisabledException` (`503`), como `put` e `delete_all`.
+
+!!! warning "Mudança no `SubjectStorageClient`"
+    O protocolo ganhou `presigned_put_url`, `stat_object` e `stream_object`.
+    `AsyncMinIOClient` e `FakeObjectStorageClient` já cumprem; um cliente seu
+    que implemente o protocolo precisa ganhar os três para continuar passando
+    no type-checker.
+
+
 ## Juntando os dois num service
 
 Apague os arquivos **antes** da linha raiz. Se o storage falhar, a linha do
@@ -597,3 +702,6 @@ linhas do titular naquela tabela — na raiz, a chave primária; nas outras, um
   sobrou.
 - `SubjectObjectStorage` guarda os arquivos sob `<prefix>/<id>/` e
   `delete_all` apaga o prefixo em lote, sem tocar outro titular.
+- Upload direto: `presign_put` assina o `PUT` sob o prefixo do titular,
+  `stat` e `read(max_bytes=limite + 1)` conferem o que chegou sem trazer
+  arquivo grande inteiro para a memória.

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tempest-fastapi-sdk"
-version = "0.320.0"
+version = "0.321.0"
 description = "Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects."
 readme = "README.md"
 requires-python = ">=3.12"
@@ -134,7 +134,7 @@ pdf = [
     "segno>=1.6.6",
 ]
 pdf-read = [
-    "pypdf>=6.16.2",
+    "pypdf>=6.21.1",
 ]
 pdf-layout = [
     # Layout-aware extraction: columns recovered, tables recovered as grids.
@@ -328,7 +328,7 @@ all = [
     "fido2>=2.2.1",
     "weasyprint>=69.0",
     "segno>=1.6.6",
-    "pypdf>=6.16.2",
+    "pypdf>=6.21.1",
     "pdfplumber>=0.11.7",
     "openpyxl>=3.1.5",
     "email-validator>=2.3.0",
@@ -433,7 +433,7 @@ dev = [
     "ruff>=0.16.5",
     "trafilatura>=2.2.0",
     "pymupdf>=1.28.2",
-    "pypdf>=6.16.2",
+    "pypdf>=6.21.1",
     "openpyxl>=3.1.5",
     "types-openpyxl>=3.1.5.20260827",
     "rank-bm25>=0.2.2",

{tempest_fastapi_sdk-0.320.0 → tempest_fastapi_sdk-0.321.0}/tempest_fastapi_sdk/__init__.py

@@ -2103,7 +2103,7 @@ from tempest_fastapi_sdk.websockets import (
     make_websocket_router as make_websocket_router,
 )
 
-__version__: str = "0.320.0"
+__version__: str = "0.321.0"
 
 from tempest_fastapi_sdk.api import (
     OAuthAudienceVerifier as OAuthAudienceVerifier,