python-ddd-framework 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- python_ddd_framework/__init__.py +17 -1
- python_ddd_framework/application/builder.py +38 -32
- python_ddd_framework/application/runtime_hooks.py +5 -3
- python_ddd_framework/application/state.py +2 -0
- python_ddd_framework/auditing/sqlalchemy/mappings.py +29 -0
- python_ddd_framework/auditing/sqlalchemy/module.py +1 -2
- python_ddd_framework/auditing/sqlalchemy/store.py +23 -15
- python_ddd_framework/caching/unit_of_work.py +4 -0
- python_ddd_framework/consumer_docs/README.md +91 -0
- python_ddd_framework/consumer_docs/architecture.md +264 -0
- python_ddd_framework/consumer_docs/development.md +934 -0
- python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/README.md +13 -1
- python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md +18 -29
- python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/module.py.jinja +2 -4
- python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md +33 -54
- python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md +32 -19
- python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/pyproject.toml.jinja +15 -1
- python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md +22 -151
- python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md +38 -541
- python_ddd_framework/domain/__init__.py +5 -0
- python_ddd_framework/domain/aggregates.py +5 -35
- python_ddd_framework/domain/auditing.py +11 -0
- python_ddd_framework/domain/capabilities.py +39 -0
- python_ddd_framework/domain/entities.py +0 -2
- python_ddd_framework/entity_caching/__init__.py +5 -0
- python_ddd_framework/entity_caching/cache.py +95 -0
- python_ddd_framework/entity_caching/contracts.py +22 -0
- python_ddd_framework/entity_caching/module.py +9 -0
- python_ddd_framework/entity_caching/registration.py +131 -0
- python_ddd_framework/events/aggregate.py +6 -13
- python_ddd_framework/events/runtime.py +93 -27
- python_ddd_framework/extensions/__init__.py +2 -0
- python_ddd_framework/extensions/catalog.py +4 -0
- python_ddd_framework/extensions/contracts.py +12 -2
- python_ddd_framework/identity/application.py +2 -4
- python_ddd_framework/identity/domain_rules.py +4 -2
- python_ddd_framework/identity/dtos.py +19 -20
- python_ddd_framework/identity/management.py +14 -11
- python_ddd_framework/identity/models.py +28 -36
- python_ddd_framework/identity/seeding.py +2 -2
- python_ddd_framework/identity/sqlalchemy/mappings.py +132 -0
- python_ddd_framework/identity/sqlalchemy/module.py +1 -11
- python_ddd_framework/identity/sqlalchemy/repository.py +147 -178
- python_ddd_framework/identity/sqlalchemy/session_security.py +8 -9
- python_ddd_framework/identity/sqlalchemy/stores.py +110 -86
- python_ddd_framework/identity/stores.py +5 -5
- python_ddd_framework/invocation/runtime.py +6 -0
- python_ddd_framework/services/__init__.py +2 -1
- python_ddd_framework/services/composition.py +8 -0
- python_ddd_framework/services/convention.py +28 -1
- python_ddd_framework/services/repository.py +31 -29
- python_ddd_framework/services/runtime.py +4 -0
- python_ddd_framework/settings/sqlalchemy/mappings.py +31 -0
- python_ddd_framework/settings/sqlalchemy/module.py +1 -2
- python_ddd_framework/settings/sqlalchemy/store.py +66 -45
- python_ddd_framework/sqlalchemy/__init__.py +8 -6
- python_ddd_framework/sqlalchemy/alembic_runtime/env.py +3 -0
- python_ddd_framework/sqlalchemy/auditing.py +112 -30
- python_ddd_framework/sqlalchemy/conventions.py +54 -0
- python_ddd_framework/sqlalchemy/event_origins.py +163 -0
- python_ddd_framework/sqlalchemy/extensions.py +81 -49
- python_ddd_framework/sqlalchemy/locking.py +22 -0
- python_ddd_framework/sqlalchemy/mapping.py +53 -0
- python_ddd_framework/sqlalchemy/metadata.py +27 -47
- python_ddd_framework/sqlalchemy/metadata_builder.py +26 -20
- python_ddd_framework/sqlalchemy/metadata_fingerprint.py +4 -1
- python_ddd_framework/sqlalchemy/metadata_ownership.py +1 -1
- python_ddd_framework/sqlalchemy/migration.py +3 -5
- python_ddd_framework/sqlalchemy/migration_rendering.py +25 -0
- python_ddd_framework/sqlalchemy/module.py +56 -3
- python_ddd_framework/sqlalchemy/module_migration.py +4 -4
- python_ddd_framework/sqlalchemy/repository.py +139 -64
- python_ddd_framework/sqlalchemy/repository_binding.py +152 -0
- python_ddd_framework/sqlalchemy/session_provider.py +16 -21
- python_ddd_framework/sqlalchemy/tracking.py +231 -0
- python_ddd_framework/sqlalchemy/types.py +25 -0
- python_ddd_framework/sqlalchemy/unit_of_work.py +110 -6
- python_ddd_framework/unit_of_work/contracts.py +13 -6
- python_ddd_framework/unit_of_work/lifecycle.py +3 -0
- python_ddd_framework/unit_of_work/manager.py +17 -4
- python_ddd_framework-0.10.1.dist-info/METADATA +363 -0
- {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/RECORD +87 -70
- {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/WHEEL +1 -1
- python_ddd_framework-0.10.1.dist-info/licenses/LICENSE +21 -0
- python_ddd_framework/auditing/sqlalchemy/models.py +0 -31
- python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/models/base.py.jinja +0 -7
- python_ddd_framework/identity/sqlalchemy/models.py +0 -104
- python_ddd_framework/settings/sqlalchemy/models.py +0 -36
- python_ddd_framework-0.9.0.dist-info/METADATA +0 -619
- python_ddd_framework-0.9.0.dist-info/licenses/LICENSE +0 -7
- /python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/{models → mappings}/__init__.py.jinja +0 -0
- {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/entry_points.txt +0 -0
- {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/licenses/src/python_ddd_framework/background_jobs/pgqueuer/UPSTREAM_LICENSE.txt +0 -0
|
@@ -1,10 +1,24 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Project architecture
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Record actual application boundaries and confirmed decisions here. Resolve the installed framework version through the [project lookup procedure](development.md#framework-documentation).
|
|
4
4
|
|
|
5
|
-
[
|
|
5
|
+
[Operations](../README.md) · [Working rules](../AGENTS.md) · [Development](development.md)
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
<a id="framework-reference"></a>
|
|
8
|
+
|
|
9
|
+
## Framework reference
|
|
10
|
+
|
|
11
|
+
Use [Framework documentation](development.md#framework-documentation) to locate:
|
|
12
|
+
|
|
13
|
+
- `python_ddd_framework/consumer_docs/architecture.md#ownership-and-dependencies` — ownership and dependency contracts.
|
|
14
|
+
- `python_ddd_framework/consumer_docs/architecture.md#business-module-boundaries` — framework layer boundaries.
|
|
15
|
+
- `python_ddd_framework/consumer_docs/development.md#implementation-workflow` — how to select and implement the needed capabilities.
|
|
16
|
+
|
|
17
|
+
Read the relevant capability contract and usage together. A framework example does not establish this application's business rules. Report conflicts before affected changes.
|
|
18
|
+
|
|
19
|
+
<a id="initial-composition"></a>
|
|
20
|
+
|
|
21
|
+
## Initial composition
|
|
8
22
|
|
|
9
23
|
The initial project is a Host without business modules. `pddd add module <name>` adds a DDD skeleton with the full responsibility directories and necessary composition. Business rules, services, tables, endpoints, and tests are added only from confirmed requirements; no order example is generated.
|
|
10
24
|
|
|
@@ -19,153 +33,10 @@ The initial project is a Host without business modules. `pddd add module <name>`
|
|
|
19
33
|
|
|
20
34
|
The Host initially selects PostgreSQL persistence, identity, auditing, Redis capabilities, settings, background jobs, and observability integrations. Read its dependency declarations or run `pddd inspect` for the actual composition. Installing a framework dependency does not enable a module or start its resources.
|
|
21
35
|
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
A `basic` module has `contracts/` and `services/`: implementation depends on the public Protocol; a consuming Module declares its dependency and injects the service. Ordinary transient DI retains native REQUEST scope and has no implicit application-service interception or HTTP exposure. It requires no database or Redis provider.
|
|
25
|
-
|
|
26
|
-
A `ddd` module uses the following dependency direction:
|
|
27
|
-
|
|
28
|
-
```text
|
|
29
|
-
application -> domain -> domain_shared
|
|
30
|
-
application -> application_contracts -> domain_shared
|
|
31
|
-
http_api -> application_contracts
|
|
32
|
-
sqlalchemy -> domain
|
|
33
|
-
|
|
34
|
-
Host composes application, sqlalchemy, and http_api modules.
|
|
35
|
-
```
|
|
36
|
-
|
|
37
|
-
| Layer | Owns | Keep outside this layer |
|
|
38
|
-
| --- | --- | --- |
|
|
39
|
-
| `domain_shared` | Shared values, typed message schemas, error definitions, permission names, and business constants. | Host configuration, persistence, and transport behavior. |
|
|
40
|
-
| `domain` | Aggregates, state transitions, events, repository contracts, setting definitions, and seed contributors. | ORM models, HTTP requests, and concrete infrastructure providers. |
|
|
41
|
-
| `application_contracts` | Input/output DTOs and public service Protocols. | Service policies, implementation details, and ORM types. |
|
|
42
|
-
| `application` | Use cases, authorization policies, event handlers, typed job handlers, workers, and integration behavior. | Database mappings and Host-specific provider selection. |
|
|
43
|
-
| `sqlalchemy` | ORM models, repository implementations, model registration, and owned migrations. | Business policy belonging to aggregates or application services. |
|
|
44
|
-
| `http_api` | Service exposure and explicit HTTP/WebSocket transport declarations. | Direct persistence access and duplicated use-case logic. |
|
|
45
|
-
|
|
46
|
-
The application layer depends on domain and application contracts. The HTTP layer consumes contracts; it does not import the application implementation. The persistence layer implements domain repository contracts. Framework types and selected native Python libraries remain available where appropriate to these responsibilities.
|
|
47
|
-
|
|
48
|
-
HTTP exposure contributes the ContractsModule dependency to the normal graph. Typed realtime messages own their versioned names and payload fields in the shared layer; application handlers and HTTP sockets map business events/results explicitly. Message schemas do not import application DTOs, and the framework owns only the envelope and process-local delivery queue. Job schedules reference their registered Job type/definition and typed payload instead of duplicating persistent task identity.
|
|
49
|
-
|
|
50
|
-
Immutable values shared by domain objects and public DTOs belong in `domain_shared/value_objects`; values used only inside Domain belong in `domain/value_objects`. Contracts must not depend on Domain to reuse a value. Keep one definition owner.
|
|
51
|
-
|
|
52
|
-
Cross-module access uses public service contracts and explicit Module dependencies. A module owns its own data and migrations. Shared database deployment does not authorize another module to query its tables. Keep internal collaboration contracts separate from end-user service contracts where the caller and authorization semantics differ; `IntegrationService` requires its own contract and is not exposed over HTTP.
|
|
53
|
-
|
|
54
|
-
The [development guide](development.md#module-layout-and-coding-rules) owns the complete directory and naming rules. When those use cases exist, separate query, management, approval, and item contracts by caller needs. Internal reporting uses a separate integration contract and implementation when its caller and authorization boundary differ. HTTP keeps its existing paths and operation identities through public route overrides when Python services move.
|
|
55
|
-
|
|
56
|
-
Business Modules explicitly depend on the framework capabilities they use. Domain seed contributors depend on `DataSeedingModule`, permission definitions on `AuthorizationModule`, application services on `ApplicationServicesModule`, and HTTP declarations on `FastApiModule`. Host provider selection does not repair a missing business-module dependency. Capability definitions use typed module declarations; their catalogs and runtime state belong to each Application. Every Host and six-layer Module explicitly declares the seven framework hooks. Synchronous configuration phases only compose the application; asynchronous initialization phases follow dependency-first barriers, and shutdown closes resources in reverse dependency order. Empty hooks use `pass`. The skeleton has no workers, hosted services, or schedules to enable.
|
|
57
|
-
|
|
58
|
-
## Mandatory design principles
|
|
59
|
-
|
|
60
|
-
Apply all seven principles that are relevant to a code or architecture change during implementation and review, together with the DDD rules below. An abstraction must serve a real responsibility, public contract, variation point, or reuse need. Counts of files, classes, or interfaces are not evidence of good design.
|
|
61
|
-
|
|
62
|
-
| Principle | Required implementation and review behavior |
|
|
63
|
-
| --- | --- |
|
|
64
|
-
| Single responsibility | Organize by stable capability, owner, and reason to change. Give public contracts/values, mutable state, orchestration, external I/O, and resource lifecycles explicit owners. Split independent responsibilities; related immutable values, enums, and exceptions may remain together. Do not centralize unrelated state or lifetimes in a generic service. |
|
|
65
|
-
| Open/closed | Use existing Module declarations, DI, and native extension points for implementations that satisfy the current contract. Avoid accumulating provider branches in core use cases. A business-semantic change still needs contract review and authorization; do not anticipate hypothetical changes with plugin layers or compatibility paths. |
|
|
66
|
-
| Liskov substitution | Implementations of a contract must preserve its preconditions, postconditions, and invariants, including errors, cancellation, idempotency, and cleanup. Do not require stronger inputs, weaken outcomes, or return success for unsupported behavior. Review replacements against the caller's contract, not just their signatures. |
|
|
67
|
-
| Interface segregation | Separate public contracts by caller use case, permissions, and lifecycle needs. A caller should depend only on the capability it needs. Avoid an all-purpose service interface and mechanical one-method interfaces. |
|
|
68
|
-
| Dependency inversion | Domain and use cases depend on contracts owned by the relevant capability; persistence and external integrations implement those boundaries. The Host selects providers and composes them. Domain/Contracts must not depend on Host, HTTP, or concrete persistence. Reuse framework abstractions directly. |
|
|
69
|
-
| Law of Demeter | Obtain facts and request operations through direct collaborators' public contracts. Do not reach through another module into its implementation, ORM, tables, or mutable internals. Aggregate changes pass through the root. Do not add a forwarding facade merely to shorten a call chain. |
|
|
70
|
-
| Composition reuse | Prefer injected collaborators, composition, and existing framework capabilities. Use inheritance for a real type relationship or native extension point. Avoid base classes combining permissions, transactions, domain state, and external communication. |
|
|
71
|
-
|
|
72
|
-
State belongs to its domain or runtime owner; orchestration coordinates those owners without absorbing their rules. A lifecycle owner must await actual release of its resources. The Host remains a composition root, and stable contracts never depend back on orchestration or infrastructure. Use a class for identity, state, lifecycle, ownership, or a real variation point; keep a stateless internal algorithm private to its capability. These constraints do not require extra layers, wrappers, or unused interfaces. Record and review changes using the [design and delivery checks](development.md#design-and-delivery-checks).
|
|
73
|
-
|
|
74
|
-
## Mandatory DDD rules
|
|
75
|
-
|
|
76
|
-
These constraints apply when a capability models aggregates. The module README owns its actual business language and invariants; documentation examples do not define its requirements.
|
|
77
|
-
|
|
78
|
-
| Boundary | Required behavior and review criterion |
|
|
79
|
-
| --- | --- |
|
|
80
|
-
| Application and aggregate | Application services authorize, load, coordinate, and save through existing contracts. State transitions and entity/value invariants must run through domain operations. Do not assign aggregate business fields or reproduce their transition rules in Application. Caller permissions and expected-version checks remain Application responsibilities. |
|
|
81
|
-
| Aggregate root and children | Change an aggregate's internal entities and collections through the root's business operations so it can enforce the aggregate's invariants. Do not return mutable internals that let callers bypass those operations. Persistence may reconstitute stored state through the domain construction boundary; reconstitution must not manufacture new creation events or become a business-write shortcut. |
|
|
82
|
-
| Domain repository and persistence | Design domain repository operations around the aggregate's identity and lifecycle, not one repository per table. Domain contracts use domain values and aggregates; keep ORM rows, Session, SQL expressions, and driver-specific values in persistence. Map database scalar subclasses to the native domain value at that boundary. Keep query projections in their declared read responsibility rather than weakening the aggregate contract. |
|
|
83
|
-
| Cross-aggregate consistency | Before implementing a write spanning aggregates, identify the participating owners, what commits atomically, and any later effects. Record concurrency, failure-after-commit, duplicate/retry, and idempotency behavior. A local UoW may coordinate multiple aggregates when that is the confirmed requirement; do not impose one aggregate per transaction mechanically. Cross-module collaboration still uses public contracts, and local events do not promise durable distributed delivery. |
|
|
84
|
-
| Business evidence | For each changed invariant, the module README must identify its rule owner, business operation, and a concrete rejection example, linking the relevant source and verification. Record unverified cases and open decisions explicitly. Directory placement, type checks, and passing unrelated tests do not by themselves prove a business rule. |
|
|
85
|
-
|
|
86
|
-
## Global settings ownership
|
|
87
|
-
|
|
88
|
-
Settings owns global definitions, reads, conditional writes, and clearing overrides. Domain Modules contribute definitions under `domain/settings`; the Host selects persistence and management HTTP. Business services decide when to read and apply values. Source precedence is runtime override, Host configuration, then definition default, filtered by the definition's allowed sources.
|
|
89
|
-
|
|
90
|
-
Management visibility and permissions govern the generic management service. Internal business services own their authorization; all writes still enforce definition ownership, value validation, and version checks. Settings commits independently of an outer business UoW, and reset retains a fresh version record. It does not own component refresh, notifications, reconciliation, retries, or application status. Follow the [usage recipe](development.md#global-settings) for concrete declarations and calls.
|
|
91
|
-
|
|
92
|
-
## Calls, scopes, and transactions
|
|
93
|
-
|
|
94
|
-
A managed service call passes through authorization, validation, ACTION scope, unit-of-work handling, and the final implementation. HTTP and direct service invocation share this pipeline. Inject the public service contract; do not construct implementations to bypass it. A self-call is an ordinary Python call and does not re-enter the pipeline.
|
|
95
|
-
|
|
96
|
-
Dishka owns service lifetimes. Repository implementations use cached REQUEST scope, application-service implementations use cached ACTION scope, and hosted services use cached APP scope. A unit of work independently owns its transaction and Session; REQUEST and ACTION scopes are not themselves transactions.
|
|
97
|
-
|
|
98
|
-
Default read/write transaction behavior follows framework method/HTTP conventions and explicit policies. Manual `begin()` creates and owns missing execution scopes, or reuses a valid existing context. Call `complete()` before exiting; a new transaction never rewrites the ACTION context cache. A flush is not a commit. Keep sessions local to the owning invocation and avoid transactions across external I/O or long waits.
|
|
99
|
-
|
|
100
|
-
Repositories map aggregates and ORM models explicitly. Their `SqlAlchemySessionProvider.operation(..., aggregate=...)` boundary stages version changes and collects aggregate events once. Database optimistic concurrency still protects competing writes; do not replace it with a cache or a distributed lock.
|
|
101
|
-
|
|
102
|
-
Local transactional events run in this order: DOMAIN handlers, flush/version checks, database commit, then AFTER_COMMIT handlers. Outside a UoW, `await events.publish(message)` dispatches immediately and does not claim a transaction was committed. Nontransactional UoWs reject explicit and automatic events before repository writes. A post-commit failure does not roll back committed data. Local events provide neither distributed delivery nor crash recovery.
|
|
103
|
-
|
|
104
|
-
`AggregateRoot.raise_local_event` validates actual field values before enqueueing. The root and nested records must be frozen dataclasses or frozen Pydantic models. Fields may contain native scalar values (`None`, bool, int, float, str, bytes, Decimal, UUID, date, datetime, time, timedelta), stable Enum values, tuples, frozensets, and NamedTuples without extra state. Datetime/time zones must be native timezone/ZoneInfo instances or None. Mutable containers and their subclasses, mapping views, entity references, unsupported custom objects, scalar subclasses, cycles, missing fields, and undeclared instance state are rejected. A mutable-container subclass remains rejected as a root or nested value even when decorated with `frozen=True`, because inherited container operations can still change its contents. Dataclass subclasses must themselves be decorated with `frozen=True`; records cannot declare cached properties or extra slots. Pydantic models cannot use `extra="allow"` or PrivateAttr. Shared immutable children are allowed. Invalid events raise TypeError without changing the queue; valid events are retained without copying. The publisher must respect normal frozen-value semantics. Direct event-bus publication and repository entity-change notifications keep their existing contracts, including entity references.
|
|
105
|
-
|
|
106
|
-
Typed caches inject `DistributedCache[Item]` and take keys/values directly. The value type owns its cache name; the Host owns the Redis prefix and global defaults. Entry options replace the whole default object. `consider_uow=True` stages changes in the concrete UoW and applies them after successful completion; rollback discards them. Redis and PostgreSQL do not share an atomic commit.
|
|
107
|
-
|
|
108
|
-
Batch cache I/O remains serial. The first unhidden Redis error, invalid payload, or cancellation can stop later commands; reads may refresh expiry or delete expired entries. After a database commit, ordinary cache errors allow other pending writes to run, while cancellation stops later commands. `hide_errors` only hides Redis errors.
|
|
109
|
-
|
|
110
|
-
## HTTP streaming and continuous access
|
|
111
|
-
|
|
112
|
-
`HttpRouter` supports synchronous and asynchronous generator endpoints with native FastAPI SSE, JSONL, and `StreamingResponse`. ApplicationService methods retain their existing return contract: they may return a native streaming Response, but do not become generator methods. Native FastAPI/Starlette own encoding and transmission; the framework manages invocation and resource boundaries.
|
|
113
|
-
|
|
114
|
-
| Phase | Owner and invariant |
|
|
115
|
-
| --- | --- |
|
|
116
|
-
| Preparation | Authorization precedes input binding. Dependencies and Filters perform checks and short business calls needed before sending. Function-scoped dependencies exit, business work commits, and preparation ACTION/UoW resources are released before transmission. The framework does not read the first generator item here; code before the first `yield` still runs during iteration. |
|
|
117
|
-
| Transmission | The HTTP transport owner retains REQUEST and supervises production, sending, and access checks. Framework-supervised reads receive the owning task's request identity and invocation permission, without inheriting preparation ACTION/UoW state. Further database work uses an independent short service call or UoW that ends before `yield`. Ordinary child tasks and external threads do not gain that permission. |
|
|
118
|
-
| Cleanup | After production exits, close the source, release preparation subscriptions, and then release REQUEST. Acquire subscriptions through a native request-scoped yield dependency so they are released even if the response generator never starts. Its unstarted `finally` cannot own a subscription acquired elsewhere. Repeated cancellation must not end the wait for actual cleanup; cleanup failures retain their cause. A synchronous generator's running `next()` must eventually return. |
|
|
119
|
-
|
|
120
|
-
Never carry a business Session, transaction, or AnyIO cancellation scope across a response `yield`. A generator's asynchronous `finally` must shield its own awaited cleanup locally; framework-managed close does not protect arbitrary awaits inside an already-unwinding generator. See the [complete example](development.md#http-generators-and-continuous-access).
|
|
121
|
-
|
|
122
|
-
Managed HTTP streams with authorization requirements check access before sending and periodically afterwards, including while idle or blocked by a slow client. Each check uses an independent short REQUEST, refreshes identity and permissions, and releases its services/UoW before returning. HTTP authenticators and permission checkers can inject the native `Request` and make short managed calls; they do not share the long request's cached services or transaction. Checks for one connection are serialized; a due send waits for the check. User/session changes invalidate access. Failure is recorded before sending is cancelled; WebSocket transport also discards queued business frames. WebSocket continuous checks concern its connection endpoint declarations, while `invoke` authorizes each service call separately without accumulating historical permissions.
|
|
123
|
-
|
|
124
|
-
Routes with no authorization requirement or `allow_anonymous` do not opt into HTTP continuous access checks. Shared authorization short-circuits these cases and `authorization.always_allow` before reading the final identity. `always_allow` does not fabricate a user or accept an invalid token; authentication and real-user requirements remain active. An authenticator may call managed methods admitted by these short-circuits, but reading final `CurrentUser` during authentication still raises the authentication-cycle error. An endpoint-injected `CurrentUser` remains its immutable preparation snapshot; new short calls during streaming use the latest checked snapshot.
|
|
125
|
-
|
|
126
|
-
Actual `http.response.start` is the error boundary. Before it, preparation/access failures can use normal error handlers. After it, terminate and record the failure; do not attempt a replacement JSON response. Shared refresh configuration and Host shutdown timeout belong to [README operations and migration](../README.md#streaming-and-access-migration-07-unreleased).
|
|
127
|
-
|
|
128
|
-
## Extension ownership
|
|
129
|
-
|
|
130
|
-
Identity owns core user/role fields, edit versions, and their base migrations. `concurrency_version` protects edits and relationship replacements; `permission_version` only tracks permission state. Password changes, deactivation, and deletion revoke sessions in the same transaction. Login and refresh coordinate through the user's transaction lock; refresh families retain their own lock-before-row mutation order. Consumer modules own only their declared extension columns/indexes and project-local revisions.
|
|
131
|
-
|
|
132
|
-
Authorization options belong to this Application. The Host may enable `always_allow` for shared authorization checks, but authentication and real-user business requirements remain separate. The setting does not change token validation, input validation, transaction ownership, or business rules. User creation, editing, and paged results share the same application-local extension models and JSON/column mappings.
|
|
133
|
-
|
|
134
|
-
Reusable modules explicitly open `ExtensionTarget` values through `ExtensionPoints`; ordinary application models need no extension registry. A customer Module depends on the target owner and contributes typed `ExtensionProperties` through `ModelExtensions`. Effective Pydantic models belong to this Application and supply validation, serialization, and OpenAPI before service methods compile, including ordinary nested DTOs, recursive fields, and native generic containers. HTTP values stay inside `extra_properties`; explicit Query/Header/Body metadata remains on the final implementation's effective signature.
|
|
135
|
-
|
|
136
|
-
The persistence Module may reference those same Pydantic fields in `SqlAlchemyModelExtension` using native Column factories. Effective mapper/registry/metadata are Application-local and shared by runtime and migrations. The original module owns its table, Schema, JSON container, and core concurrency columns; the customer extension owns only its declared columns/indexes and local revisions with explicit Alembic `depends_on`. Ownership constrains both object filters and generated operations, including inline create-table columns and table comments. Current extension heads satisfy current dependencies; historical revisions keep their original dependencies. Module dependencies do not imply database prerequisites. Never patch shared framework models or author revisions in installed packages.
|
|
137
|
-
|
|
138
|
-
## Configuration and lifecycle
|
|
139
|
-
|
|
140
|
-
The Host selects the environment through `{{ cookiecutter.host_environment_variable }}` and uses `PDDD_` for business environment variables. Nested fields use `__`. Optional `app.yaml` supplies shared values; `app.<environment>.yaml` supplies environment-specific values. Environment variables override file inputs; explicit Host CLI inputs and overrides have their documented higher precedence.
|
|
141
|
-
|
|
142
|
-
Modules bind typed `BaseOptions` models with `context.configure(...)`; services inject `Options[T]`. Startup options and mutable runtime settings have separate purposes. `SettingProvider` reads settings; conditional management updates use the current version token.
|
|
143
|
-
|
|
144
|
-
`MessagingModule` owns bounded in-process channels and their lifecycle. Each message type has
|
|
145
|
-
one declared channel and a cached ACTION Handler binding. Consumption creates a fresh
|
|
146
|
-
REQUEST/ACTION through the hosted bridge; idle receive holds no transaction. Closing admission
|
|
147
|
-
still permits previously accepted work through one-use reservations. Failure/deadline handling
|
|
148
|
-
waits for handler/UoW/finalizer exit. Only pending replaceable snapshots may coalesce. Messages
|
|
149
|
-
are independent of local events, durable Jobs and WebSocket delivery; see
|
|
150
|
-
[usage](development.md#in-process-messages).
|
|
151
|
-
|
|
152
|
-
An Application owns its runtime state, DI container, connections, and background execution. Module definitions can be shared; mutable runtime state cannot. No global application registry or service locator is required.
|
|
153
|
-
|
|
154
|
-
Module initialization precedes selected hosted services and background execution. Shutdown waits for real cleanup. The Host does not migrate or seed the database. `dev-init` prepares local infrastructure, while explicit `db` commands own migration and seed operations.
|
|
155
|
-
|
|
156
|
-
## Background work and external boundaries
|
|
157
|
-
|
|
158
|
-
- Durable jobs use typed, versioned payloads and the PostgreSQL provider. Transactional enqueue must use the same configured connection as the surrounding unit of work. External side effects remain the job's idempotency responsibility.
|
|
159
|
-
- Periodic workers are explicitly registered. No workers are generated. When adding one, configuration cannot enable a worker disabled in its class declaration.
|
|
160
|
-
- Execution modes are `host`, `shared`, and `exclusive`. Spawned processes compose their own Application; they do not inherit a live Session or container.
|
|
161
|
-
- A `HostedService` owns long-lived SDKs or threads, their failures, recovery, and actual shutdown. It is opt-in; background-process instances need explicit selection. Shutdown has global barriers: close ordinary admission, await `stopping`, close remaining admission, drain accepted work, then release resources in `stop` before Module/container cleanup. Only successfully started services prepare; all touched services clean up. External callbacks use the separate, temporary stopping context, never an upgraded startup context.
|
|
162
|
-
- Redis business locks are leases. Preserve cancellation and cleanup when ownership is lost; a lease is not a transaction, fencing guarantee, or exactly-once guarantee.
|
|
163
|
-
- In-process channels preserve SDK input during stopping only for declared `stopping_owners` and a current hook context passed to `send/submit`. The channel Module depends on the service owner. Admission permissions are Application-local and temporary; accepted work retains its reservation until execution or a reported non-execution outcome, with unchanged capacity and per-message scopes.
|
|
164
|
-
- WebSocket delivery targets currently connected clients. The native process-local transport has no cross-process backplane, offline replay, or delivery acknowledgment. HTTP streams follow the [preparation, transmission, and cleanup boundaries](#http-streaming-and-continuous-access).
|
|
165
|
-
- Liveness and readiness report lifecycle state, not continuous infrastructure availability. Trace export is disabled in the generated development configuration until explicitly configured.
|
|
36
|
+
<a id="application-decisions"></a>
|
|
166
37
|
|
|
167
|
-
##
|
|
38
|
+
## Application decisions
|
|
168
39
|
|
|
169
|
-
|
|
40
|
+
The initial Host contains no customer business capability. As modules are implemented, record confirmed business boundaries, cross-module collaboration, data ownership, deployment/provider choices and the reasons for significant decisions. Link the owning module README instead of copying its rules. Derive the complete dependency graph from Module declarations and package metadata rather than maintaining a second inventory here.
|
|
170
41
|
|
|
171
|
-
|
|
42
|
+
Keep this file current when those decisions change. Framework guarantees and usage recipes remain in the installed consumer guides; upgrades do not rewrite this project file.
|