diff --git a/.github/scripts/test_alembic_v2_lifecycle.sh b/.github/scripts/test_alembic_v2_lifecycle.sh index b122419df..6c1af686b 100755 --- a/.github/scripts/test_alembic_v2_lifecycle.sh +++ b/.github/scripts/test_alembic_v2_lifecycle.sh @@ -11,4 +11,5 @@ uv run --frozen --extra dev pytest -q \ tests/integration/test_alembic_v2_saved_item_keys.py \ tests/integration/test_alembic_v2_user_types.py \ tests/integration/test_alembic_v2_withheld_area_codes.py \ - tests/integration/test_alembic_v2_shared_report_keys.py + tests/integration/test_alembic_v2_shared_report_keys.py \ + tests/integration/test_alembic_v2_user_dynamics.py diff --git a/changelog.d/v2-user-dynamics.added.md b/changelog.d/v2-user-dynamics.added.md new file mode 100644 index 000000000..ec5336da2 --- /dev/null +++ b/changelog.d/v2-user-dynamics.added.md @@ -0,0 +1 @@ +Let users save named dynamics, as they save policies: `user_dynamics` holds the owner (a signed-in user or a signed-out browser), the country, a dynamic stored in that country, and a name and description. `POST /v2/user-dynamics` saves one (201), refusing an unknown dynamic (404) and another country's (400); `GET /v2/user-dynamics` lists the caller's saved dynamics, optionally for one `dynamic_id`; and `GET`, `PATCH` (rename, or repoint to another dynamic) and `DELETE` `/v2/user-dynamics/{association_id}` act on one, answering 404 for another user's. Saved dynamics are deleted with their user, move to the account at sign-in, and are listed in `dynamics` in `GET /v2/me/export` and the admin saved-items read. A dynamic that users have saved can't be deleted. API v1 doesn't copy v1 saved policies into saved dynamics, since it no longer writes v1 saved policies; the migration of existing rows creates them. diff --git a/docs/engineering/migration-contracts.md b/docs/engineering/migration-contracts.md index 3533d11c3..0f70a2e17 100644 --- a/docs/engineering/migration-contracts.md +++ b/docs/engineering/migration-contracts.md @@ -7,8 +7,8 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | Metric | Count | | --- | ---: | | route group count | 9 | -| workflow count | 19 | -| request count | 103 | +| workflow count | 20 | +| request count | 113 | | db entity count | 6 | | sim flow count | 3 | @@ -19,7 +19,7 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | `health` | `health`, `simulation-gateway-check`, `liveness-check`, `readiness-check`, `deployment` | `none` | `none` | | `specification` | `specification` | `none` | `none` | | `metadata` | `metadata`, `countries`, `datasets`, `economy-options`, `model-catalog`, `parameter-values`, `parameters`, `regions`, `tax-benefit-model-versions`, `tax-benefit-models`, `variables` | `metadata` | `none` | -| `policy` | `policy`, `policies`, `dynamics`, `user-policy`, `user-policies` | `policy` | `none` | +| `policy` | `policy`, `policies`, `dynamics`, `user-policy`, `user-policies`, `user-dynamics` | `policy` | `none` | | `household` | `household`, `households`, `household-calculations`, `user-household`, `user-households`, `calculate`, `calculate-full` | `household` | `household` | | `economy` | `economy` | `simulation` | `economy` | | `simulation` | `simulation`, `simulations`, `user-simulations` | `simulation` | `economy` | @@ -77,6 +77,24 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | `PATCH` | `/v2/user-policies/{association_id}?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.legacy_policy_id`, `result.item.policy_id`, `result.item.name`, `result.item.description`, `result.item.baseline`, `result.item.provenance`, `result.item.updated_at` | | `DELETE` | `/v2/user-policies/{association_id}?country_id=us` | 204 | `policy` | `PolicyEngine-Unauthenticated-User` | | +### `user_dynamic_associations_v2` + +- Current contract: `typed_v2_resources` +- Future owner: Users' saved dynamics + +| Method | Path | Status | Route group | Required headers | Stable response fields | +| --- | --- | ---: | --- | --- | --- | +| `POST` | `/v2/user-dynamics?country_id=us` | 201 | `policy` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | +| `GET` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | +| `GET` | `/v2/user-dynamics?country_id=us` | 200 | `policy` | `Authorization` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` | +| `PATCH` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` | +| `DELETE` | `/v2/user-dynamics/{association_id}?country_id=us` | 204 | `policy` | `Authorization` | | +| `POST` | `/v2/user-dynamics?country_id=us` | 201 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | +| `GET` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.country_id`, `result.item.user_id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.created_at`, `result.item.updated_at` | +| `GET` | `/v2/user-dynamics?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.items`, `result.offset`, `result.limit`, `result.has_more` | +| `PATCH` | `/v2/user-dynamics/{association_id}?country_id=us` | 200 | `policy` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.dynamic_id`, `result.item.name`, `result.item.description`, `result.item.updated_at` | +| `DELETE` | `/v2/user-dynamics/{association_id}?country_id=us` | 204 | `policy` | `PolicyEngine-Unauthenticated-User` | | + ### `household_save_read` - Current contract: `api_v1_compatible` @@ -173,8 +191,8 @@ Generated from `policyengine_api/migration_registry.py` and `tests/contract/regi | `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at`, `result.latest_type_change` | | `GET` | `/v2/me?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name`, `result.item.email`, `result.item.created_at`, `result.latest_type_change` | | `PATCH` | `/v2/me?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.id`, `result.item.primary_country`, `result.item.first_name`, `result.item.last_name` | -| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.user`, `result.policies`, `result.households`, `result.simulations`, `result.reports` | -| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.user`, `result.policies`, `result.households`, `result.simulations`, `result.reports` | +| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.user`, `result.policies`, `result.dynamics`, `result.households`, `result.simulations`, `result.reports` | +| `GET` | `/v2/me/export?country_id=us` | 200 | `user_profile` | `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.user`, `result.policies`, `result.dynamics`, `result.households`, `result.simulations`, `result.reports` | | `POST` | `/v2/me/upgrade?country_id=us` | 200 | `user_profile` | `Authorization`, `PolicyEngine-Unauthenticated-User` | `status`, `message`, `result.item.id`, `result.item.user_type`, `result.item.primary_country`, `result.outcome` | | `POST` | `/v2/me/invitations/accept?country_id=us` | 200 | `user_profile` | `Authorization` | `status`, `message`, `result.item.user_type`, `result.item.previous_user_type`, `result.item.type_changed` | | `POST` | `/v2/me/type-changes/{type_change_id}/dismiss?country_id=us` | 204 | `user_profile` | `Authorization` | | diff --git a/docs/engineering/skills/alembic-migrations.md b/docs/engineering/skills/alembic-migrations.md index 25e0b76f2..213a990ee 100644 --- a/docs/engineering/skills/alembic-migrations.md +++ b/docs/engineering/skills/alembic-migrations.md @@ -457,6 +457,8 @@ it publishes that version, with nothing to restore it. Downgrading past the revision is therefore safe only while no version is pruned (no `tax_benefit_model_versions` row has `catalog_values_pruned_at` set). From the head, such a downgrade first runs the later revisions' downgrades: +`d417fe8b1b17`'s drops `user_dynamics` with every saved dynamic (see "API v2 +users' saved dynamics"), `9d1d12a7ac58`'s needs `dynamics` empty (see "API v2 dynamics stored like policies"), `f519a77ba122`'s drops `user_invitations` and needs no recorded change with @@ -1073,3 +1075,44 @@ row. `tests/integration/test_alembic_v2_dynamics.py` checks that nothing else changes, the downgrade and upgrade, both refusals, and the keys and unique rules. +### API v2 users' saved dynamics + +Revision `d417fe8b1b17` (parent `9d1d12a7ac58`) was autogenerated, with no +post-generation corrections apart from `ruff format`, after the model gained +`UserDynamic`. Its ID was chosen with `--rev-id`, so the tests written before it +could name it. It creates `user_dynamics`, users' named saved dynamics, built +like `user_policies` without its v1 reference, `baseline` and `provenance`: + +- `user_id`, a key to `users`, `CASCADE`, indexed: a user's saved dynamics + are deleted with the user, and the sign-in merge moves a browser's to the + account it signs in to. +- `country_id`, a key to `countries`, `RESTRICT`. +- `dynamic_id` (required): with `country_id`, a key to `dynamics (id, + country_id)` (`fk_user_dynamics_dynamic_country`, `RESTRICT`). A saved + dynamic names a dynamic of its own country, and a dynamic that users have + saved can't be deleted. +- `name` (255) and `description` (text), both nullable. +- `(id, country_id)` is unique (`uq_user_dynamics_id_country`), so other + tables can name a saved dynamic of one country. There is no unique rule on + the owner and dynamic: a user may save one dynamic more than once. +- Indexes on `(country_id, user_id, created_at, id)` for a user's listing, + and on `(country_id, dynamic_id)`, which also serves the key's check when a + dynamic is deleted. + +`user_dynamics` has no v1 column, since v1 has no dynamics. API v1 no longer +writes v1 saved policies (their routes were removed on 2026-10-22), so no +copy creates saved dynamics. D4 · 1's migration gives each v1 saved policy that +holds assumption values a saved dynamic with its name, through +`services.v2.user_dynamics.services.create_user_dynamic_in_session`. + +The runtime role reads and writes `user_dynamics`, as it does `user_policies`; +no other role has access. The previous API v1 revision doesn't map the table, +so it keeps working at this revision, and deleting a user through it still +deletes their saved dynamics, through the key's `CASCADE`. Its sign-in merge +doesn't move saved dynamics, though: while it serves after a rollback, a +browser that signs in to an existing account loses its saved dynamics with +its unauthenticated user. The downgrade drops the table with every saved +dynamic, and the dynamics they named stay. +`tests/integration/test_alembic_v2_user_dynamics.py` checks that nothing else +changes, the keys, deletion with the user and the downgrade. + diff --git a/docs/engineering/skills/testing.md b/docs/engineering/skills/testing.md index 579f6f573..37d786785 100644 --- a/docs/engineering/skills/testing.md +++ b/docs/engineering/skills/testing.md @@ -632,6 +632,8 @@ uv run --frozen pytest \ tests/unit/v2/test_user_household_routes.py \ tests/unit/v2/test_user_simulation_report_routes.py \ tests/unit/v2/test_user_policy_service.py \ + tests/unit/v2/test_user_dynamic_routes.py \ + tests/unit/v2/test_user_dynamic_service.py \ tests/unit/v2/test_user_household_service.py \ tests/unit/v2/test_user_account_service.py \ tests/unit/v2/test_unauthenticated_user_service.py \ @@ -658,6 +660,7 @@ V2_MIGRATION_DATABASE_URL="postgresql+psycopg://.../policyengine_v2_alembic_test uv run --frozen pytest \ tests/integration/test_alembic_v2_lifecycle.py \ tests/integration/test_alembic_v2_catalog_tables.py \ + tests/integration/test_alembic_v2_user_dynamics.py \ tests/integration/test_v2_user_identity_persistence.py \ tests/integration/test_v2_user_type_persistence.py -q ``` diff --git a/docs/engineering/skills/typing-only-imports.md b/docs/engineering/skills/typing-only-imports.md index 89675adc7..31ca9a459 100644 --- a/docs/engineering/skills/typing-only-imports.md +++ b/docs/engineering/skills/typing-only-imports.md @@ -44,8 +44,8 @@ name in that annotation at module level. Query dependencies are module-level aliases, such as `CountryQueryDependency`. The signed-in user routes also depend on `require_user`, the authenticator `NativeRouteDependencies` injects into each router, which exists only inside the router builder. Their modules -(`fastapi_routes/v2/me`, `user_households`, `user_policies`, `user_reports` and -`user_simulations`) don't use `from __future__ import annotations`, so +(`fastapi_routes/v2/me`, `user_dynamics`, `user_households`, `user_policies`, +`user_reports` and `user_simulations`) don't use `from __future__ import annotations`, so `Annotated[AccountPrincipal, Depends(require_user)]` is evaluated where the handler is defined, and the names their other annotations use are imported at runtime. With the future import, FastAPI would silently treat `principal` as a diff --git a/docs/generated/migration_contracts.json b/docs/generated/migration_contracts.json index 52e8312de..a85a57283 100644 --- a/docs/generated/migration_contracts.json +++ b/docs/generated/migration_contracts.json @@ -1,10 +1,10 @@ { "metadata": { "db_entity_count": 6, - "request_count": 103, + "request_count": 113, "route_group_count": 9, "sim_flow_count": 3, - "workflow_count": 19 + "workflow_count": 20 }, "route_groups": [ { @@ -53,7 +53,8 @@ "policies", "dynamics", "user-policy", - "user-policies" + "user-policies", + "user-dynamics" ], "sim_flow": null }, @@ -444,6 +445,187 @@ } ] }, + { + "current_contract": "typed_v2_resources", + "future_owner_pr": "Users' saved dynamics", + "name": "user_dynamic_associations_v2", + "requests": [ + { + "expected_status": 201, + "headers": [ + "Authorization" + ], + "method": "POST", + "path": "/v2/user-dynamics?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.country_id", + "result.item.user_id", + "result.item.dynamic_id", + "result.item.name", + "result.item.description", + "result.item.created_at", + "result.item.updated_at" + ] + }, + { + "expected_status": 200, + "headers": [ + "Authorization" + ], + "method": "GET", + "path": "/v2/user-dynamics/{association_id}?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.country_id", + "result.item.user_id", + "result.item.dynamic_id", + "result.item.name", + "result.item.description", + "result.item.created_at", + "result.item.updated_at" + ] + }, + { + "expected_status": 200, + "headers": [ + "Authorization" + ], + "method": "GET", + "path": "/v2/user-dynamics?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.items", + "result.offset", + "result.limit", + "result.has_more" + ] + }, + { + "expected_status": 200, + "headers": [ + "Authorization" + ], + "method": "PATCH", + "path": "/v2/user-dynamics/{association_id}?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.dynamic_id", + "result.item.name", + "result.item.description", + "result.item.updated_at" + ] + }, + { + "expected_status": 204, + "headers": [ + "Authorization" + ], + "method": "DELETE", + "path": "/v2/user-dynamics/{association_id}?country_id=us", + "route_group": "policy", + "stable_response_fields": [] + }, + { + "expected_status": 201, + "headers": [ + "PolicyEngine-Unauthenticated-User" + ], + "method": "POST", + "path": "/v2/user-dynamics?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.country_id", + "result.item.user_id", + "result.item.dynamic_id", + "result.item.name", + "result.item.description", + "result.item.created_at", + "result.item.updated_at" + ] + }, + { + "expected_status": 200, + "headers": [ + "PolicyEngine-Unauthenticated-User" + ], + "method": "GET", + "path": "/v2/user-dynamics/{association_id}?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.country_id", + "result.item.user_id", + "result.item.dynamic_id", + "result.item.name", + "result.item.description", + "result.item.created_at", + "result.item.updated_at" + ] + }, + { + "expected_status": 200, + "headers": [ + "PolicyEngine-Unauthenticated-User" + ], + "method": "GET", + "path": "/v2/user-dynamics?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.items", + "result.offset", + "result.limit", + "result.has_more" + ] + }, + { + "expected_status": 200, + "headers": [ + "PolicyEngine-Unauthenticated-User" + ], + "method": "PATCH", + "path": "/v2/user-dynamics/{association_id}?country_id=us", + "route_group": "policy", + "stable_response_fields": [ + "status", + "message", + "result.item.id", + "result.item.dynamic_id", + "result.item.name", + "result.item.description", + "result.item.updated_at" + ] + }, + { + "expected_status": 204, + "headers": [ + "PolicyEngine-Unauthenticated-User" + ], + "method": "DELETE", + "path": "/v2/user-dynamics/{association_id}?country_id=us", + "route_group": "policy", + "stable_response_fields": [] + } + ] + }, { "current_contract": "api_v1_compatible", "future_owner_pr": "PR 11: Household Migration", @@ -1284,6 +1466,7 @@ "message", "result.user", "result.policies", + "result.dynamics", "result.households", "result.simulations", "result.reports" @@ -1302,6 +1485,7 @@ "message", "result.user", "result.policies", + "result.dynamics", "result.households", "result.simulations", "result.reports" diff --git a/docs/migration/stage-12a-user-login.md b/docs/migration/stage-12a-user-login.md index b7465a3aa..86641cf5a 100644 --- a/docs/migration/stage-12a-user-login.md +++ b/docs/migration/stage-12a-user-login.md @@ -120,7 +120,7 @@ type first, and each operation checks it again in its own transaction. | `GET /v2/admin/users/{user_id}` | One signed-in user. | | `PATCH /v2/admin/users/{user_id}` `{"user_type": …, "expected_user_type": …}`, each `standard`, `author` or `admin` | Changes the type and records the change. The type the user already has changes and records nothing, whatever `expected_user_type` is. Otherwise `expected_user_type`, the type the admin last read, must still be the stored type: when it differs, the change is refused with 409 and nothing is written. Only the type is compared, so a type changed and changed back since the read is not detected. | | `GET /v2/admin/users/{user_id}/user-type-changes` | The user's recorded changes, newest first. | -| `GET /v2/admin/users/{user_id}/saved-items` | Read-only: what the user's own `GET /v2/me/export` returns, the user and every policy, household, simulation and report it saved, in every country. The user's `email` is the one its admin user item shows; its names are the stored ones, as the user's own export has them. | +| `GET /v2/admin/users/{user_id}/saved-items` | Read-only: what the user's own `GET /v2/me/export` returns, the user and every policy, dynamic, household, simulation and report it saved, in every country. The user's `email` is the one its admin user item shows; its names are the stored ones, as the user's own export has them. | | `DELETE /v2/admin/users/{user_id}` | Deletes the user's account and saved records, and the Auth0 users of its sign-in identities, as `DELETE /v2/me` deletes the caller's own (see [Admins' account deletions](#admins-account-deletions)). 204. | An admin user item is `{id, user_type, email, first_name, last_name, @@ -461,7 +461,7 @@ unauthenticated: a signed-in user's row is never locked. | State | Outcome | What happens | | --- | --- | --- | | The identity has no user yet; the browser's unauthenticated user exists | `converted` | The `user_identities` row (issuer, subject, verified email) is inserted pointing at the browser's `users.id`; the user becomes `standard` with `primary_country = country_id`. The ID is unchanged, so every association stays owned. | -| The identity already belongs to signed-in user S; the unauthenticated user exists | `merged` | Every row of `user_policies`, `user_household_associations`, `user_simulation_associations`, and `user_report_associations` owned by the unauthenticated user moves to S with its ID, contents, and timestamps unchanged; then the unauthenticated user is deleted. S keeps its stored type. | +| The identity already belongs to signed-in user S; the unauthenticated user exists | `merged` | Every row of `user_policies`, `user_dynamics`, `user_household_associations`, `user_simulation_associations`, and `user_report_associations` owned by the unauthenticated user moves to S with its ID, contents, and timestamps unchanged; then the unauthenticated user is deleted. S keeps its stored type. | | No unauthenticated user with that ID | `none` | The identity's user is resolved, or provisioned, as on any request. | | The ID names a signed-in user (already converted, or anyone else's) | `none` | That user is never touched; the identity's user is resolved as on any request. | @@ -587,7 +587,7 @@ contract shared with `policyengine-app-v2`. The generated route inventory is in | `GET /v2/me/export` | The user and every association, all countries | The same; `user: null` and empty lists before the first saved record | | `POST /v2/me/upgrade?country_id=` | Requires the header too (422 without it); `{"item": MeItem, "outcome": ...}` | 401 (a bearer token is required) | | `DELETE /v2/me` | 204; deletes data, then the Auth0 user when configured; 409 for the last admin, deleting nothing | 204; deletes data, never calls Auth0 | -| `/v2/user-policies`, `/v2/user-households`, `/v2/user-simulations`, `/v2/user-reports` | POST (201), list, GET, PATCH, DELETE (204), owner-scoped | The same; reads never provision | +| `/v2/user-policies`, `/v2/user-dynamics`, `/v2/user-households`, `/v2/user-simulations`, `/v2/user-reports` | POST (201), list, GET, PATCH, DELETE (204), owner-scoped | The same; reads never provision | | `GET /v2/shared-reports/{id}?country_id=` | No credential: any user's saved report in that country, without its owner (404 when none) | The same | ### Shared reports @@ -1101,8 +1101,8 @@ The disposable-Postgres suite proves the following: - concurrent upgrades of one browser convert exactly once; - two browsers upgrading into a new account at once share it: one converts, the other merges; -- a merge moves all four association kinds with their IDs, keeps report links - valid, and deletes the unauthenticated user; +- a merge moves every association kind, saved dynamics included, with their + IDs, keeps report links valid, and deletes the unauthenticated user; - a signed-out write waits for a conversion and then gets 401, or, after a merge, starts a new unauthenticated user; - a signed-out account deletion racing a conversion never deletes the diff --git a/migrations/v2/versions/d417fe8b1b17_add_users_saved_dynamics.py b/migrations/v2/versions/d417fe8b1b17_add_users_saved_dynamics.py new file mode 100644 index 000000000..e70f1dea8 --- /dev/null +++ b/migrations/v2/versions/d417fe8b1b17_add_users_saved_dynamics.py @@ -0,0 +1,102 @@ +"""add users' saved dynamics + +Revision ID: d417fe8b1b17 +Revises: 9d1d12a7ac58 +Create Date: 2026-11-19 21:00:24.397454 +Generation: uv run alembic -c alembic-v2.ini revision --autogenerate + +Adds user_dynamics, users' named saved dynamics, built like user_policies +without its v1 reference: the owner (a key to users, CASCADE), the country (a +key to countries, RESTRICT) and a dynamic of that country (a key with the +country to dynamics, RESTRICT), with a name and description. (id, country_id) +is unique, so other tables can name a saved dynamic of one country. Indexed +by owner, by country, owner and creation, and by country and dynamic. The ID +was chosen with --rev-id; the operations are exactly as generated, apart from +ruff format. +""" + +from typing import Sequence, Union + +from alembic import op +import sqlalchemy as sa +import sqlmodel + + +revision: str = "d417fe8b1b17" +down_revision: Union[str, None] = "9d1d12a7ac58" +branch_labels: Union[str, Sequence[str], None] = None +depends_on: Union[str, Sequence[str], None] = None + + +def upgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.create_table( + "user_dynamics", + sa.Column("id", sa.Uuid(), nullable=False), + sa.Column( + "created_at", + sa.DateTime(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.Column( + "updated_at", + sa.DateTime(timezone=True), + server_default=sa.text("now()"), + nullable=False, + ), + sa.Column("user_id", sa.Uuid(), nullable=False), + sa.Column("dynamic_id", sa.Uuid(), nullable=False), + sa.Column( + "country_id", sqlmodel.sql.sqltypes.AutoString(length=2), nullable=False + ), + sa.Column("name", sqlmodel.sql.sqltypes.AutoString(length=255), nullable=True), + sa.Column("description", sa.Text(), nullable=True), + sa.ForeignKeyConstraint( + ["country_id"], + ["countries.id"], + name=op.f("fk_user_dynamics_country_id_countries"), + ondelete="RESTRICT", + ), + sa.ForeignKeyConstraint( + ["dynamic_id", "country_id"], + ["dynamics.id", "dynamics.country_id"], + name="fk_user_dynamics_dynamic_country", + ondelete="RESTRICT", + ), + sa.ForeignKeyConstraint( + ["user_id"], + ["users.id"], + name=op.f("fk_user_dynamics_user_id_users"), + ondelete="CASCADE", + ), + sa.PrimaryKeyConstraint("id", name=op.f("pk_user_dynamics")), + sa.UniqueConstraint("id", "country_id", name="uq_user_dynamics_id_country"), + ) + op.create_index( + "ix_user_dynamics_country_dynamic", + "user_dynamics", + ["country_id", "dynamic_id"], + unique=False, + ) + op.create_index( + "ix_user_dynamics_country_user_created_id", + "user_dynamics", + ["country_id", "user_id", "created_at", "id"], + unique=False, + ) + op.create_index( + op.f("ix_user_dynamics_user_id"), "user_dynamics", ["user_id"], unique=False + ) + # ### end Alembic commands ### + + +def downgrade() -> None: + # ### commands auto generated by Alembic - please adjust! ### + op.drop_index(op.f("ix_user_dynamics_user_id"), table_name="user_dynamics") + op.drop_index( + "ix_user_dynamics_country_user_created_id", table_name="user_dynamics" + ) + op.drop_index("ix_user_dynamics_country_dynamic", table_name="user_dynamics") + op.drop_table("user_dynamics") + # ### end Alembic commands ### diff --git a/policyengine_api/data/v2/migration_target.py b/policyengine_api/data/v2/migration_target.py index 9c4fcbf26..ca6098032 100644 --- a/policyengine_api/data/v2/migration_target.py +++ b/policyengine_api/data/v2/migration_target.py @@ -24,7 +24,7 @@ from collections.abc import Mapping V2_ALEMBIC_DISPOSABLE_TEST = "V2_ALEMBIC_DISPOSABLE_TEST" -V2_ALEMBIC_HEAD_REVISION = "9d1d12a7ac58" +V2_ALEMBIC_HEAD_REVISION = "d417fe8b1b17" DISPOSABLE_DATABASE_NAME = "policyengine_v2_alembic_test" DISPOSABLE_HOSTS = frozenset({"localhost", "127.0.0.1", "::1", "postgres"}) MIGRATION_ROLE = "policyengine_v2_migrator" diff --git a/policyengine_api/data/v2/models/__init__.py b/policyengine_api/data/v2/models/__init__.py index 973eb9c11..d005168b7 100644 --- a/policyengine_api/data/v2/models/__init__.py +++ b/policyengine_api/data/v2/models/__init__.py @@ -18,6 +18,7 @@ # Import in dependency order so every reviewed table registers exactly once. from policyengine_api.data.v2.models.associations import ( # noqa: E402 + UserDynamic, UserHouseholdAssociation, UserPolicy, UserReportAssociation, @@ -173,6 +174,7 @@ "TaxBenefitModelVersion", "UKAreaType", "User", + "UserDynamic", "UserHouseholdAssociation", "UserIdentity", "UserInvitation", diff --git a/policyengine_api/data/v2/models/associations.py b/policyengine_api/data/v2/models/associations.py index 82fab4fa4..b154f690c 100644 --- a/policyengine_api/data/v2/models/associations.py +++ b/policyengine_api/data/v2/models/associations.py @@ -2,8 +2,9 @@ Every saved-item association names its target through a nullable v2 reference, a nullable country-scoped v1 (legacy) reference, or both; a -database check requires at least one. A user's record of a report run they -asked for names the v2 run alone. +database check requires at least one. A saved dynamic names its v2 dynamic +alone, since v1 has no dynamics, and so does a user's record of a report run +they asked for. The simulation and report associations still carry the pre-Stage 12A ``country`` and ``label`` columns. Nothing reads or writes them; they stay @@ -25,7 +26,7 @@ enum_type, ) from policyengine_api.data.v2.models.households import Household -from policyengine_api.data.v2.models.policies import Policy +from policyengine_api.data.v2.models.policies import Dynamic, Policy from policyengine_api.data.v2.models.reports import ReportRunTrigger from policyengine_api.data.v2.models.users import User from policyengine_api.utils.budget_window import BUDGET_WINDOW_MAX_YEARS @@ -177,6 +178,61 @@ class UserPolicy(TimestampedModel, table=True): ) +class UserDynamic(TimestampedModel, table=True): + """A user's saved, named link to a dynamic in the same country. + + Built like ``user_policies`` without its v1 reference: a dynamic holds a + report's model assumptions with no name, and a user's saved dynamic names + it. Deleted with the user; a dynamic that users have saved cannot be + deleted. + """ + + __tablename__ = "user_dynamics" + __table_args__ = ( + sa.UniqueConstraint( + "id", + "country_id", + name="uq_user_dynamics_id_country", + ), + sa.ForeignKeyConstraint( + ["dynamic_id", "country_id"], + ["dynamics.id", "dynamics.country_id"], + name="fk_user_dynamics_dynamic_country", + ondelete="RESTRICT", + ), + sa.Index( + "ix_user_dynamics_country_user_created_id", + "country_id", + "user_id", + "created_at", + "id", + ), + # Also serves the key's check when a dynamic is deleted. + sa.Index( + "ix_user_dynamics_country_dynamic", + "country_id", + "dynamic_id", + ), + ) + + user_id: UUID = Field( + foreign_key="users.id", + ondelete="CASCADE", + index=True, + ) + dynamic_id: UUID + country_id: str = Field( + max_length=2, + foreign_key="countries.id", + ondelete="RESTRICT", + ) + name: str | None = Field(default=None, max_length=255) + description: str | None = Field(default=None, sa_type=sa.Text) + + user: User = Relationship(back_populates="dynamic_associations") + dynamic: Dynamic = Relationship(back_populates="user_associations") + + class UserSimulationAssociation(TimestampedModel, table=True): """A user's saved simulation, named by its v2 or v1 simulation or both. diff --git a/policyengine_api/data/v2/models/countries.py b/policyengine_api/data/v2/models/countries.py index fc3ae8677..dcbc5f277 100644 --- a/policyengine_api/data/v2/models/countries.py +++ b/policyengine_api/data/v2/models/countries.py @@ -5,8 +5,9 @@ row records the calculations its country supports: a household-only country has ``household_enabled`` set and ``society_wide_enabled`` unset. -``users.primary_country`` and the ``country_id`` of households, policies and -the four user association tables reference ``countries.id``. Other v2 country +``users.primary_country`` and the ``country_id`` of households, policies, +dynamics and the five user association tables reference ``countries.id``. +Other v2 country columns do not: the mapping tables that pair v1 records with their v2 copies keep their US-and-UK checks, and the simulation-domain tables, the comparison run tables and the retired association ``country`` columns store unconstrained diff --git a/policyengine_api/data/v2/models/policies.py b/policyengine_api/data/v2/models/policies.py index ba134ed0f..b2fead152 100644 --- a/policyengine_api/data/v2/models/policies.py +++ b/policyengine_api/data/v2/models/policies.py @@ -10,7 +10,7 @@ from policyengine_api.data.v2.models.metadata import TaxBenefitModel if TYPE_CHECKING: - from policyengine_api.data.v2.models.associations import UserPolicy + from policyengine_api.data.v2.models.associations import UserDynamic, UserPolicy from policyengine_api.data.v2.models.households import HouseholdJob from policyengine_api.data.v2.models.metadata import ( ParameterValue, @@ -102,8 +102,9 @@ class Dynamic(TimestampedModel, table=True): policy: every parameter under ``gov.simulation.``, plus the US's top-level ``simulation.`` (``policyengine_api.dynamic_parameters``). It is stored and hashed as a policy is, bound to one catalog version, with - no name or description: a user's saved dynamics name it. Its parameter - values are deleted with it. + no name or description: a user's saved dynamics (``user_dynamics``) name + it. Its parameter values are deleted with it; dynamics that users have + saved cannot be deleted. """ __tablename__ = "dynamics" @@ -156,3 +157,4 @@ class Dynamic(TimestampedModel, table=True): ) simulations: list["Simulation"] = Relationship(back_populates="dynamic") household_jobs: list["HouseholdJob"] = Relationship(back_populates="dynamic") + user_associations: list["UserDynamic"] = Relationship(back_populates="dynamic") diff --git a/policyengine_api/data/v2/models/users.py b/policyengine_api/data/v2/models/users.py index 0a4d55018..f6d4479ca 100644 --- a/policyengine_api/data/v2/models/users.py +++ b/policyengine_api/data/v2/models/users.py @@ -21,6 +21,7 @@ if TYPE_CHECKING: from policyengine_api.data.v2.models.associations import ( + UserDynamic, UserHouseholdAssociation, UserPolicy, UserReportAssociation, @@ -128,6 +129,10 @@ class User(IdentifiedModel, table=True): back_populates="user", cascade_delete=True, ) + dynamic_associations: list["UserDynamic"] = Relationship( + back_populates="user", + cascade_delete=True, + ) simulation_associations: list["UserSimulationAssociation"] = Relationship( back_populates="user", cascade_delete=True, diff --git a/policyengine_api/data/v2/privileges.py b/policyengine_api/data/v2/privileges.py index d468a60d4..c7ddcb0c7 100644 --- a/policyengine_api/data/v2/privileges.py +++ b/policyengine_api/data/v2/privileges.py @@ -335,7 +335,8 @@ def _run_table( # Served countries; the migration that creates the table inserts its rows, # and the Public API reads them. "countries": _access(runtime=READ), - # Users and their saved work (Stage 12A). + # Users and their saved work (Stage 12A), and their saved dynamics. + "user_dynamics": _access(runtime=READ_WRITE), "user_household_associations": _access(runtime=READ_WRITE), "user_identities": _access(runtime=READ_WRITE), "user_policies": _access(runtime=READ_WRITE), diff --git a/policyengine_api/fastapi_routes/dependencies.py b/policyengine_api/fastapi_routes/dependencies.py index e886b9250..0d24ef292 100644 --- a/policyengine_api/fastapi_routes/dependencies.py +++ b/policyengine_api/fastapi_routes/dependencies.py @@ -24,6 +24,7 @@ V2PolicyResourceService, V2StoredReportResourceService, V2StoredSimulationResourceService, + V2UserDynamicResourceService, V2UserHouseholdResourceService, V2UserInvitationResourceService, V2UserPolicyResourceService, @@ -79,6 +80,7 @@ "V2PolicyResourceService", "V2StoredReportResourceService", "V2StoredSimulationResourceService", + "V2UserDynamicResourceService", "V2UserHouseholdResourceService", "V2UserInvitationResourceService", "V2UserPolicyResourceService", @@ -417,6 +419,20 @@ def _default_v2_user_policy_service_factory() -> V2UserPolicyResourceService: ) +def _default_v2_user_dynamic_service_factory() -> V2UserDynamicResourceService: + from policyengine_api.data.v2.database import ( + get_v2_session_factory, + ) + from policyengine_api.services.v2.user_dynamics.database_session import ( + UserDynamicDatabaseSession, + ) + from policyengine_api.services.v2.user_dynamics.services import ( + V2UserDynamicService, + ) + + return V2UserDynamicService(UserDynamicDatabaseSession(get_v2_session_factory())) + + def _default_v2_user_household_service_factory() -> V2UserHouseholdResourceService: from policyengine_api.data.v2.database import ( get_v2_session_factory, @@ -577,6 +593,9 @@ class NativeRouteDependencies: v2_user_policy_service_factory: Callable[[], V2UserPolicyResourceService] | None = ( None ) + v2_user_dynamic_service_factory: ( + Callable[[], V2UserDynamicResourceService] | None + ) = None v2_user_household_service_factory: ( Callable[[], V2UserHouseholdResourceService] | None ) = None @@ -622,6 +641,7 @@ def defaults(cls) -> NativeRouteDependencies: _default_v2_stored_simulation_service_factory ), v2_user_policy_service_factory=(_default_v2_user_policy_service_factory), + v2_user_dynamic_service_factory=_default_v2_user_dynamic_service_factory, v2_user_household_service_factory=( _default_v2_user_household_service_factory ), diff --git a/policyengine_api/fastapi_routes/resource_service_protocols.py b/policyengine_api/fastapi_routes/resource_service_protocols.py index cb710ff6b..6d365a350 100644 --- a/policyengine_api/fastapi_routes/resource_service_protocols.py +++ b/policyengine_api/fastapi_routes/resource_service_protocols.py @@ -4,6 +4,14 @@ from typing import TYPE_CHECKING, Protocol +from policyengine_api.fastapi_routes.saved_item_service_protocols import ( + V2UserDynamicResourceService, + V2UserHouseholdResourceService, + V2UserPolicyResourceService, + V2UserReportResourceService, + V2UserSimulationResourceService, +) + if TYPE_CHECKING: from collections.abc import Sequence from uuid import UUID @@ -53,39 +61,12 @@ AccountUpdateInput, AccountUpgrade, ) - from policyengine_api.services.v2.user_households.types import ( - UserHouseholdCreateFields, - UserHouseholdFilter, - UserHouseholdPage, - UserHouseholdRead, - UserHouseholdUpdateInput, - ) from policyengine_api.services.v2.user_invitations.types import ( AdminInvitationPage, AdminInvitationRead, AdminInvitationSearch, InvitationAcceptance, ) - from policyengine_api.services.v2.user_policies.types import ( - UserPolicyCreateFields, - UserPolicyFilter, - UserPolicyPage, - UserPolicyRead, - UserPolicyUpdateInput, - ) - from policyengine_api.services.v2.user_reports.types import ( - SharedUserReportRead, - UserReportCreateFields, - UserReportPage, - UserReportRead, - UserReportUpdateInput, - ) - from policyengine_api.services.v2.user_simulations.types import ( - UserSimulationCreateFields, - UserSimulationPage, - UserSimulationRead, - UserSimulationUpdateInput, - ) from policyengine_api.services.v2.user_types.types import ( AdminUserPage, AdminUserRead, @@ -94,6 +75,25 @@ ) +__all__ = [ + "V2AccountResourceService", + "V2CountryResourceService", + "V2DynamicResourceService", + "V2HouseholdCalculationResourceService", + "V2HouseholdResourceService", + "V2PolicyResourceService", + "V2StoredReportResourceService", + "V2StoredSimulationResourceService", + "V2UserDynamicResourceService", + "V2UserHouseholdResourceService", + "V2UserInvitationResourceService", + "V2UserPolicyResourceService", + "V2UserReportResourceService", + "V2UserSimulationResourceService", + "V2UserTypeResourceService", +] + + class V2CountryResourceService(Protocol): """Route-independent countries list read for one request.""" @@ -363,260 +363,6 @@ def create_simulation( ... -class V2UserPolicyResourceService(Protocol): - """Route-independent user-policy operations for one request.""" - - def create_user_policy( - self, - *, - principal: AccountPrincipal, - association_input: UserPolicyCreateFields, - ) -> UserPolicyRead: - """Save a policy for the caller, provisioning their user if needed.""" - ... - - def get_user_policy( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> UserPolicyRead: - """Return the caller's association, or raise ``UserPolicyNotFoundError``.""" - ... - - def list_user_policies( - self, - *, - principal: AccountPrincipal, - country_id: str, - policy_filter: UserPolicyFilter | None = None, - offset: int = 0, - limit: int = 100, - ) -> UserPolicyPage: - """Return a page of the caller's associations, optionally for one policy.""" - ... - - def patch_user_policy( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - association_input: UserPolicyUpdateInput, - ) -> UserPolicyRead: - """Update the supplied fields of the caller's association and return it. - - The association keeps its id, owner and creation time. A new - ``legacy_policy_id`` repoints it to another v1 policy; a new ``policy_id`` - repoints it to a v2 policy in the same country and, sent without - ``legacy_policy_id``, clears the v1 reference. - """ - ... - - def delete_user_policy( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> None: - """Delete the caller's association, or raise ``UserPolicyNotFoundError``.""" - ... - - -class V2UserHouseholdResourceService(Protocol): - """Route-independent user-household operations for one request.""" - - def create_user_household( - self, - *, - principal: AccountPrincipal, - association_input: UserHouseholdCreateFields, - ) -> UserHouseholdRead: - """Save a household for the caller, provisioning their user if needed.""" - ... - - def get_user_household( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> UserHouseholdRead: - """Return the caller's association, or raise ``UserHouseholdNotFoundError``.""" - ... - - def list_user_households( - self, - *, - principal: AccountPrincipal, - country_id: str, - household_filter: UserHouseholdFilter | None = None, - offset: int = 0, - limit: int = 100, - ) -> UserHouseholdPage: - """Return a page of the caller's associations, optionally for one household.""" - ... - - def patch_user_household( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - association_input: UserHouseholdUpdateInput, - ) -> UserHouseholdRead: - """Update the supplied fields of the caller's association and return it. - - The association keeps its id, owner and creation time. A new - ``legacy_household_id`` repoints it to another v1 household; a new - ``household_id`` repoints it to a v2 household in the same country and, - sent without ``legacy_household_id``, clears the v1 reference. - """ - ... - - def delete_user_household( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> None: - """Delete the caller's association, or raise ``UserHouseholdNotFoundError``.""" - ... - - -class V2UserSimulationResourceService(Protocol): - """Route-independent user-simulation operations for one request.""" - - def create_user_simulation( - self, - *, - principal: AccountPrincipal, - association_input: UserSimulationCreateFields, - ) -> UserSimulationRead: - """Save a v1 simulation for the caller, provisioning their user if needed.""" - ... - - def get_user_simulation( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> UserSimulationRead: - """Return the caller's association, or raise ``UserSimulationNotFoundError``.""" - ... - - def list_user_simulations( - self, - *, - principal: AccountPrincipal, - country_id: str, - legacy_simulation_id: int | None = None, - offset: int = 0, - limit: int = 100, - ) -> UserSimulationPage: - """Return a page of the caller's associations, optionally for one simulation.""" - ... - - def patch_user_simulation( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - association_input: UserSimulationUpdateInput, - ) -> UserSimulationRead: - """Update the supplied fields of the caller's association and return it. - - A new ``legacy_simulation_id`` repoints it to another v1 simulation. - """ - ... - - def delete_user_simulation( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> None: - """Delete the caller's association, or raise ``UserSimulationNotFoundError``.""" - ... - - -class V2UserReportResourceService(Protocol): - """Route-independent user-report operations for one request.""" - - def create_user_report( - self, - *, - principal: AccountPrincipal, - association_input: UserReportCreateFields, - ) -> UserReportRead: - """Save a v1 report for the caller, provisioning their user if needed. - - Linked saved reforms must be the caller's own. - """ - ... - - def get_user_report( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> UserReportRead: - """Return the caller's association, or raise ``UserReportNotFoundError``.""" - ... - - def get_shared_user_report( - self, - *, - country_id: str, - association_id: UUID, - ) -> SharedUserReportRead: - """Return any user's saved report to a link holder, without its owner. - - Raise ``UserReportNotFoundError`` when the country has no such report. - """ - ... - - def list_user_reports( - self, - *, - principal: AccountPrincipal, - country_id: str, - legacy_report_id: int | None = None, - offset: int = 0, - limit: int = 100, - ) -> UserReportPage: - """Return a page of the caller's associations, optionally for one v1 report.""" - ... - - def patch_user_report( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - association_input: UserReportUpdateInput, - ) -> UserReportRead: - """Update the supplied fields of the caller's association and return it.""" - ... - - def delete_user_report( - self, - *, - principal: AccountPrincipal, - country_id: str, - association_id: UUID, - ) -> None: - """Delete the caller's association, or raise ``UserReportNotFoundError``.""" - ... - - class V2AccountResourceService(Protocol): """Route-independent account operations for one request.""" diff --git a/policyengine_api/fastapi_routes/saved_item_service_protocols.py b/policyengine_api/fastapi_routes/saved_item_service_protocols.py new file mode 100644 index 000000000..144cfa4d5 --- /dev/null +++ b/policyengine_api/fastapi_routes/saved_item_service_protocols.py @@ -0,0 +1,363 @@ +"""Interfaces of the services behind users' saved items, which native routes call. + +Saved policies, dynamics, households, simulations and reports. +``policyengine_api.fastapi_routes.resource_service_protocols`` re-exports +them, and routes and tests import them from there. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Protocol + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_api.services.v2.identity.types import AccountPrincipal + from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicCreateFields, + UserDynamicFilter, + UserDynamicPage, + UserDynamicRead, + UserDynamicUpdateInput, + ) + from policyengine_api.services.v2.user_households.types import ( + UserHouseholdCreateFields, + UserHouseholdFilter, + UserHouseholdPage, + UserHouseholdRead, + UserHouseholdUpdateInput, + ) + from policyengine_api.services.v2.user_policies.types import ( + UserPolicyCreateFields, + UserPolicyFilter, + UserPolicyPage, + UserPolicyRead, + UserPolicyUpdateInput, + ) + from policyengine_api.services.v2.user_reports.types import ( + SharedUserReportRead, + UserReportCreateFields, + UserReportPage, + UserReportRead, + UserReportUpdateInput, + ) + from policyengine_api.services.v2.user_simulations.types import ( + UserSimulationCreateFields, + UserSimulationPage, + UserSimulationRead, + UserSimulationUpdateInput, + ) + + +class V2UserPolicyResourceService(Protocol): + """Route-independent user-policy operations for one request.""" + + def create_user_policy( + self, + *, + principal: AccountPrincipal, + association_input: UserPolicyCreateFields, + ) -> UserPolicyRead: + """Save a policy for the caller, provisioning their user if needed.""" + ... + + def get_user_policy( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> UserPolicyRead: + """Return the caller's association, or raise ``UserPolicyNotFoundError``.""" + ... + + def list_user_policies( + self, + *, + principal: AccountPrincipal, + country_id: str, + policy_filter: UserPolicyFilter | None = None, + offset: int = 0, + limit: int = 100, + ) -> UserPolicyPage: + """Return a page of the caller's associations, optionally for one policy.""" + ... + + def patch_user_policy( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + association_input: UserPolicyUpdateInput, + ) -> UserPolicyRead: + """Update the supplied fields of the caller's association and return it. + + The association keeps its id, owner and creation time. A new + ``legacy_policy_id`` repoints it to another v1 policy; a new ``policy_id`` + repoints it to a v2 policy in the same country and, sent without + ``legacy_policy_id``, clears the v1 reference. + """ + ... + + def delete_user_policy( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> None: + """Delete the caller's association, or raise ``UserPolicyNotFoundError``.""" + ... + + +class V2UserDynamicResourceService(Protocol): + """Route-independent saved-dynamic operations for one request.""" + + def create_user_dynamic( + self, + *, + principal: AccountPrincipal, + association_input: UserDynamicCreateFields, + ) -> UserDynamicRead: + """Save a dynamic for the caller, provisioning their user if needed.""" + ... + + def get_user_dynamic( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> UserDynamicRead: + """Return the caller's saved dynamic, or raise ``UserDynamicNotFoundError``.""" + ... + + def list_user_dynamics( + self, + *, + principal: AccountPrincipal, + country_id: str, + dynamic_filter: UserDynamicFilter | None = None, + offset: int = 0, + limit: int = 100, + ) -> UserDynamicPage: + """Return a page of the caller's saved dynamics, optionally for one dynamic.""" + ... + + def patch_user_dynamic( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + association_input: UserDynamicUpdateInput, + ) -> UserDynamicRead: + """Rename the caller's saved dynamic, or repoint it to another dynamic. + + It keeps its id, owner and creation time; a new ``dynamic_id`` must be + stored in the same country. + """ + ... + + def delete_user_dynamic( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> None: + """Delete the caller's saved dynamic, or raise ``UserDynamicNotFoundError``.""" + ... + + +class V2UserHouseholdResourceService(Protocol): + """Route-independent user-household operations for one request.""" + + def create_user_household( + self, + *, + principal: AccountPrincipal, + association_input: UserHouseholdCreateFields, + ) -> UserHouseholdRead: + """Save a household for the caller, provisioning their user if needed.""" + ... + + def get_user_household( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> UserHouseholdRead: + """Return the caller's association, or raise ``UserHouseholdNotFoundError``.""" + ... + + def list_user_households( + self, + *, + principal: AccountPrincipal, + country_id: str, + household_filter: UserHouseholdFilter | None = None, + offset: int = 0, + limit: int = 100, + ) -> UserHouseholdPage: + """Return a page of the caller's associations, optionally for one household.""" + ... + + def patch_user_household( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + association_input: UserHouseholdUpdateInput, + ) -> UserHouseholdRead: + """Update the supplied fields of the caller's association and return it. + + The association keeps its id, owner and creation time. A new + ``legacy_household_id`` repoints it to another v1 household; a new + ``household_id`` repoints it to a v2 household in the same country and, + sent without ``legacy_household_id``, clears the v1 reference. + """ + ... + + def delete_user_household( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> None: + """Delete the caller's association, or raise ``UserHouseholdNotFoundError``.""" + ... + + +class V2UserSimulationResourceService(Protocol): + """Route-independent user-simulation operations for one request.""" + + def create_user_simulation( + self, + *, + principal: AccountPrincipal, + association_input: UserSimulationCreateFields, + ) -> UserSimulationRead: + """Save a v1 simulation for the caller, provisioning their user if needed.""" + ... + + def get_user_simulation( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> UserSimulationRead: + """Return the caller's association, or raise ``UserSimulationNotFoundError``.""" + ... + + def list_user_simulations( + self, + *, + principal: AccountPrincipal, + country_id: str, + legacy_simulation_id: int | None = None, + offset: int = 0, + limit: int = 100, + ) -> UserSimulationPage: + """Return a page of the caller's associations, optionally for one simulation.""" + ... + + def patch_user_simulation( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + association_input: UserSimulationUpdateInput, + ) -> UserSimulationRead: + """Update the supplied fields of the caller's association and return it. + + A new ``legacy_simulation_id`` repoints it to another v1 simulation. + """ + ... + + def delete_user_simulation( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> None: + """Delete the caller's association, or raise ``UserSimulationNotFoundError``.""" + ... + + +class V2UserReportResourceService(Protocol): + """Route-independent user-report operations for one request.""" + + def create_user_report( + self, + *, + principal: AccountPrincipal, + association_input: UserReportCreateFields, + ) -> UserReportRead: + """Save a v1 report for the caller, provisioning their user if needed. + + Linked saved reforms must be the caller's own. + """ + ... + + def get_user_report( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> UserReportRead: + """Return the caller's association, or raise ``UserReportNotFoundError``.""" + ... + + def get_shared_user_report( + self, + *, + country_id: str, + association_id: UUID, + ) -> SharedUserReportRead: + """Return any user's saved report to a link holder, without its owner. + + Raise ``UserReportNotFoundError`` when the country has no such report. + """ + ... + + def list_user_reports( + self, + *, + principal: AccountPrincipal, + country_id: str, + legacy_report_id: int | None = None, + offset: int = 0, + limit: int = 100, + ) -> UserReportPage: + """Return a page of the caller's associations, optionally for one v1 report.""" + ... + + def patch_user_report( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + association_input: UserReportUpdateInput, + ) -> UserReportRead: + """Update the supplied fields of the caller's association and return it.""" + ... + + def delete_user_report( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> None: + """Delete the caller's association, or raise ``UserReportNotFoundError``.""" + ... diff --git a/policyengine_api/fastapi_routes/v2/admin_users/response_models.py b/policyengine_api/fastapi_routes/v2/admin_users/response_models.py index 5c71db9c4..6f48e2415 100644 --- a/policyengine_api/fastapi_routes/v2/admin_users/response_models.py +++ b/policyengine_api/fastapi_routes/v2/admin_users/response_models.py @@ -163,8 +163,8 @@ class AdminUserSavedItemsResponse(StrictAdminUserAPIModel): """The response for a signed-in user's saved items, in every country. ``result`` is what the user's own ``GET /v2/me/export`` returns: the user, - with the email admins see for it, and every policy, household, simulation - and report it saved. + with the email admins see for it, and every policy, dynamic, household, + simulation and report it saved. """ status: Literal["ok"] = "ok" diff --git a/policyengine_api/fastapi_routes/v2/admin_users/routes.py b/policyengine_api/fastapi_routes/v2/admin_users/routes.py index 85b974b74..dac5cfbf1 100644 --- a/policyengine_api/fastapi_routes/v2/admin_users/routes.py +++ b/policyengine_api/fastapi_routes/v2/admin_users/routes.py @@ -373,13 +373,14 @@ def list_user_type_changes( "/users/{user_id}/saved-items", response_model=AdminUserSavedItemsResponse, summary=( - "Read a signed-in user's saved policies, households, simulations and " - "reports" + "Read a signed-in user's saved policies, dynamics, households, " + "simulations and reports" ), description=( "Admins only; read-only. Returns what the user's own GET /v2/me/export " "returns, in every country: the user, with the email admins see for " - "it, and every saved policy, household, simulation and report. An " + "it, and every saved policy, dynamic, household, simulation and " + "report. An " "unauthenticated user's ID is not found (404). Each read is recorded " "with the admin's and the user's IDs." ), diff --git a/policyengine_api/fastapi_routes/v2/me/response_models.py b/policyengine_api/fastapi_routes/v2/me/response_models.py index c07059023..676284163 100644 --- a/policyengine_api/fastapi_routes/v2/me/response_models.py +++ b/policyengine_api/fastapi_routes/v2/me/response_models.py @@ -8,6 +8,9 @@ from pydantic import BaseModel, ConfigDict +from policyengine_api.fastapi_routes.v2.user_dynamics.response_models import ( + UserDynamicItem, +) from policyengine_api.fastapi_routes.v2.user_households.response_models import ( UserHouseholdItem, ) @@ -148,7 +151,7 @@ class InvitationAcceptanceResult(StrictAccountAPIModel): class MeExportResult(StrictAccountAPIModel): - """A user and every policy, household, simulation and report it saved. + """A user and every policy, dynamic, household, simulation and report it saved. The export covers every country, not only the requested one. ``GET /v2/me/export`` returns the current user's, and @@ -158,6 +161,7 @@ class MeExportResult(StrictAccountAPIModel): # Null when an unauthenticated user has not saved anything yet. user: MeItem | None policies: list[UserPolicyItem] + dynamics: list[UserDynamicItem] households: list[UserHouseholdItem] simulations: list[UserSimulationItem] reports: list[UserReportItem] @@ -168,6 +172,7 @@ def from_export(cls, export: AccountExport) -> MeExportResult: return cls( user=None if export.user is None else MeItem.from_read(export.user), policies=[UserPolicyItem.from_read(item) for item in export.policies], + dynamics=[UserDynamicItem.from_read(item) for item in export.dynamics], households=[ UserHouseholdItem.from_read(item) for item in export.households ], diff --git a/policyengine_api/fastapi_routes/v2/routes.py b/policyengine_api/fastapi_routes/v2/routes.py index 589bcc73d..21ed48387 100644 --- a/policyengine_api/fastapi_routes/v2/routes.py +++ b/policyengine_api/fastapi_routes/v2/routes.py @@ -47,6 +47,9 @@ from policyengine_api.fastapi_routes.v2.simulations.routes import ( build_v2_simulation_router, ) +from policyengine_api.fastapi_routes.v2.user_dynamics.routes import ( + build_v2_user_dynamic_router, +) from policyengine_api.fastapi_routes.v2.user_households.routes import ( build_v2_user_household_router, ) @@ -79,6 +82,7 @@ def build_v2_router( router.include_router(build_v2_user_simulation_router(dependencies)) router.include_router(build_v2_user_household_router(dependencies)) router.include_router(build_v2_user_policy_router(dependencies)) + router.include_router(build_v2_user_dynamic_router(dependencies)) router.include_router(build_v2_household_router(dependencies)) router.include_router(build_v2_household_calculation_router(dependencies)) router.include_router(build_v2_policy_router(dependencies)) diff --git a/policyengine_api/fastapi_routes/v2/user_dynamics/__init__.py b/policyengine_api/fastapi_routes/v2/user_dynamics/__init__.py new file mode 100644 index 000000000..ffac33c08 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/user_dynamics/__init__.py @@ -0,0 +1 @@ +"""FastAPI adapters for users' saved dynamics (``/v2/user-dynamics``).""" diff --git a/policyengine_api/fastapi_routes/v2/user_dynamics/request_models.py b/policyengine_api/fastapi_routes/v2/user_dynamics/request_models.py new file mode 100644 index 000000000..087987676 --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/user_dynamics/request_models.py @@ -0,0 +1,14 @@ +"""Strict HTTP request models for users' saved dynamics.""" + +from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicCreateFields, + UserDynamicUpdateInput, +) + + +class UserDynamicCreateRequest(UserDynamicCreateFields): + """Saved-dynamic fields; the owner is taken from the request credential.""" + + +class UserDynamicPatchRequest(UserDynamicUpdateInput): + """Explicitly supplied fields to rename or repoint a saved dynamic.""" diff --git a/policyengine_api/fastapi_routes/v2/user_dynamics/response_models.py b/policyengine_api/fastapi_routes/v2/user_dynamics/response_models.py new file mode 100644 index 000000000..596ba0f6c --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/user_dynamics/response_models.py @@ -0,0 +1,100 @@ +"""Strict HTTP response models for users' saved dynamics.""" + +from __future__ import annotations + +from datetime import datetime +from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar +from uuid import UUID + +from pydantic import BaseModel, ConfigDict + +from policyengine_api.fastapi_routes.v2.user_resources_support import ( + USER_RESOURCE_ERROR_RESPONSES, +) +from policyengine_api.query_parameters import CountryId + +if TYPE_CHECKING: + from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicPage, + UserDynamicRead, + ) + + +class StrictUserDynamicAPIModel(BaseModel): + """Strict saved-dynamic contract with dataclass conversion support.""" + + model_config = ConfigDict(extra="forbid", from_attributes=True) + + +class UserDynamicItem(StrictUserDynamicAPIModel): + """A dynamic saved by a v2 user, with the user's name and description for it. + + Unlike dynamics, saved dynamics can be renamed, repointed or deleted. + """ + + id: UUID + country_id: CountryId + user_id: UUID + dynamic_id: UUID + name: str | None + description: str | None + created_at: datetime + updated_at: datetime + + @classmethod + def from_read(cls, item: UserDynamicRead) -> UserDynamicItem: + """Build the response item by validating the service read record's fields.""" + return cls.model_validate(item) + + +class UserDynamicDetailResult(StrictUserDynamicAPIModel): + """Result holding one saved dynamic in ``item``.""" + + item: UserDynamicItem + + +class UserDynamicPageResult(StrictUserDynamicAPIModel): + """One page of saved dynamics, oldest first. + + ``offset`` and ``limit`` echo the request; when ``has_more`` is true, ask + for the next page with ``offset + limit``. + """ + + items: list[UserDynamicItem] + offset: int + limit: int + has_more: bool + + @classmethod + def from_page(cls, page: UserDynamicPage) -> UserDynamicPageResult: + """Build the response page from a service page, converting each item.""" + return cls( + items=[UserDynamicItem.from_read(item) for item in page.items], + offset=page.offset, + limit=page.limit, + has_more=page.has_more, + ) + + +ResultT = TypeVar("ResultT") + + +class UserDynamicSuccessResponse(StrictUserDynamicAPIModel, Generic[ResultT]): + """Success envelope: ``status`` "ok", a null ``message`` and the ``result``.""" + + status: Literal["ok"] = "ok" + message: None = None + result: ResultT + + +class UserDynamicDetailResponse(UserDynamicSuccessResponse[UserDynamicDetailResult]): + """Success response holding one saved dynamic.""" + + +class UserDynamicPageResponse(UserDynamicSuccessResponse[UserDynamicPageResult]): + """Success response holding one page of saved dynamics.""" + + +USER_DYNAMIC_ERROR_RESPONSES: dict[int | str, dict[str, Any]] = ( + USER_RESOURCE_ERROR_RESPONSES +) diff --git a/policyengine_api/fastapi_routes/v2/user_dynamics/routes.py b/policyengine_api/fastapi_routes/v2/user_dynamics/routes.py new file mode 100644 index 000000000..5598634bf --- /dev/null +++ b/policyengine_api/fastapi_routes/v2/user_dynamics/routes.py @@ -0,0 +1,219 @@ +"""Native FastAPI routes for users' saved dynamics.""" + +from collections.abc import Callable +from typing import Annotated +from uuid import UUID + +from fastapi import APIRouter, Depends +from starlette.responses import JSONResponse, Response + +from policyengine_api.fastapi_routes.dependencies import ( + NativeRouteDependencies, + V2UserDynamicResourceService, + _default_v2_user_dynamic_service_factory, +) +from policyengine_api.fastapi_routes.query_parameters import query_dependency +from policyengine_api.fastapi_routes.v2.errors_support import v2_error_response +from policyengine_api.fastapi_routes.v2.user_dynamics.request_models import ( + UserDynamicCreateRequest, + UserDynamicPatchRequest, +) +from policyengine_api.fastapi_routes.v2.user_dynamics.response_models import ( + USER_DYNAMIC_ERROR_RESPONSES, + UserDynamicDetailResponse, + UserDynamicDetailResult, + UserDynamicItem, + UserDynamicPageResponse, + UserDynamicPageResult, +) +from policyengine_api.fastapi_routes.v2.user_resources_support import ( + enforce_user_write_request_size, + user_resource_operation, +) +from policyengine_api.query_parameters import ( + CountryQuery, + UserDynamicCollectionQuery, +) +from policyengine_api.services.v2.identity.types import AccountPrincipal +from policyengine_api.services.v2.user_dynamics.types import UserDynamicFilter + +CountryQueryDependency = Annotated[ + CountryQuery, Depends(query_dependency(CountryQuery)) +] +UserDynamicCollectionQueryDependency = Annotated[ + UserDynamicCollectionQuery, + Depends(query_dependency(UserDynamicCollectionQuery)), +] + + +def _service_factory( + dependencies: NativeRouteDependencies, +) -> Callable[[], V2UserDynamicResourceService]: + if dependencies.v2_user_dynamic_service_factory is not None: + return dependencies.v2_user_dynamic_service_factory + return _default_v2_user_dynamic_service_factory + + +def _create_user_dynamic( + service_factory: Callable[[], V2UserDynamicResourceService], + body: UserDynamicCreateRequest, + query: CountryQuery, + principal: AccountPrincipal, +) -> UserDynamicDetailResponse | JSONResponse: + """Save a dynamic once the body and query agree on its country.""" + if body.country_id != query.country_id: + return v2_error_response( + 400, + "Body country_id must match query country_id", + ) + + def create() -> UserDynamicDetailResponse: + item = service_factory().create_user_dynamic( + principal=principal, + association_input=body, + ) + return UserDynamicDetailResponse( + result=UserDynamicDetailResult(item=UserDynamicItem.from_read(item)) + ) + + return user_resource_operation(create) + + +def build_v2_user_dynamic_router( + dependencies: NativeRouteDependencies, +) -> APIRouter: + """Build the saved-dynamic routes without opening a connection. + + Authentication is a router-level dependency, so a missing or invalid + credential is rejected before query or body validation. + """ + require_user = dependencies.require_user + router = APIRouter( + prefix="/v2", + responses=USER_DYNAMIC_ERROR_RESPONSES, + dependencies=[ + Depends(require_user), + Depends(enforce_user_write_request_size), + ], + ) + service_factory = _service_factory(dependencies) + + @router.post( + "/user-dynamics", + response_model=UserDynamicDetailResponse, + status_code=201, + summary="Save a dynamic for the current user", + description=( + "Requires a bearer access token or the PolicyEngine-Unauthenticated-User " + "header; the owner is taken from that credential. dynamic_id names a " + "dynamic (POST /v2/dynamics) stored in the same country: an unknown " + "one is not found (404), and another country's is refused (400). A " + "user may save the same dynamic more than once." + ), + ) + def create_user_dynamic( + body: UserDynamicCreateRequest, + query: CountryQueryDependency, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> UserDynamicDetailResponse | JSONResponse: + return _create_user_dynamic(service_factory, body, query, principal) + + @router.get( + "/user-dynamics/{association_id}", + response_model=UserDynamicDetailResponse, + summary="Read one of the current user's saved dynamics", + ) + def get_user_dynamic( + association_id: UUID, + query: CountryQueryDependency, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> UserDynamicDetailResponse | JSONResponse: + def read() -> UserDynamicDetailResponse: + item = service_factory().get_user_dynamic( + principal=principal, + country_id=query.country_id, + association_id=association_id, + ) + return UserDynamicDetailResponse( + result=UserDynamicDetailResult(item=UserDynamicItem.from_read(item)) + ) + + return user_resource_operation(read) + + @router.get( + "/user-dynamics", + response_model=UserDynamicPageResponse, + summary="List the current user's saved dynamics", + description=( + "Oldest first. dynamic_id keeps only the saved dynamics that name " + "that dynamic." + ), + ) + def get_user_dynamics( + query: UserDynamicCollectionQueryDependency, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> UserDynamicPageResponse | JSONResponse: + def read() -> UserDynamicPageResponse: + page = service_factory().list_user_dynamics( + principal=principal, + country_id=query.country_id, + dynamic_filter=UserDynamicFilter(dynamic_id=query.dynamic_id), + offset=query.offset, + limit=query.limit, + ) + return UserDynamicPageResponse(result=UserDynamicPageResult.from_page(page)) + + return user_resource_operation(read) + + @router.patch( + "/user-dynamics/{association_id}", + response_model=UserDynamicDetailResponse, + summary="Rename or repoint one of the current user's saved dynamics", + description=( + "The row keeps its id, owner and creation time. dynamic_id points it " + "at another dynamic stored in the same country, and can't be null." + ), + ) + def patch_user_dynamic_route( + association_id: UUID, + body: UserDynamicPatchRequest, + query: CountryQueryDependency, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> UserDynamicDetailResponse | JSONResponse: + def patch() -> UserDynamicDetailResponse: + item = service_factory().patch_user_dynamic( + principal=principal, + country_id=query.country_id, + association_id=association_id, + association_input=body, + ) + return UserDynamicDetailResponse( + result=UserDynamicDetailResult(item=UserDynamicItem.from_read(item)) + ) + + return user_resource_operation(patch) + + @router.delete( + "/user-dynamics/{association_id}", + response_model=None, + status_code=204, + response_class=Response, + summary="Delete one of the current user's saved dynamics", + description="The dynamic it names is kept.", + ) + def delete_user_dynamic_route( + association_id: UUID, + query: CountryQueryDependency, + principal: Annotated[AccountPrincipal, Depends(require_user)], + ) -> Response | JSONResponse: + def delete() -> Response: + service_factory().delete_user_dynamic( + principal=principal, + country_id=query.country_id, + association_id=association_id, + ) + return Response(status_code=204) + + return user_resource_operation(delete) + + return router diff --git a/policyengine_api/fastapi_routes/v2/user_resources_support.py b/policyengine_api/fastapi_routes/v2/user_resources_support.py index eff3e4ffc..381a5fd70 100644 --- a/policyengine_api/fastapi_routes/v2/user_resources_support.py +++ b/policyengine_api/fastapi_routes/v2/user_resources_support.py @@ -39,6 +39,9 @@ AccountNotFoundError, TypeChangeNotFoundError, ) +from policyengine_api.services.v2.user_dynamics.validators import ( + AssociationDynamicNotFoundError, +) from policyengine_api.services.v2.user_households.validators import ( AssociationHouseholdNotFoundError, ) @@ -238,6 +241,7 @@ class UserResourceFailure(NamedTuple): ( AssociationNotFoundError, AssociationPolicyNotFoundError, + AssociationDynamicNotFoundError, AssociationHouseholdNotFoundError, AssociationReportNotFoundError, AssociationSimulationNotFoundError, diff --git a/policyengine_api/migration_logging.py b/policyengine_api/migration_logging.py index 8fd207ba4..bead7d1d9 100644 --- a/policyengine_api/migration_logging.py +++ b/policyengine_api/migration_logging.py @@ -52,6 +52,7 @@ { "policies", "user-policies", + "user-dynamics", "households", "user-households", "user-simulations", @@ -67,6 +68,7 @@ V2_USER_RESOURCE_SEGMENTS = frozenset( { "user-policies", + "user-dynamics", "user-households", "user-simulations", "user-reports", diff --git a/policyengine_api/migration_registry.py b/policyengine_api/migration_registry.py index 6c7e808cb..ab1bf5ad7 100644 --- a/policyengine_api/migration_registry.py +++ b/policyengine_api/migration_registry.py @@ -62,6 +62,7 @@ class RouteGroupConfig: "dynamics", "user-policy", "user-policies", + "user-dynamics", ), db_entity="policy", ), diff --git a/policyengine_api/query_parameters.py b/policyengine_api/query_parameters.py index a2a0c5278..7c2311d91 100644 --- a/policyengine_api/query_parameters.py +++ b/policyengine_api/query_parameters.py @@ -377,6 +377,12 @@ class UserPolicyCollectionQuery(CountryQuery, PaginationQuery): legacy_policy_id: LegacyResourceId | None = None +class UserDynamicCollectionQuery(CountryQuery, PaginationQuery): + """Query contract for the current user's saved dynamics.""" + + dynamic_id: ResourceId | None = None + + EmailSearch = Annotated[ str, StringConstraints(strip_whitespace=True, min_length=1, max_length=320), diff --git a/policyengine_api/services/v2/identity/database_connectors/updates.py b/policyengine_api/services/v2/identity/database_connectors/updates.py index 64368c389..1bf84577f 100644 --- a/policyengine_api/services/v2/identity/database_connectors/updates.py +++ b/policyengine_api/services/v2/identity/database_connectors/updates.py @@ -9,6 +9,7 @@ from policyengine_api.data.v2.models import ( User, + UserDynamic, UserHouseholdAssociation, UserIdentity, UserPolicy, @@ -23,6 +24,7 @@ USER_ASSOCIATION_TABLES = ( UserPolicy, + UserDynamic, UserHouseholdAssociation, UserSimulationAssociation, UserReportAssociation, diff --git a/policyengine_api/services/v2/user_accounts/services.py b/policyengine_api/services/v2/user_accounts/services.py index 36dd04c50..c86a6db28 100644 --- a/policyengine_api/services/v2/user_accounts/services.py +++ b/policyengine_api/services/v2/user_accounts/services.py @@ -120,6 +120,9 @@ def export_user_in_session( """ # Imported here: v2 services load only when used (ruff's # banned-module-level-imports in pyproject.toml). + from policyengine_api.services.v2.user_dynamics.services import ( + read_all_user_dynamics, + ) from policyengine_api.services.v2.user_households.services import ( read_all_user_households, ) @@ -137,6 +140,7 @@ def export_user_in_session( return AccountExport( user=account_read(user, email=email), policies=read_all_user_policies(session, user_id=user_id), + dynamics=read_all_user_dynamics(session, user_id=user_id), households=read_all_user_households(session, user_id=user_id), simulations=read_all_user_simulations(session, user_id=user_id), reports=read_all_user_reports(session, user_id=user_id), @@ -264,6 +268,7 @@ def export_account( return AccountExport( user=None, policies=(), + dynamics=(), households=(), simulations=(), reports=(), diff --git a/policyengine_api/services/v2/user_accounts/types.py b/policyengine_api/services/v2/user_accounts/types.py index ad0e15bcb..1e634a145 100644 --- a/policyengine_api/services/v2/user_accounts/types.py +++ b/policyengine_api/services/v2/user_accounts/types.py @@ -15,6 +15,7 @@ from policyengine_api.data.v2.models import UserType from policyengine_api.services.v2.identity.types import AccountConversionOutcome + from policyengine_api.services.v2.user_dynamics.types import UserDynamicRead from policyengine_api.services.v2.user_households.types import UserHouseholdRead from policyengine_api.services.v2.user_policies.types import UserPolicyRead from policyengine_api.services.v2.user_reports.types import UserReportRead @@ -88,6 +89,7 @@ class AccountExport: # Null when an unauthenticated principal has not saved anything yet. user: AccountRead | None policies: tuple[UserPolicyRead, ...] + dynamics: tuple[UserDynamicRead, ...] households: tuple[UserHouseholdRead, ...] simulations: tuple[UserSimulationRead, ...] reports: tuple[UserReportRead, ...] diff --git a/policyengine_api/services/v2/user_dynamics/__init__.py b/policyengine_api/services/v2/user_dynamics/__init__.py new file mode 100644 index 000000000..e56c303de --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/__init__.py @@ -0,0 +1 @@ +"""Application services for users' saved dynamics (``user_dynamics``).""" diff --git a/policyengine_api/services/v2/user_dynamics/database_connectors/__init__.py b/policyengine_api/services/v2/user_dynamics/database_connectors/__init__.py new file mode 100644 index 000000000..b4004eb03 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/database_connectors/__init__.py @@ -0,0 +1 @@ +"""SQL-facing connector functions for users' saved dynamics.""" diff --git a/policyengine_api/services/v2/user_dynamics/database_connectors/creates.py b/policyengine_api/services/v2/user_dynamics/database_connectors/creates.py new file mode 100644 index 000000000..7eeaae967 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/database_connectors/creates.py @@ -0,0 +1,25 @@ +"""Database inserts used by the operations on users' saved dynamics.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.data.v2.models import UserDynamic + +if TYPE_CHECKING: + from sqlmodel import Session + + from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicCreationInput, + ) + + +def create_user_dynamic( + session: Session, creation_input: UserDynamicCreationInput +) -> UserDynamic: + """Insert a saved dynamic and return it with its generated fields loaded.""" + saved_dynamic = UserDynamic(**creation_input.model_dump()) + session.add(saved_dynamic) + session.flush() + session.refresh(saved_dynamic) + return saved_dynamic diff --git a/policyengine_api/services/v2/user_dynamics/database_connectors/deletes.py b/policyengine_api/services/v2/user_dynamics/database_connectors/deletes.py new file mode 100644 index 000000000..7db4f42ed --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/database_connectors/deletes.py @@ -0,0 +1,16 @@ +"""Database deletes used by the operations on users' saved dynamics.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from sqlmodel import Session + + from policyengine_api.data.v2.models import UserDynamic + + +def delete_user_dynamic(session: Session, saved_dynamic: UserDynamic) -> None: + """Delete a saved dynamic; the dynamic it names is kept.""" + session.delete(saved_dynamic) + session.flush() diff --git a/policyengine_api/services/v2/user_dynamics/database_connectors/reads.py b/policyengine_api/services/v2/user_dynamics/database_connectors/reads.py new file mode 100644 index 000000000..71a84781f --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/database_connectors/reads.py @@ -0,0 +1,70 @@ +"""Database selections used by the operations on users' saved dynamics.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from sqlmodel import Session, col, select + +from policyengine_api.data.v2.models import Dynamic, UserDynamic + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_api.services.v2.user_dynamics.types import UserDynamicListing + + +def read_dynamic_for_association(session: Session, dynamic_id: UUID) -> Dynamic | None: + """Return the dynamic with this id in any country, or None.""" + return session.exec(select(Dynamic).where(Dynamic.id == dynamic_id)).one_or_none() + + +def read_owned_user_dynamic_row( + session: Session, + *, + user_id: UUID, + country_id: str, + association_id: UUID, +) -> UserDynamic | None: + """Return the user's saved dynamic with this id in this country, or None.""" + return session.exec( + select(UserDynamic).where( + UserDynamic.id == association_id, + UserDynamic.country_id == country_id, + UserDynamic.user_id == user_id, + ) + ).one_or_none() + + +def read_user_dynamic_rows( + session: Session, listing: UserDynamicListing +) -> list[UserDynamic]: + """Return up to ``limit + 1`` of a user's saved dynamics in creation order. + + With the listing's ``dynamic_id``, only those naming that dynamic are + returned. The extra row lets the caller report whether another page exists. + """ + statement = select(UserDynamic).where( + UserDynamic.country_id == listing.country_id, + UserDynamic.user_id == listing.user_id, + ) + if listing.dynamic_id is not None: + statement = statement.where(UserDynamic.dynamic_id == listing.dynamic_id) + return list( + session.exec( + statement.order_by(col(UserDynamic.created_at), col(UserDynamic.id)) + .offset(listing.offset) + .limit(listing.limit + 1) + ).all() + ) + + +def read_all_user_dynamic_rows(session: Session, *, user_id: UUID) -> list[UserDynamic]: + """Return every saved dynamic the user owns, in any country, in creation order.""" + return list( + session.exec( + select(UserDynamic) + .where(UserDynamic.user_id == user_id) + .order_by(col(UserDynamic.created_at), col(UserDynamic.id)) + ).all() + ) diff --git a/policyengine_api/services/v2/user_dynamics/database_connectors/updates.py b/policyengine_api/services/v2/user_dynamics/database_connectors/updates.py new file mode 100644 index 000000000..0c54b2390 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/database_connectors/updates.py @@ -0,0 +1,33 @@ +"""Database updates used by the operations on users' saved dynamics.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.data.v2.models.base import utc_now + +if TYPE_CHECKING: + from sqlmodel import Session + + from policyengine_api.data.v2.models import UserDynamic + from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicUpdateInput, + ) + + +def update_user_dynamic( + session: Session, + saved_dynamic: UserDynamic, + update_input: UserDynamicUpdateInput, +) -> UserDynamic: + """Apply the supplied fields, bump ``updated_at`` and return the row. + + The service checks a new ``dynamic_id`` before calling this. + """ + for field_name, value in update_input.model_dump(exclude_unset=True).items(): + setattr(saved_dynamic, field_name, value) + saved_dynamic.updated_at = utc_now() + session.add(saved_dynamic) + session.flush() + session.refresh(saved_dynamic) + return saved_dynamic diff --git a/policyengine_api/services/v2/user_dynamics/database_session.py b/policyengine_api/services/v2/user_dynamics/database_session.py new file mode 100644 index 000000000..636ee1535 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/database_session.py @@ -0,0 +1,32 @@ +"""Database session lifetime management for v2 saved-dynamic services.""" + +from __future__ import annotations + +from contextlib import contextmanager +from typing import TYPE_CHECKING + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy.orm import sessionmaker + from sqlmodel import Session + + +class UserDynamicDatabaseSession: + """Open read sessions and transactions for saved-dynamic services.""" + + def __init__(self, session_factory: sessionmaker[Session]) -> None: + """Use ``session_factory`` to open every session.""" + self._session_factory = session_factory + + @contextmanager + def read(self) -> Iterator[Session]: + """Yield a session for reads; nothing is committed.""" + with self._session_factory() as session: + yield session + + @contextmanager + def transaction(self) -> Iterator[Session]: + """Yield a session whose transaction commits on exit and rolls back on error.""" + with self._session_factory.begin() as session: + yield session diff --git a/policyengine_api/services/v2/user_dynamics/services.py b/policyengine_api/services/v2/user_dynamics/services.py new file mode 100644 index 000000000..01309a6b8 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/services.py @@ -0,0 +1,273 @@ +"""Router-facing and migration-facing services for users' saved dynamics.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.identity.services import ( + resolve_principal_user_for_read_in_session, + resolve_principal_user_in_session, +) +from policyengine_api.services.v2.user_dynamics.database_connectors.creates import ( + create_user_dynamic, +) +from policyengine_api.services.v2.user_dynamics.database_connectors.deletes import ( + delete_user_dynamic, +) +from policyengine_api.services.v2.user_dynamics.database_connectors.reads import ( + read_all_user_dynamic_rows, + read_dynamic_for_association, + read_owned_user_dynamic_row, + read_user_dynamic_rows, +) +from policyengine_api.services.v2.user_dynamics.database_connectors.updates import ( + update_user_dynamic, +) +from policyengine_api.services.v2.user_dynamics.transformations import ( + owned_user_dynamic_input, + user_dynamic_page, + user_dynamic_read, +) +from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicFilter, + UserDynamicListing, +) +from policyengine_api.services.v2.user_dynamics.validators import ( + require_user_dynamic, + validate_association_dynamic, +) + +if TYPE_CHECKING: + from uuid import UUID + + from sqlmodel import Session + + from policyengine_api.data.v2.models import UserDynamic + from policyengine_api.services.v2.identity.types import AccountPrincipal + from policyengine_api.services.v2.user_dynamics.database_session import ( + UserDynamicDatabaseSession, + ) + from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicCreateFields, + UserDynamicCreationInput, + UserDynamicPage, + UserDynamicRead, + UserDynamicUpdateInput, + ) + + +def require_dynamic_in_country( + session: Session, *, country_id: str, dynamic_id: UUID +) -> None: + """Check that the dynamic exists and is stored in ``country_id``. + + Raise AssociationDynamicNotFoundError or AssociationDynamicCountryConflictError. + """ + validate_association_dynamic( + country_id=country_id, + dynamic_id=dynamic_id, + dynamic=read_dynamic_for_association(session, dynamic_id), + ) + + +def create_user_dynamic_in_session( + session: Session, creation_input: UserDynamicCreationInput +) -> UserDynamicRead: + """Save a dynamic for the user that ``creation_input`` names, in ``session``. + + This is what D4 · 1's migration calls to give a v1 saved policy a saved + dynamic; the routes call it once they have resolved the owner. The user + must exist, and the dynamic must be stored in the saved dynamic's country + (AssociationDynamicNotFoundError or AssociationDynamicCountryConflictError). + The caller's transaction commits it. + """ + require_dynamic_in_country( + session, + country_id=creation_input.country_id, + dynamic_id=creation_input.dynamic_id, + ) + return user_dynamic_read(create_user_dynamic(session, creation_input)) + + +def read_owned_user_dynamic( + session: Session, + *, + user_id: UUID | None, + country_id: str, + association_id: UUID, +) -> UserDynamic: + """``user_id`` is None for an unauthenticated user that owns nothing yet.""" + return require_user_dynamic( + None + if user_id is None + else read_owned_user_dynamic_row( + session, + user_id=user_id, + country_id=country_id, + association_id=association_id, + ), + association_id=association_id, + ) + + +def read_all_user_dynamics( + session: Session, *, user_id: UUID +) -> tuple[UserDynamicRead, ...]: + """Return every saved dynamic owned by a user, across countries.""" + return tuple( + user_dynamic_read(row) + for row in read_all_user_dynamic_rows(session, user_id=user_id) + ) + + +class V2UserDynamicService: + """Sequence owner-scoped saved-dynamic operations through explicit sessions. + + The owner always comes from the verified session principal: a signed-in + user or a signed-out browser. Reads never provision a browser's + unauthenticated user; one that does not exist yet owns no records. + """ + + def __init__(self, database_session: UserDynamicDatabaseSession) -> None: + """Open sessions through ``database_session``.""" + self._database_session = database_session + + def create_user_dynamic( + self, + *, + principal: AccountPrincipal, + association_input: UserDynamicCreateFields, + ) -> UserDynamicRead: + """Save a dynamic for the principal, provisioning their v2 user if needed. + + The dynamic must be stored in this country + (AssociationDynamicNotFoundError or AssociationDynamicCountryConflictError). + """ + with self._database_session.transaction() as session: + owner = resolve_principal_user_in_session( + session, + principal, + country_id=association_input.country_id, + ) + return create_user_dynamic_in_session( + session, + owned_user_dynamic_input(association_input, user_id=owner.user_id), + ) + + def get_user_dynamic( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> UserDynamicRead: + """Return the principal's saved dynamic in this country. + + Raise UserDynamicNotFoundError when it is absent or another user's. A + signed-out browser that has not saved anything yet owns nothing. + """ + with self._database_session.transaction() as session: + owner = resolve_principal_user_for_read_in_session( + session, principal, country_id=country_id + ) + return user_dynamic_read( + read_owned_user_dynamic( + session, + user_id=None if owner is None else owner.user_id, + country_id=country_id, + association_id=association_id, + ) + ) + + def list_user_dynamics( + self, + *, + principal: AccountPrincipal, + country_id: str, + dynamic_filter: UserDynamicFilter | None = None, + offset: int = 0, + limit: int = 100, + ) -> UserDynamicPage: + """Return a page of the principal's saved dynamics in this country. + + ``dynamic_filter`` narrows it to one dynamic. A signed-out browser that + has not saved anything yet gets an empty page. + """ + selected = dynamic_filter if dynamic_filter is not None else UserDynamicFilter() + with self._database_session.transaction() as session: + owner = resolve_principal_user_for_read_in_session( + session, principal, country_id=country_id + ) + if owner is None: + return user_dynamic_page([], offset=offset, limit=limit) + rows = read_user_dynamic_rows( + session, + UserDynamicListing( + country_id=country_id, + user_id=owner.user_id, + dynamic_id=selected.dynamic_id, + offset=offset, + limit=limit, + ), + ) + return user_dynamic_page(rows, offset=offset, limit=limit) + + def patch_user_dynamic( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + association_input: UserDynamicUpdateInput, + ) -> UserDynamicRead: + """Update the supplied fields of the principal's saved dynamic in this country. + + It keeps its id, owner, country and creation time. A new ``dynamic_id`` + must be stored in this country (AssociationDynamicNotFoundError or + AssociationDynamicCountryConflictError). Raise UserDynamicNotFoundError + when the saved dynamic is not the principal's. + """ + with self._database_session.transaction() as session: + owner = resolve_principal_user_in_session( + session, principal, country_id=country_id + ) + saved_dynamic = read_owned_user_dynamic( + session, + user_id=owner.user_id, + country_id=country_id, + association_id=association_id, + ) + if association_input.dynamic_id is not None: + require_dynamic_in_country( + session, + country_id=country_id, + dynamic_id=association_input.dynamic_id, + ) + return user_dynamic_read( + update_user_dynamic(session, saved_dynamic, association_input) + ) + + def delete_user_dynamic( + self, + *, + principal: AccountPrincipal, + country_id: str, + association_id: UUID, + ) -> None: + """Delete the principal's saved dynamic in this country. + + Raise UserDynamicNotFoundError when it is not the principal's. + """ + with self._database_session.transaction() as session: + owner = resolve_principal_user_in_session( + session, principal, country_id=country_id + ) + delete_user_dynamic( + session, + read_owned_user_dynamic( + session, + user_id=owner.user_id, + country_id=country_id, + association_id=association_id, + ), + ) diff --git a/policyengine_api/services/v2/user_dynamics/transformations.py b/policyengine_api/services/v2/user_dynamics/transformations.py new file mode 100644 index 000000000..9a75219a3 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/transformations.py @@ -0,0 +1,53 @@ +"""Pure representation transformations for users' saved dynamics.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicCreateFields, + UserDynamicCreationInput, + UserDynamicPage, + UserDynamicRead, +) + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_api.data.v2.models import UserDynamic + + +def user_dynamic_read(saved_dynamic: UserDynamic) -> UserDynamicRead: + """Convert a stored saved-dynamic row to the service's read model.""" + return UserDynamicRead( + id=saved_dynamic.id, + country_id=saved_dynamic.country_id, + user_id=saved_dynamic.user_id, + dynamic_id=saved_dynamic.dynamic_id, + name=saved_dynamic.name, + description=saved_dynamic.description, + created_at=saved_dynamic.created_at, + updated_at=saved_dynamic.updated_at, + ) + + +def user_dynamic_page( + rows: list[UserDynamic], *, offset: int, limit: int +) -> UserDynamicPage: + """Build a page from up to ``limit + 1`` rows. + + The extra row is not returned; it only sets ``has_more``. + """ + return UserDynamicPage( + items=tuple(user_dynamic_read(row) for row in rows[:limit]), + offset=offset, + limit=limit, + has_more=len(rows) > limit, + ) + + +def owned_user_dynamic_input( + fields: UserDynamicCreateFields, *, user_id: UUID +) -> UserDynamicCreationInput: + """Attach the session owner to the caller's saved-dynamic fields.""" + return UserDynamicCreationInput(**fields.model_dump(), user_id=user_id) diff --git a/policyengine_api/services/v2/user_dynamics/types.py b/policyengine_api/services/v2/user_dynamics/types.py new file mode 100644 index 000000000..fc6e554e4 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/types.py @@ -0,0 +1,114 @@ +"""Framework-independent data exchanged by the layers of users' saved dynamics.""" + +from __future__ import annotations + +from dataclasses import dataclass +from typing import TYPE_CHECKING + +from pydantic import model_validator + +from policyengine_api.query_parameters import CountryId, ResourceId, UserId +from policyengine_api.services.v2.associations.types import ( + AssociationDescription, + AssociationName, + StrictAssociationModel, +) + +if TYPE_CHECKING: + from datetime import datetime + from uuid import UUID + + +class StrictUserDynamicInput(StrictAssociationModel): + """Reject fields outside the reviewed saved-dynamic contract.""" + + +class UserDynamicCreateFields(StrictUserDynamicInput): + """Caller-supplied saved-dynamic fields; the owner comes from the session.""" + + country_id: CountryId + dynamic_id: ResourceId + name: AssociationName | None = None + description: AssociationDescription | None = None + + +class UserDynamicCreationInput(StrictUserDynamicInput): + """Complete persisted saved-dynamic values, including the resolved owner.""" + + country_id: CountryId + user_id: UserId + dynamic_id: ResourceId + name: AssociationName | None = None + description: AssociationDescription | None = None + + +class UserDynamicUpdateInput(StrictUserDynamicInput): + """A partial update of a saved dynamic; only supplied fields are changed. + + At least one field must be supplied. ``dynamic_id`` points the saved + dynamic at another dynamic in its country, and can't be set to null. + """ + + dynamic_id: ResourceId | None = None + name: AssociationName | None = None + description: AssociationDescription | None = None + + @model_validator(mode="after") + def require_supplied_field(self) -> UserDynamicUpdateInput: + """Require a supplied field, and reject an explicit null ``dynamic_id``.""" + if not self.model_fields_set & {"dynamic_id", "name", "description"}: + msg = "At least one of dynamic_id, name, or description must be supplied" + raise ValueError(msg) + if "dynamic_id" in self.model_fields_set and self.dynamic_id is None: + msg = "dynamic_id must not be null" + raise ValueError(msg) + return self + + +@dataclass(frozen=True) +class UserDynamicRead: + """A stored saved dynamic as the service returns it to routes.""" + + id: UUID + country_id: str + user_id: UUID + dynamic_id: UUID + name: str | None + description: str | None + created_at: datetime + updated_at: datetime + + +@dataclass(frozen=True) +class UserDynamicFilter: + """Which of the caller's saved dynamics a listing keeps. + + ``dynamic_id`` keeps those naming one dynamic; without it, every saved + dynamic is kept. + """ + + dynamic_id: UUID | None = None + + +@dataclass(frozen=True) +class UserDynamicListing: + """One page of a user's saved dynamics to read, optionally for one dynamic.""" + + country_id: str + user_id: UUID + dynamic_id: UUID | None + offset: int + limit: int + + +@dataclass(frozen=True) +class UserDynamicPage: + """One page of saved dynamics in creation order. + + ``has_more`` says whether more follow. + """ + + items: tuple[UserDynamicRead, ...] + offset: int + limit: int + has_more: bool diff --git a/policyengine_api/services/v2/user_dynamics/validators.py b/policyengine_api/services/v2/user_dynamics/validators.py new file mode 100644 index 000000000..69e7b0157 --- /dev/null +++ b/policyengine_api/services/v2/user_dynamics/validators.py @@ -0,0 +1,55 @@ +"""Database-independent validation for users' saved dynamics.""" + +from __future__ import annotations + +from typing import TYPE_CHECKING + +from policyengine_api.services.v2.associations.validators import ( + AssociationNotFoundError, + AssociationReferenceConflictError, +) + +if TYPE_CHECKING: + from uuid import UUID + + from policyengine_api.data.v2.models import Dynamic, UserDynamic + + +class UserDynamicNotFoundError(AssociationNotFoundError): + """Raised when a saved dynamic is absent for the caller and country.""" + + +class AssociationDynamicNotFoundError(LookupError): + """Raised when a saved dynamic names an unknown dynamic.""" + + +class AssociationDynamicCountryConflictError(AssociationReferenceConflictError): + """Raised when a saved dynamic names a dynamic stored in another country.""" + + +def require_user_dynamic( + saved_dynamic: UserDynamic | None, *, association_id: UUID +) -> UserDynamic: + """Return the saved dynamic, or raise UserDynamicNotFoundError if it is None.""" + if saved_dynamic is None: + msg = f"saved dynamic {association_id} was not found" + raise UserDynamicNotFoundError(msg) + return saved_dynamic + + +def validate_association_dynamic( + *, + country_id: str, + dynamic_id: UUID, + dynamic: Dynamic | None, +) -> None: + """Check that a named dynamic exists and is stored in the saved dynamic's country. + + Raise AssociationDynamicNotFoundError or AssociationDynamicCountryConflictError. + """ + if dynamic is None: + msg = f"dynamic {dynamic_id} was not found" + raise AssociationDynamicNotFoundError(msg) + if dynamic.country_id != country_id: + msg = "A saved dynamic's country_id must match the dynamic's country" + raise AssociationDynamicCountryConflictError(msg) diff --git a/pyproject.toml b/pyproject.toml index e0dd5ba20..04bc603f7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -192,6 +192,7 @@ files = [ "policyengine_api/fastapi_routes/dependencies.py", "policyengine_api/fastapi_routes/metadata_protocols.py", "policyengine_api/fastapi_routes/resource_service_protocols.py", + "policyengine_api/fastapi_routes/saved_item_service_protocols.py", "policyengine_api/fastapi_routes/v2", "policyengine_api/services/v2", "policyengine_api/content_encoding.py", @@ -423,6 +424,8 @@ banned-module-level-imports = [ "policyengine_api.services.v2.stored_simulations.services", "policyengine_api.services.v2.user_accounts.database_session", "policyengine_api.services.v2.user_accounts.services", + "policyengine_api.services.v2.user_dynamics.database_session", + "policyengine_api.services.v2.user_dynamics.services", "policyengine_api.services.v2.user_emails.services", "policyengine_api.services.v2.user_households.database_session", "policyengine_api.services.v2.user_households.services", @@ -463,6 +466,8 @@ runtime-evaluated-base-classes = [ "policyengine_api.fastapi_routes.v2.reports.response_models.StrictReportAPIModel", "policyengine_api.fastapi_routes.v2.simulations.response_models.SimulationSuccessResponse", "policyengine_api.fastapi_routes.v2.simulations.response_models.StrictSimulationAPIModel", + "policyengine_api.fastapi_routes.v2.user_dynamics.response_models.StrictUserDynamicAPIModel", + "policyengine_api.fastapi_routes.v2.user_dynamics.response_models.UserDynamicSuccessResponse", "policyengine_api.fastapi_routes.v2.user_households.response_models.StrictUserHouseholdAPIModel", "policyengine_api.fastapi_routes.v2.user_households.response_models.UserHouseholdSuccessResponse", "policyengine_api.fastapi_routes.v2.user_policies.response_models.StrictUserPolicyAPIModel", @@ -498,6 +503,10 @@ runtime-evaluated-base-classes = [ "policyengine_api.services.v2.stored_reports.economy_results.types.EconomyResultModel", "policyengine_api.services.v2.user_accounts.types.AccountUpdateInput", "policyengine_api.services.v2.user_accounts.types.StrictAccountInput", + "policyengine_api.services.v2.user_dynamics.types.StrictUserDynamicInput", + "policyengine_api.services.v2.user_dynamics.types.UserDynamicCreateFields", + "policyengine_api.services.v2.user_dynamics.types.UserDynamicCreationInput", + "policyengine_api.services.v2.user_dynamics.types.UserDynamicUpdateInput", "policyengine_api.services.v2.user_households.types.StrictUserHouseholdInput", "policyengine_api.services.v2.user_households.types.UserHouseholdCreateFields", "policyengine_api.services.v2.user_households.types.UserHouseholdCreationInput", diff --git a/rules/registry.toml b/rules/registry.toml index 87a5cf6a8..bbace0f4a 100644 --- a/rules/registry.toml +++ b/rules/registry.toml @@ -1471,6 +1471,7 @@ paths = [ "policyengine_api/fastapi_routes/dependencies.py", "policyengine_api/fastapi_routes/metadata_protocols.py", "policyengine_api/fastapi_routes/resource_service_protocols.py", + "policyengine_api/fastapi_routes/saved_item_service_protocols.py", "policyengine_api/fastapi_routes/v2", "policyengine_api/services/v2", "policyengine_api/content_encoding.py", diff --git a/tests/contract/registry.py b/tests/contract/registry.py index 0bf798576..2fdda2d39 100644 --- a/tests/contract/registry.py +++ b/tests/contract/registry.py @@ -277,6 +277,17 @@ class WorkflowContract: ), ), ), + WorkflowContract( + name="user_dynamic_associations_v2", + current_contract="typed_v2_resources", + future_owner_pr="Users' saved dynamics", + requests=_user_association_requests( + "user-dynamics", + route_group="policy", + item_fields=_association_item_fields("dynamic_id", "name", "description"), + patch_fields=("dynamic_id", "name", "description"), + ), + ), WorkflowContract( name="household_save_read", current_contract="api_v1_compatible", @@ -554,6 +565,7 @@ class WorkflowContract: "message", "result.user", "result.policies", + "result.dynamics", "result.households", "result.simulations", "result.reports", diff --git a/tests/contract/test_app_v2_workflow_contracts.py b/tests/contract/test_app_v2_workflow_contracts.py index cfe8c896d..78d48a1b1 100644 --- a/tests/contract/test_app_v2_workflow_contracts.py +++ b/tests/contract/test_app_v2_workflow_contracts.py @@ -12,6 +12,7 @@ def test_app_v2_workflow_contract_registry_is_complete(): "policy_resources_v2", "dynamic_resources_v2", "user_policy_associations_v2", + "user_dynamic_associations_v2", "household_save_read", "household_resources_v2", "household_calculations_v2", @@ -40,6 +41,7 @@ def test_app_v2_workflow_contract_registry_is_complete(): "policy_resources_v2", "dynamic_resources_v2", "user_policy_associations_v2", + "user_dynamic_associations_v2", "household_resources_v2", "household_calculations_v2", "user_household_associations_v2", @@ -95,7 +97,7 @@ def test_user_routes_record_signed_in_and_signed_out_contracts() -> None: if headers == ("PolicyEngine-Unauthenticated-User",) } - for resource in ("policies", "households", "simulations", "reports"): + for resource in ("policies", "dynamics", "households", "simulations", "reports"): collection = f"/v2/user-{resource}" detail = f"{collection}/{{association_id}}" assert { diff --git a/tests/integration/test_alembic_v2_dynamics.py b/tests/integration/test_alembic_v2_dynamics.py index 3da55d7cf..f79f92207 100644 --- a/tests/integration/test_alembic_v2_dynamics.py +++ b/tests/integration/test_alembic_v2_dynamics.py @@ -323,7 +323,8 @@ def test_the_downgrade_fails_changing_nothing_while_a_dynamic_is_stored( engine: Engine, ) -> None: config = alembic_v2_config() - command.upgrade(config, DYNAMICS_REVISION) + # Step down from head, so the downgrade below runs this revision's step alone. + command.downgrade(config, DYNAMICS_REVISION) with engine.begin() as connection: rows = insert_public_api_rows(connection) dynamic_id = _insert_dynamic(connection, rows) diff --git a/tests/integration/test_alembic_v2_user_dynamics.py b/tests/integration/test_alembic_v2_user_dynamics.py new file mode 100644 index 000000000..cc00e3c91 --- /dev/null +++ b/tests/integration/test_alembic_v2_user_dynamics.py @@ -0,0 +1,276 @@ +"""Check the revision that adds users' saved dynamics against disposable Postgres. + +The revision creates ``user_dynamics`` and changes nothing else. A saved +dynamic names a dynamic stored in its own country, which can't be deleted +while it is saved, and is deleted with its user. The downgrade drops the +table with its rows. +""" + +from __future__ import annotations + +from typing import TYPE_CHECKING, Any +from uuid import uuid4 + +import pytest +from alembic import command +from sqlalchemy import create_engine, inspect, text + +from tests.fixtures.integration.alembic_v2 import alembic_v2_config, disposable_v2_url +from tests.integration.simulation_rows import ( + PublicApiRows, + delete_public_api_rows, + insert_public_api_rows, + insert_row, + refused, +) + +if TYPE_CHECKING: + from collections.abc import Iterator + + from sqlalchemy import Connection, Engine + +DYNAMICS_REVISION = "9d1d12a7ac58" +USER_DYNAMICS_REVISION = "d417fe8b1b17" + + +@pytest.fixture +def engine() -> Iterator[Engine]: + """Yield an engine on a database at head, and leave it at head.""" + command.upgrade(alembic_v2_config(), "head") + database_engine = create_engine(disposable_v2_url()) + try: + yield database_engine + finally: + command.upgrade(alembic_v2_config(), "head") + database_engine.dispose() + + +@pytest.fixture +def connection(engine: Engine) -> Iterator[Connection]: + """Yield a connection at head whose writes are rolled back after the test.""" + with engine.connect() as database_connection: + transaction = database_connection.begin() + try: + yield database_connection + finally: + transaction.rollback() + + +def _schema(engine: Engine) -> dict[str, dict[str, Any]]: + """Return each table's columns, keys, unique constraints and indexes.""" + inspector = inspect(engine) + return { + table_name: { + "columns": sorted( + (column["name"], str(column["type"]), column["nullable"]) + for column in inspector.get_columns(table_name) + ), + "foreign_keys": sorted( + ( + tuple(key["constrained_columns"]), + key["referred_table"], + tuple(key["referred_columns"]), + key["options"].get("ondelete"), + ) + for key in inspector.get_foreign_keys(table_name) + ), + "unique": sorted( + (str(constraint["name"]), tuple(constraint["column_names"])) + for constraint in inspector.get_unique_constraints(table_name) + ), + "indexes": sorted( + ( + str(index["name"]), + tuple(str(column) for column in index["column_names"]), + bool(index["unique"]), + ) + for index in inspector.get_indexes(table_name) + ), + } + for table_name in inspector.get_table_names() + } + + +def _insert_user(connection: Connection) -> object: + user_id = uuid4() + insert_row( + connection, + "users", + id=user_id, + user_type="standard", + primary_country="us", + ) + return user_id + + +def _insert_dynamic( + connection: Connection, rows: PublicApiRows, *, country_id: str +) -> object: + dynamic_id = uuid4() + insert_row( + connection, + "dynamics", + id=dynamic_id, + country_id=country_id, + tax_benefit_model_id=rows.model_id, + tax_benefit_model_version_id=rows.version_id, + canonicalization_version=1, + content_hash=uuid4().hex * 2, + ) + return dynamic_id + + +def _insert_saved_dynamic( + connection: Connection, + *, + user_id: object, + dynamic_id: object, + country_id: str = "us", +) -> object: + saved_dynamic_id = uuid4() + insert_row( + connection, + "user_dynamics", + id=saved_dynamic_id, + user_id=user_id, + dynamic_id=dynamic_id, + country_id=country_id, + name="CBO labour supply responses", + ) + return saved_dynamic_id + + +def _saved_dynamic_count(connection: Connection, saved_dynamic_id: object) -> int: + return int( + connection.execute( + text("SELECT count(*) FROM user_dynamics WHERE id = :id"), + {"id": saved_dynamic_id}, + ).scalar_one() + ) + + +def test_the_revision_adds_only_the_saved_dynamics_table(engine: Engine) -> None: + config = alembic_v2_config() + command.downgrade(config, DYNAMICS_REVISION) + before = _schema(engine) + command.upgrade(config, USER_DYNAMICS_REVISION) + after = _schema(engine) + + assert "user_dynamics" not in before + unchanged = { + name: value for name, value in after.items() if name != "user_dynamics" + } + assert unchanged == before + saved_dynamics = after["user_dynamics"] + assert saved_dynamics["columns"] == sorted( + [ + ("id", "UUID", False), + ("created_at", "TIMESTAMP", False), + ("updated_at", "TIMESTAMP", False), + ("user_id", "UUID", False), + ("country_id", "VARCHAR(2)", False), + ("dynamic_id", "UUID", False), + ("name", "VARCHAR(255)", True), + ("description", "TEXT", True), + ] + ) + assert saved_dynamics["foreign_keys"] == sorted( + [ + (("user_id",), "users", ("id",), "CASCADE"), + (("country_id",), "countries", ("id",), "RESTRICT"), + ( + ("dynamic_id", "country_id"), + "dynamics", + ("id", "country_id"), + "RESTRICT", + ), + ] + ) + assert saved_dynamics["unique"] == [ + ("uq_user_dynamics_id_country", ("id", "country_id")) + ] + # Postgres also lists the unique constraint's own index, checked above. + assert { + name for name, _columns, unique in saved_dynamics["indexes"] if not unique + } == { + "ix_user_dynamics_country_user_created_id", + "ix_user_dynamics_country_dynamic", + "ix_user_dynamics_user_id", + } + # The saved-policy table's columns, without its v1 reference and v3 fields. + assert {column[0] for column in saved_dynamics["columns"]} == { + column[0] for column in after["user_policies"]["columns"] + } - {"policy_id", "legacy_policy_id", "baseline", "provenance"} | {"dynamic_id"} + + command.downgrade(config, DYNAMICS_REVISION) + assert _schema(engine) == before + command.upgrade(config, "head") + command.check(config) + + +def test_a_saved_dynamic_names_a_dynamic_of_its_country_which_stays_while_saved( + connection: Connection, +) -> None: + rows = insert_public_api_rows(connection) + user_id = _insert_user(connection) + us_dynamic_id = _insert_dynamic(connection, rows, country_id="us") + uk_dynamic_id = _insert_dynamic(connection, rows, country_id="uk") + + with refused(connection, match="fk_user_dynamics_dynamic_country"): + _insert_saved_dynamic(connection, user_id=user_id, dynamic_id=uk_dynamic_id) + with refused(connection, match="fk_user_dynamics_dynamic_country"): + _insert_saved_dynamic(connection, user_id=user_id, dynamic_id=uuid4()) + with refused(connection, match="null value"): + _insert_saved_dynamic(connection, user_id=user_id, dynamic_id=None) + _insert_saved_dynamic(connection, user_id=user_id, dynamic_id=us_dynamic_id) + _insert_saved_dynamic( + connection, user_id=user_id, dynamic_id=uk_dynamic_id, country_id="uk" + ) + # Saving the same dynamic again, under another name, is allowed. + _insert_saved_dynamic(connection, user_id=user_id, dynamic_id=us_dynamic_id) + + with refused(connection, match="fk_user_dynamics_dynamic_country"): + connection.execute( + text("DELETE FROM dynamics WHERE id = :id"), {"id": us_dynamic_id} + ) + + +def test_saved_dynamics_are_deleted_with_their_user(connection: Connection) -> None: + rows = insert_public_api_rows(connection) + owner_id = _insert_user(connection) + other_user_id = _insert_user(connection) + dynamic_id = _insert_dynamic(connection, rows, country_id="us") + owners_saved_dynamic = _insert_saved_dynamic( + connection, user_id=owner_id, dynamic_id=dynamic_id + ) + others_saved_dynamic = _insert_saved_dynamic( + connection, user_id=other_user_id, dynamic_id=dynamic_id + ) + + connection.execute(text("DELETE FROM users WHERE id = :id"), {"id": owner_id}) + + assert _saved_dynamic_count(connection, owners_saved_dynamic) == 0 + assert _saved_dynamic_count(connection, others_saved_dynamic) == 1 + + +def test_the_downgrade_drops_the_saved_dynamics_with_the_table(engine: Engine) -> None: + config = alembic_v2_config() + # Step down from head, so the downgrade below runs this revision's step alone. + command.downgrade(config, USER_DYNAMICS_REVISION) + with engine.begin() as connection: + rows = insert_public_api_rows(connection) + user_id = _insert_user(connection) + dynamic_id = _insert_dynamic(connection, rows, country_id="us") + _insert_saved_dynamic(connection, user_id=user_id, dynamic_id=dynamic_id) + try: + command.downgrade(config, DYNAMICS_REVISION) + assert "user_dynamics" not in inspect(engine).get_table_names() + finally: + with engine.begin() as connection: + connection.execute( + text("DELETE FROM users WHERE id = :id"), {"id": user_id} + ) + connection.execute( + text("DELETE FROM dynamics WHERE id = :id"), {"id": dynamic_id} + ) + delete_public_api_rows(connection, rows) diff --git a/tests/integration/test_v2_user_identity_persistence.py b/tests/integration/test_v2_user_identity_persistence.py index f129ee086..289f28a9f 100644 --- a/tests/integration/test_v2_user_identity_persistence.py +++ b/tests/integration/test_v2_user_identity_persistence.py @@ -19,7 +19,7 @@ import pytest from pydantic import ValidationError -from sqlalchemy import create_engine, delete, func, select, update +from sqlalchemy import create_engine, delete, func, select, text, update from sqlalchemy.exc import IntegrityError from sqlalchemy.orm import sessionmaker from sqlmodel import Session @@ -32,6 +32,7 @@ from policyengine_api.data.v2.models import ( LegacyUserMapping, User, + UserDynamic, UserHouseholdAssociation, UserIdentity, UserPolicy, @@ -60,6 +61,14 @@ ) from policyengine_api.services.v2.user_accounts.services import V2AccountService from policyengine_api.services.v2.user_accounts.types import AccountUpdateInput +from policyengine_api.services.v2.user_dynamics.database_session import ( + UserDynamicDatabaseSession, +) +from policyengine_api.services.v2.user_dynamics.services import V2UserDynamicService +from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicCreateFields, + UserDynamicUpdateInput, +) from policyengine_api.services.v2.user_households.database_session import ( UserHouseholdDatabaseSession, ) @@ -88,6 +97,11 @@ from policyengine_api.services.v2.user_simulations.types import ( UserSimulationCreateFields, ) +from tests.integration.simulation_rows import ( + delete_public_api_rows, + insert_public_api_rows, + insert_row, +) from tests.unit.v2.user_service_support import default_legacy_references if TYPE_CHECKING: @@ -796,3 +810,99 @@ def pending_checker(connection) -> bool: "user_simulation_associations", "user_report_associations", } + + +@pytest.fixture +def stored_dynamic_id() -> Iterator[UUID]: + """Store a US dynamic as the superuser; delete it and its saves afterwards.""" + cleanup_engine = create_engine(_disposable_url()) + dynamic_id = uuid4() + with cleanup_engine.begin() as connection: + rows = insert_public_api_rows(connection) + insert_row( + connection, + "dynamics", + id=dynamic_id, + country_id="us", + tax_benefit_model_id=rows.model_id, + tax_benefit_model_version_id=rows.version_id, + canonicalization_version=1, + content_hash=uuid4().hex * 2, + ) + try: + yield dynamic_id + finally: + with cleanup_engine.begin() as connection: + connection.execute( + delete(UserDynamic).where(UserDynamic.dynamic_id == dynamic_id) + ) + connection.execute( + text("DELETE FROM dynamics WHERE id = :id"), {"id": dynamic_id} + ) + delete_public_api_rows(connection, rows) + cleanup_engine.dispose() + + +def test_saved_dynamics_move_at_sign_in_and_are_deleted_with_the_account( + sessions, stored_dynamic_id: UUID +) -> None: + """The runtime role saves, renames, merges and deletes users' saved dynamics.""" + browser = _browser(sessions) + alice = _principal(sessions, "google-oauth2|saved-dynamics") + deleted_subjects: list[str] = [] + + class RecordingDeleter: + def prepare_deletion(self) -> None: + return None + + def delete_user(self, subject: str) -> None: + deleted_subjects.append(subject) + + accounts = V2AccountService( + AccountDatabaseSession(sessions), + auth0_user_deleter_factory=RecordingDeleter, + ) + saved_dynamics = V2UserDynamicService(UserDynamicDatabaseSession(sessions)) + alice_id = accounts.get_account(principal=alice, country_id="us").id + fields = UserDynamicCreateFields( + country_id="us", dynamic_id=stored_dynamic_id, name="CBO responses" + ) + alices = saved_dynamics.create_user_dynamic( + principal=alice, association_input=fields + ) + browsers = saved_dynamics.create_user_dynamic( + principal=browser, association_input=fields + ) + saved_dynamics.patch_user_dynamic( + principal=browser, + country_id="us", + association_id=browsers.id, + association_input=UserDynamicUpdateInput(name="Browser's responses"), + ) + + upgrade = accounts.upgrade_account( + principal=alice, unauthenticated_user_id=browser.user_id, country_id="us" + ) + + assert upgrade.outcome is AccountConversionOutcome.MERGED + exported = accounts.export_account(principal=alice, country_id="us") + assert [(item.id, item.user_id, item.name) for item in exported.dynamics] == [ + (alices.id, alice_id, "CBO responses"), + (browsers.id, alice_id, "Browser's responses"), + ] + saved_dynamics.delete_user_dynamic( + principal=alice, country_id="us", association_id=alices.id + ) + + accounts.delete_account(principal=alice) + + assert deleted_subjects == [alice.subject] + assert ( + _count( + sessions, + select(func.count()) + .select_from(UserDynamic) + .where(UserDynamic.dynamic_id == stored_dynamic_id), + ) + == 0 + ) diff --git a/tests/unit/routes/test_migration_context_logging.py b/tests/unit/routes/test_migration_context_logging.py index 88e1f5844..c063f2f0a 100644 --- a/tests/unit/routes/test_migration_context_logging.py +++ b/tests/unit/routes/test_migration_context_logging.py @@ -523,6 +523,22 @@ class _UserResourceRequest(NamedTuple): _UserResourceRequest("POST", "/v2/me/upgrade", "user_profile", None, "supabase"), _UserResourceRequest("GET", "/v2/user-simulations", "simulation", "supabase", None), _UserResourceRequest("POST", "/v2/user-households", "household", None, "supabase"), + _UserResourceRequest("GET", "/v2/user-dynamics", "policy", "supabase", None), + _UserResourceRequest("POST", "/v2/user-dynamics", "policy", None, "supabase"), + _UserResourceRequest( + "PATCH", + "/v2/user-dynamics/00000000-0000-0000-0000-000000000001", + "policy", + None, + "supabase", + ), + _UserResourceRequest( + "DELETE", + "/v2/user-dynamics/00000000-0000-0000-0000-000000000001", + "policy", + None, + "supabase", + ), _UserResourceRequest( "POST", "/v2/user-simulations", "simulation", None, "supabase" ), @@ -578,6 +594,8 @@ def test_signed_in_user_resources_log_supabase_sources( ): method, path, route_group, db_read, db_write = request_case for name in ( + "DB_READ_POLICY", + "DB_WRITE_POLICY", "DB_READ_SIMULATION", "DB_WRITE_SIMULATION", "DB_READ_REPORT", diff --git a/tests/unit/test_alembic_workflows.py b/tests/unit/test_alembic_workflows.py index 73b063d32..5f2e1078f 100644 --- a/tests/unit/test_alembic_workflows.py +++ b/tests/unit/test_alembic_workflows.py @@ -214,6 +214,7 @@ def test_reusable_v2_alembic_check_uses_only_disposable_postgres(): assert "test_alembic_v2_user_types.py" in lifecycle_script assert "test_alembic_v2_withheld_area_codes.py" in lifecycle_script assert "test_alembic_v2_shared_report_keys.py" in lifecycle_script + assert "test_alembic_v2_user_dynamics.py" in lifecycle_script assert "redis:7.2-alpine" not in workflow assert "RUNTIME_CACHE_TEST_URL" not in workflow assert "test_v2_catalog_installed.py" not in workflow diff --git a/tests/unit/test_migration_contract_artifacts.py b/tests/unit/test_migration_contract_artifacts.py index 8ed1ad688..85319749e 100644 --- a/tests/unit/test_migration_contract_artifacts.py +++ b/tests/unit/test_migration_contract_artifacts.py @@ -13,8 +13,8 @@ def test_migration_contract_payload_summarizes_route_contracts(): assert payload["version"] == 1 assert payload["metadata"] == { "route_group_count": 9, - "workflow_count": 19, - "request_count": 103, + "workflow_count": 20, + "request_count": 113, "db_entity_count": 6, "sim_flow_count": 3, } @@ -23,6 +23,7 @@ def test_migration_contract_payload_summarizes_route_contracts(): "policy_resources_v2", "dynamic_resources_v2", "user_policy_associations_v2", + "user_dynamic_associations_v2", "household_save_read", "household_resources_v2", "household_calculations_v2", @@ -142,8 +143,8 @@ def test_user_contracts_require_a_signed_in_or_signed_out_credential(): headers_by_request = Counter(tuple(request["headers"]) for request in user_requests) assert headers_by_request == { - ("Authorization",): 26, - ("PolicyEngine-Unauthenticated-User",): 23, + ("Authorization",): 31, + ("PolicyEngine-Unauthenticated-User",): 28, ("Authorization", "PolicyEngine-Unauthenticated-User"): 1, } assert all("user_id=" not in request["path"] for request in user_requests) diff --git a/tests/unit/test_migration_flags.py b/tests/unit/test_migration_flags.py index 4ca5dd68f..0cde3ce94 100644 --- a/tests/unit/test_migration_flags.py +++ b/tests/unit/test_migration_flags.py @@ -180,6 +180,11 @@ def test_explicit_migration_context_rejects_invalid_database_sources( "/v2/user-policies/00000000-0000-0000-0000-000000000001", "policy", ), + ("/v2/user-dynamics", "policy"), + ( + "/v2/user-dynamics/00000000-0000-0000-0000-000000000001", + "policy", + ), ("/v2/user-households", "household"), ("/v2/household-calculations", "household"), ( diff --git a/tests/unit/v2/test_admin_user_routes.py b/tests/unit/v2/test_admin_user_routes.py index e4092a5c8..df6c25ba0 100644 --- a/tests/unit/v2/test_admin_user_routes.py +++ b/tests/unit/v2/test_admin_user_routes.py @@ -23,6 +23,7 @@ AccountDeletionUnavailableError, AccountIdentityDeletionError, ) +from policyengine_api.services.v2.user_dynamics.types import UserDynamicRead from policyengine_api.services.v2.user_households.types import UserHouseholdRead from policyengine_api.services.v2.user_policies.types import UserPolicyRead from policyengine_api.services.v2.user_reports.types import UserReportRead @@ -61,6 +62,8 @@ SAVED_HOUSEHOLD_ID = UUID("00000000-0000-0000-0000-000000000084") SAVED_SIMULATION_ID = UUID("00000000-0000-0000-0000-000000000085") SAVED_REPORT_ID = UUID("00000000-0000-0000-0000-000000000086") +SAVED_DYNAMIC_ID = UUID("00000000-0000-0000-0000-000000000087") +DYNAMIC_ID = UUID("00000000-0000-0000-0000-000000000088") LAST_SEEN_AT = datetime(2026, 2, 1, tzinfo=UTC) SAVED_ITEMS_PATH = f"/v2/admin/users/{TARGET_ID}/saved-items" @@ -120,6 +123,18 @@ def _saved_items() -> AccountExport: updated_at=CREATED_AT, ), ), + dynamics=( + UserDynamicRead( + id=SAVED_DYNAMIC_ID, + country_id="us", + user_id=TARGET_ID, + dynamic_id=DYNAMIC_ID, + name="Bob's assumptions", + description=None, + created_at=CREATED_AT, + updated_at=CREATED_AT, + ), + ), households=( UserHouseholdRead( id=SAVED_HOUSEHOLD_ID, @@ -300,10 +315,11 @@ def test_admins_read_a_users_saved_items_as_its_own_export_returns_them() -> Non assert result["user"]["id"] == str(TARGET_ID) assert [ (kind, item["id"], item["country_id"]) - for kind in ("policies", "households", "simulations", "reports") + for kind in ("policies", "dynamics", "households", "simulations", "reports") for item in result[kind] ] == [ ("policies", str(SAVED_POLICY_ID), "uk"), + ("dynamics", str(SAVED_DYNAMIC_ID), "us"), ("households", str(SAVED_HOUSEHOLD_ID), "us"), ("simulations", str(SAVED_SIMULATION_ID), "us"), ("reports", str(SAVED_REPORT_ID), "uk"), diff --git a/tests/unit/v2/test_alembic_v2_revisions.py b/tests/unit/v2/test_alembic_v2_revisions.py index da9be4836..562e74353 100644 --- a/tests/unit/v2/test_alembic_v2_revisions.py +++ b/tests/unit/v2/test_alembic_v2_revisions.py @@ -33,6 +33,7 @@ "simulation_runs", "stage12_evaluation_reports", "stage12_evaluation_simulations", + "user_dynamics", "user_identities", "user_invitations", "user_report_run_associations", @@ -69,8 +70,11 @@ # The user invitations revision, on the shared reports revision, and parent # of the dynamics revision. USER_INVITATIONS_REVISION = "f519a77ba122" -# The dynamics revision, on the user invitations revision. +# The dynamics revision, on the user invitations revision, and parent of the +# user dynamics revision. DYNAMICS_REVISION = "9d1d12a7ac58" +# The user dynamics revision, on the dynamics revision. +USER_DYNAMICS_REVISION = "d417fe8b1b17" def test_v2_revision_chain_has_generated_policy_and_user_identity_changes() -> None: @@ -79,6 +83,7 @@ def test_v2_revision_chain_has_generated_policy_and_user_identity_changes() -> N assert script.get_heads() == [V2_ALEMBIC_HEAD_REVISION] assert [revision.revision for revision in script.walk_revisions()] == [ V2_ALEMBIC_HEAD_REVISION, + DYNAMICS_REVISION, USER_INVITATIONS_REVISION, SHARED_REPORTS_REVISION, WITHHELD_AREA_CODES_REVISION, @@ -1155,7 +1160,6 @@ def test_dynamics_revision_stores_dynamics_like_policies_and_maps_them() -> None ] downgrade = revision[revision.index("def downgrade()") :] - assert V2_ALEMBIC_HEAD_REVISION == DYNAMICS_REVISION assert ( "Generation: uv run alembic -c alembic-v2.ini revision --autogenerate" in revision @@ -1209,3 +1213,48 @@ def test_dynamics_revision_stores_dynamics_like_policies_and_maps_them() -> None assert 'postgresql_where=sa.text("dynamic_id IS NOT NULL")' in upgrade assert "op.execute(" not in revision assert "op.bulk_insert(" not in revision + + +def test_user_dynamics_revision_creates_only_the_saved_dynamics_table() -> None: + """The revision after dynamics creates ``user_dynamics`` and nothing else. + + It is generated with no corrections, with its ID chosen through + ``--rev-id``: one table, whose keys name its user (``CASCADE``), its + country and a dynamic of that country (both ``RESTRICT``), with its + three indexes. The downgrade drops them, and neither writes data. + """ + (path,) = (REPO / "migrations/v2/versions").glob(f"{USER_DYNAMICS_REVISION}_*.py") + revision = path.read_text(encoding="utf-8") + upgrade = revision[ + revision.index("def upgrade()") : revision.index("def downgrade()") + ] + downgrade = revision[revision.index("def downgrade()") :] + + assert V2_ALEMBIC_HEAD_REVISION == USER_DYNAMICS_REVISION + assert ( + "Generation: uv run alembic -c alembic-v2.ini revision --autogenerate" + in revision + ) + assert f'down_revision: Union[str, None] = "{DYNAMICS_REVISION}"' in revision + assert "correction" not in revision.lower() + operations = [name for name in re.findall(r"op\.\w+", upgrade) if name != "op.f"] + assert sorted(operations) == ["op.create_index"] * 3 + ["op.create_table"] + reversals = [name for name in re.findall(r"op\.\w+", downgrade) if name != "op.f"] + assert sorted(reversals) == ["op.drop_index"] * 3 + ["op.drop_table"] + assert re.search(r'op\.create_table\(\s*"user_dynamics"', upgrade) + assert 'op.drop_table("user_dynamics")' in downgrade + for constraint_name in ( + "fk_user_dynamics_dynamic_country", + "uq_user_dynamics_id_country", + "ix_user_dynamics_country_user_created_id", + "ix_user_dynamics_country_dynamic", + ): + assert constraint_name in upgrade + assert re.search( + r'\["dynamic_id", "country_id"\],\s*\["dynamics\.id", "dynamics\.country_id"\]', + upgrade, + ) + assert upgrade.count('ondelete="RESTRICT"') == 2 + assert upgrade.count('ondelete="CASCADE"') == 1 + assert "op.execute(" not in revision + assert "op.bulk_insert(" not in revision diff --git a/tests/unit/v2/test_data_crud_boundaries.py b/tests/unit/v2/test_data_crud_boundaries.py index 96c6d08ea..49b912768 100644 --- a/tests/unit/v2/test_data_crud_boundaries.py +++ b/tests/unit/v2/test_data_crud_boundaries.py @@ -139,6 +139,7 @@ def test_database_session_modules_do_not_construct_queries( "identity/services.py", "legacy_refs/services.py", "user_accounts/services.py", + "user_dynamics/services.py", "user_households/services.py", "user_policies/services.py", "user_reports/services.py", diff --git a/tests/unit/v2/test_import_side_effects.py b/tests/unit/v2/test_import_side_effects.py index 9bd2d7389..637e6d406 100644 --- a/tests/unit/v2/test_import_side_effects.py +++ b/tests/unit/v2/test_import_side_effects.py @@ -69,7 +69,7 @@ def reject_ddl(*args, **kwargs): import sys after = set(pathlib.Path.cwd().iterdir()) assert before == after -assert len(V2_METADATA.tables) == 50 +assert len(V2_METADATA.tables) == 51 assert "policyengine_api.data.v2.catalog.initialization" not in sys.modules assert "policyengine_api.data.v2.policy_migration_qualification" not in sys.modules assert "policyengine_api.data.v2.household_migration_qualification" not in sys.modules diff --git a/tests/unit/v2/test_me_routes.py b/tests/unit/v2/test_me_routes.py index cb3b25afb..f2c5c723d 100644 --- a/tests/unit/v2/test_me_routes.py +++ b/tests/unit/v2/test_me_routes.py @@ -76,6 +76,7 @@ def _result(name: str, _kwargs: dict): return AccountExport( user=_account(), policies=(), + dynamics=(), households=(), simulations=(), reports=(), @@ -134,6 +135,7 @@ def typed_result(name: str, _kwargs: dict): "export_account": AccountExport( user=account, policies=(), + dynamics=(), households=(), simulations=(), reports=(), @@ -197,6 +199,7 @@ def test_export_and_delete_me() -> None: assert exported.json()["result"] == { "user": exported.json()["result"]["user"], "policies": [], + "dynamics": [], "households": [], "simulations": [], "reports": [], @@ -303,6 +306,7 @@ def result(name: str, kwargs: dict): return AccountExport( user=_account(), policies=(odd_policy,), + dynamics=(), households=(), simulations=(), reports=(odd_report,), @@ -370,7 +374,12 @@ def result(name: str, _kwargs: dict): msg = "The account was not found" raise AccountNotFoundError(msg) return AccountExport( - user=None, policies=(), households=(), simulations=(), reports=() + user=None, + policies=(), + dynamics=(), + households=(), + simulations=(), + reports=(), ) client, _service = _client( @@ -386,6 +395,7 @@ def result(name: str, _kwargs: dict): assert exported.json()["result"] == { "user": None, "policies": [], + "dynamics": [], "households": [], "simulations": [], "reports": [], diff --git a/tests/unit/v2/test_metadata_routes.py b/tests/unit/v2/test_metadata_routes.py index 9c5f65855..88e7f915e 100644 --- a/tests/unit/v2/test_metadata_routes.py +++ b/tests/unit/v2/test_metadata_routes.py @@ -344,6 +344,8 @@ def test_openapi_references_explicit_resource_response_schemas() -> None: "/v2/reports/{report_id}/runs", "/v2/simulations", "/v2/simulations/{simulation_id}", + "/v2/user-dynamics", + "/v2/user-dynamics/{association_id}", "/v2/user-households", "/v2/user-households/{association_id}", "/v2/user-policies", diff --git a/tests/unit/v2/test_models.py b/tests/unit/v2/test_models.py index d1316ecba..e81c86e92 100644 --- a/tests/unit/v2/test_models.py +++ b/tests/unit/v2/test_models.py @@ -28,6 +28,7 @@ SimulationRun, TaxBenefitModelVersion, User, + UserDynamic, UserHouseholdAssociation, UserIdentity, UserPolicy, @@ -42,8 +43,10 @@ ("users", "primary_country"), ("households", "country_id"), ("policies", "country_id"), + ("dynamics", "country_id"), ("user_household_associations", "country_id"), ("user_policies", "country_id"), + ("user_dynamics", "country_id"), ("user_simulation_associations", "country_id"), ("user_report_associations", "country_id"), ) @@ -80,6 +83,7 @@ def test_domain_models_are_grouped_into_topic_scoped_modules() -> None: SimulationRun: "simulations", UserHouseholdAssociation: "associations", UserPolicy: "associations", + UserDynamic: "associations", LegacyPolicyMapping: "policy_mappings", LegacyUserMapping: "policy_mappings", LegacyUserPolicyMapping: "policy_mappings", @@ -153,6 +157,7 @@ def test_user_owned_associations_have_relational_integrity() -> None: "simulation_associations", ), (UserPolicy, "user_policies", "policy_associations"), + (UserDynamic, "user_dynamics", "dynamic_associations"), (UserReportAssociation, "user_report_associations", "report_associations"), ) diff --git a/tests/unit/v2/test_privilege_manifest.py b/tests/unit/v2/test_privilege_manifest.py index 77152f580..f577472c3 100644 --- a/tests/unit/v2/test_privilege_manifest.py +++ b/tests/unit/v2/test_privilege_manifest.py @@ -496,3 +496,23 @@ def test_api_v1_creates_and_reads_dynamics_but_never_changes_them() -> None: assert declared[SIMULATION_SERVICE_ROLE]["dynamics"] == READ assert declared[MODAL_WORKER_ROLE]["dynamics"] == READ assert declared[CATALOG_WRITER_ROLE]["dynamics"] == NO_ACCESS + + +def test_api_v1_saves_users_dynamics_as_it_saves_their_policies() -> None: + """Users' saved dynamics are written as saved policies are, by API v1 alone. + + API v1 creates, renames, repoints and deletes a user's saved dynamics, and + moves a browser's saved dynamics to the account it signs in to, so it holds + every privilege it holds on ``user_policies``. The simulation service, its + Modal workers and the catalog writer never read them. + """ + declared = declared_privileges(TEST_ENVIRONMENT) + + assert declared[RUNTIME_ROLE]["user_dynamics"] == READ_WRITE + assert ( + declared[RUNTIME_ROLE]["user_dynamics"] + == declared[RUNTIME_ROLE]["user_policies"] + ) + for role, tables in declared.items(): + if role != RUNTIME_ROLE: + assert tables["user_dynamics"] == NO_ACCESS, role diff --git a/tests/unit/v2/test_user_dynamic_routes.py b/tests/unit/v2/test_user_dynamic_routes.py new file mode 100644 index 000000000..880be8a24 --- /dev/null +++ b/tests/unit/v2/test_user_dynamic_routes.py @@ -0,0 +1,375 @@ +"""Native FastAPI contract tests for users' saved dynamics (``/v2/user-dynamics``).""" + +from __future__ import annotations + +from datetime import timedelta +from typing import TYPE_CHECKING, Any +from uuid import UUID + +import pytest +from sqlalchemy.exc import IntegrityError, SQLAlchemyError + +from policyengine_api.data.v2.settings import V2ConfigurationError +from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicFilter, + UserDynamicPage, + UserDynamicRead, +) +from policyengine_api.services.v2.user_dynamics.validators import ( + AssociationDynamicCountryConflictError, + AssociationDynamicNotFoundError, + UserDynamicNotFoundError, +) +from tests.unit.v2.user_route_support import ( + CREATED_AT, + OWNER_ID, + PRINCIPAL, + UNAUTHENTICATED_PRINCIPAL, + RecordingService, + signed_out_browser, + user_route_client, +) + +if TYPE_CHECKING: + from collections.abc import Callable + + from fastapi.testclient import TestClient + +SAVED_DYNAMIC_ID = UUID("00000000-0000-0000-0000-000000000061") +DYNAMIC_ID = UUID("00000000-0000-0000-0000-000000000011") +OTHER_DYNAMIC_ID = UUID("00000000-0000-0000-0000-000000000012") +DETAIL_PATH = f"/v2/user-dynamics/{SAVED_DYNAMIC_ID}?country_id=us" + + +def _saved_dynamic_read(**changes: Any) -> UserDynamicRead: + values: dict[str, Any] = { + "id": SAVED_DYNAMIC_ID, + "country_id": "us", + "user_id": OWNER_ID, + "dynamic_id": DYNAMIC_ID, + "name": "CBO labour supply responses", + "description": "Income and substitution elasticities", + "created_at": CREATED_AT, + "updated_at": CREATED_AT + timedelta(seconds=1), + } + values.update(changes) + return UserDynamicRead(**values) + + +def _result( + name: str, kwargs: dict[str, Any] +) -> UserDynamicRead | UserDynamicPage | None: + if name == "list_user_dynamics": + return UserDynamicPage( + items=(_saved_dynamic_read(),), + offset=kwargs["offset"], + limit=kwargs["limit"], + has_more=False, + ) + if name == "delete_user_dynamic": + return None + return _saved_dynamic_read() + + +def _client( + service: RecordingService | None = None, + *, + require_user: Callable[..., Any] | None = None, +) -> tuple[TestClient, RecordingService, dict[str, int]]: + recording_service = service or RecordingService(_result) + principal_overrides = {} if require_user is None else {"require_user": require_user} + client, flask_calls = user_route_client( + v2_user_dynamic_service_factory=lambda: recording_service, + **principal_overrides, + ) + return client, recording_service, flask_calls + + +def _body(**changes: object) -> dict[str, object]: + body: dict[str, object] = { + "country_id": "us", + "dynamic_id": str(DYNAMIC_ID), + "name": "CBO labour supply responses", + "description": "Income and substitution elasticities", + } + body.update(changes) + return body + + +def test_create_returns_the_saved_dynamic_owned_by_the_session_user() -> None: + client, service, flask_calls = _client() + + response = client.post("/v2/user-dynamics?country_id=US", json=_body()) + + assert response.status_code == 201 + assert response.json() == { + "status": "ok", + "message": None, + "result": { + "item": { + "id": str(SAVED_DYNAMIC_ID), + "country_id": "us", + "user_id": str(OWNER_ID), + "dynamic_id": str(DYNAMIC_ID), + "name": "CBO labour supply responses", + "description": "Income and substitution elasticities", + "created_at": "2026-01-01T00:00:00Z", + "updated_at": "2026-01-01T00:00:01Z", + } + }, + } + name, kwargs = service.calls[0] + assert name == "create_user_dynamic" + assert kwargs["principal"] == PRINCIPAL + fields = kwargs["association_input"] + assert (fields.country_id, fields.dynamic_id) == ("us", DYNAMIC_ID) + assert not hasattr(fields, "user_id") + assert flask_calls["count"] == 0 + + +def test_a_signed_out_browser_saves_dynamics_as_itself() -> None: + client, service, _flask_calls = _client(require_user=signed_out_browser) + + response = client.post("/v2/user-dynamics?country_id=us", json=_body()) + + assert response.status_code == 201 + assert service.calls[0][1]["principal"] == UNAUTHENTICATED_PRINCIPAL + + +@pytest.mark.parametrize( + "body", + [ + _body(user_id=str(OWNER_ID)), + {"country_id": "us", "name": "No dynamic"}, + _body(dynamic_id=None), + _body(dynamic_id="not-a-uuid"), + _body(legacy_policy_id=1), + _body(baseline="current-law"), + _body(name="x" * 256), + _body(description="x" * 10_001), + ], +) +def test_create_rejects_owners_missing_dynamics_and_invalid_fields( + body: dict[str, object], +) -> None: + client, service, _flask_calls = _client() + + response = client.post("/v2/user-dynamics?country_id=us", json=body) + + assert response.status_code == 422 + assert response.json() == { + "status": "error", + "message": "Invalid API v2 request", + } + assert service.calls == [] + + +def test_create_rejects_a_body_country_unlike_the_query_country() -> None: + client, service, _flask_calls = _client() + + response = client.post("/v2/user-dynamics?country_id=uk", json=_body()) + + assert response.status_code == 400 + assert service.calls == [] + + +def test_detail_and_list_are_scoped_to_the_session_user() -> None: + client, service, _flask_calls = _client() + + detail = client.get(f"/v2/user-dynamics/{SAVED_DYNAMIC_ID}?country_id=US") + page = client.get( + f"/v2/user-dynamics?country_id=us&dynamic_id={DYNAMIC_ID}&offset=2&limit=3" + ) + + assert detail.status_code == 200 + assert page.status_code == 200 + assert service.calls == [ + ( + "get_user_dynamic", + { + "principal": PRINCIPAL, + "country_id": "us", + "association_id": SAVED_DYNAMIC_ID, + }, + ), + ( + "list_user_dynamics", + { + "principal": PRINCIPAL, + "country_id": "us", + "dynamic_filter": UserDynamicFilter(dynamic_id=DYNAMIC_ID), + "offset": 2, + "limit": 3, + }, + ), + ] + assert page.json()["result"] == { + "items": [detail.json()["result"]["item"]], + "offset": 2, + "limit": 3, + "has_more": False, + } + + +def test_collection_rejects_owners_unknown_duplicate_and_invalid_queries() -> None: + client, service, _flask_calls = _client() + + responses = [ + client.get(f"/v2/user-dynamics?country_id=us&user_id={OWNER_ID}"), + client.get("/v2/user-dynamics"), + client.get("/v2/user-dynamics?country_id=us&legacy_policy_id=1"), + client.get("/v2/user-dynamics?country_id=us&country_id=uk"), + client.get("/v2/user-dynamics?country_id=us&limit=501"), + client.get("/v2/user-dynamics?country_id=us&dynamic_id=not-a-uuid"), + ] + + assert [response.status_code for response in responses] == [422] * 6 + assert all(response.json()["status"] == "error" for response in responses) + assert service.calls == [] + + +def test_patch_renames_or_repoints_and_rejects_invalid_changes() -> None: + client, service, flask_calls = _client() + + renamed = client.patch(DETAIL_PATH, json={"name": "Renamed", "description": None}) + repointed = client.patch(DETAIL_PATH, json={"dynamic_id": str(OTHER_DYNAMIC_ID)}) + invalid = [ + client.patch(DETAIL_PATH, json=body) + for body in ( + {"dynamic_id": None}, + {"dynamic_id": "not-a-uuid"}, + {"user_id": str(OWNER_ID)}, + {"country_id": "uk"}, + {"legacy_policy_id": 1}, + {}, + ) + ] + + assert renamed.status_code == 200 + assert repointed.status_code == 200 + rename_input = service.calls[0][1]["association_input"] + repoint_input = service.calls[1][1]["association_input"] + assert rename_input.model_fields_set == {"name", "description"} + assert (rename_input.name, rename_input.description) == ("Renamed", None) + assert repoint_input.model_fields_set == {"dynamic_id"} + assert repoint_input.dynamic_id == OTHER_DYNAMIC_ID + assert [response.status_code for response in invalid] == [422] * 6 + assert [call[0] for call in service.calls] == [ + "patch_user_dynamic", + "patch_user_dynamic", + ] + assert service.calls[0][1]["association_id"] == SAVED_DYNAMIC_ID + assert flask_calls["count"] == 0 + + +def test_delete_returns_no_content_for_the_session_user() -> None: + client, service, _flask_calls = _client() + + response = client.delete(DETAIL_PATH) + + assert response.status_code == 204 + assert response.content == b"" + assert service.calls == [ + ( + "delete_user_dynamic", + { + "principal": PRINCIPAL, + "country_id": "us", + "association_id": SAVED_DYNAMIC_ID, + }, + ) + ] + + +@pytest.mark.parametrize( + ("error", "status", "message"), + [ + ( + AssociationDynamicCountryConflictError("another country's dynamic"), + 400, + "country", + ), + (AssociationDynamicNotFoundError("dynamic was not found"), 404, "not found"), + (UserDynamicNotFoundError("saved dynamic was not found"), 404, "not found"), + ( + IntegrityError("statement secret", {}, Exception("credential")), + 409, + "conflicts", + ), + (V2ConfigurationError("postgresql://secret"), 503, "unavailable"), + (SQLAlchemyError("statement secret"), 503, "unavailable"), + (RuntimeError("credential and caller data"), 500, "operation failed"), + ], +) +def test_failures_map_to_secret_safe_typed_errors( + error: Exception, + status: int, + message: str, +) -> None: + service = RecordingService(_result) + service.error = error + client, _service, _flask_calls = _client(service) + + responses = [ + client.post("/v2/user-dynamics?country_id=us", json=_body()), + client.get(DETAIL_PATH), + client.patch(DETAIL_PATH, json={"name": "Renamed"}), + client.delete(DETAIL_PATH), + ] + + for response in responses: + assert response.status_code == status + assert response.json()["status"] == "error" + assert message in response.json()["message"].lower() + assert "secret" not in response.text + assert "credential" not in response.text + + +def test_openapi_publishes_the_saved_dynamic_contracts() -> None: + client, _service, _flask_calls = _client() + schema = client.get("/v2/openapi.json").json() + + collection = schema["paths"]["/v2/user-dynamics"]["get"] + parameters = {item["name"]: item for item in collection["parameters"]} + assert set(parameters) == {"country_id", "offset", "limit", "dynamic_id"} + assert parameters["limit"]["schema"]["maximum"] == 500 + for path, method in ( + ("/v2/user-dynamics", "post"), + ("/v2/user-dynamics", "get"), + ("/v2/user-dynamics/{association_id}", "get"), + ("/v2/user-dynamics/{association_id}", "patch"), + ("/v2/user-dynamics/{association_id}", "delete"), + ): + operation = schema["paths"][path][method] + assert {"400", "401", "403", "404", "409", "422", "500", "503"} <= set( + operation["responses"] + ) + + item_schema = schema["components"]["schemas"]["UserDynamicItem"] + assert set(item_schema["required"]) == { + "id", + "country_id", + "user_id", + "dynamic_id", + "name", + "description", + "created_at", + "updated_at", + } + create_ref = schema["paths"]["/v2/user-dynamics"]["post"]["requestBody"]["content"][ + "application/json" + ]["schema"]["$ref"] + create_schema = schema["components"]["schemas"][create_ref.rsplit("/", 1)[-1]] + assert create_schema["additionalProperties"] is False + assert set(create_schema["properties"]) == { + "country_id", + "dynamic_id", + "name", + "description", + } + assert set(create_schema["required"]) == {"country_id", "dynamic_id"} + patch = schema["paths"]["/v2/user-dynamics/{association_id}"]["patch"] + patch_ref = patch["requestBody"]["content"]["application/json"]["schema"]["$ref"] + patch_schema = schema["components"]["schemas"][patch_ref.rsplit("/", 1)[-1]] + assert patch_schema["additionalProperties"] is False + assert set(patch_schema["properties"]) == {"dynamic_id", "name", "description"} diff --git a/tests/unit/v2/test_user_dynamic_service.py b/tests/unit/v2/test_user_dynamic_service.py new file mode 100644 index 000000000..a7b87e358 --- /dev/null +++ b/tests/unit/v2/test_user_dynamic_service.py @@ -0,0 +1,478 @@ +"""Service tests for users' saved dynamics (``user_dynamics``).""" + +from __future__ import annotations + +from typing import TYPE_CHECKING +from uuid import uuid4 + +import pytest +from pydantic import ValidationError +from sqlalchemy import delete, func, select +from sqlalchemy.exc import IntegrityError + +from policyengine_api.data.v2.models import Dynamic, User, UserDynamic, UserType +from policyengine_api.services.v2.identity.types import AccountConversionOutcome +from policyengine_api.services.v2.user_accounts.database_session import ( + AccountDatabaseSession, +) +from policyengine_api.services.v2.user_accounts.services import V2AccountService +from policyengine_api.services.v2.user_dynamics.database_session import ( + UserDynamicDatabaseSession, +) +from policyengine_api.services.v2.user_dynamics.services import ( + V2UserDynamicService, + create_user_dynamic_in_session, +) +from policyengine_api.services.v2.user_dynamics.types import ( + UserDynamicCreateFields, + UserDynamicCreationInput, + UserDynamicFilter, + UserDynamicUpdateInput, +) +from policyengine_api.services.v2.user_dynamics.validators import ( + AssociationDynamicCountryConflictError, + AssociationDynamicNotFoundError, + UserDynamicNotFoundError, +) +from tests.unit.v2.user_service_support import ( + ALICE, + BOB, + OTHER_SIGNED_OUT_BROWSER, + SIGNED_OUT_BROWSER, + V2Store, + v2_store, +) + +if TYPE_CHECKING: + from collections.abc import Iterator + from uuid import UUID + + +@pytest.fixture +def store() -> Iterator[V2Store]: + with v2_store() as selected: + yield selected + + +@pytest.fixture +def saved_dynamics(store: V2Store) -> V2UserDynamicService: + return V2UserDynamicService(UserDynamicDatabaseSession(store.sessions)) + + +def _fields(dynamic_id: UUID, **changes: object) -> UserDynamicCreateFields: + values: dict[str, object] = { + "country_id": "us", + "dynamic_id": dynamic_id, + "name": "CBO labour supply responses", + "description": "Income and substitution elasticities", + } + values.update(changes) + return UserDynamicCreateFields.model_validate(values) + + +def _saved_dynamic_count(store: V2Store) -> int: + with store.sessions() as session: + return int( + session.execute(select(func.count()).select_from(UserDynamic)).scalar_one() + ) + + +def test_first_save_provisions_the_owner_and_stores_the_name( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + created = saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + + assert created.country_id == "us" + assert created.dynamic_id == store.dynamic_id + assert created.name == "CBO labour supply responses" + assert created.description == "Income and substitution elasticities" + with store.sessions() as session: + owner = session.get(User, created.user_id) + stored = session.get(UserDynamic, created.id) + assert owner is not None + assert owner.user_type == UserType.STANDARD.value + assert stored is not None + assert stored.user_id == created.user_id + assert ( + saved_dynamics.get_user_dynamic( + principal=ALICE, country_id="us", association_id=created.id + ) + == created + ) + + +def test_a_signed_out_browser_saves_and_reads_only_its_own_dynamics( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + before = saved_dynamics.list_user_dynamics( + principal=SIGNED_OUT_BROWSER, country_id="us" + ) + with store.sessions() as session: + assert session.get(User, SIGNED_OUT_BROWSER.user_id) is None + + created = saved_dynamics.create_user_dynamic( + principal=SIGNED_OUT_BROWSER, association_input=_fields(store.dynamic_id) + ) + listed = saved_dynamics.list_user_dynamics( + principal=SIGNED_OUT_BROWSER, country_id="us" + ) + + assert before.items == () + assert created.user_id == SIGNED_OUT_BROWSER.user_id + assert [item.id for item in listed.items] == [created.id] + with store.sessions() as session: + browser_user = session.get(User, SIGNED_OUT_BROWSER.user_id) + assert browser_user is not None + assert browser_user.user_type == UserType.UNAUTHENTICATED.value + assert ( + saved_dynamics.list_user_dynamics( + principal=OTHER_SIGNED_OUT_BROWSER, country_id="us" + ).items + == () + ) + with pytest.raises(UserDynamicNotFoundError): + saved_dynamics.get_user_dynamic( + principal=OTHER_SIGNED_OUT_BROWSER, + country_id="us", + association_id=created.id, + ) + + +def test_another_users_saved_dynamic_cannot_be_read_changed_or_deleted( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + created = saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + saved_dynamics.create_user_dynamic( + principal=BOB, association_input=_fields(store.dynamic_id, name="Bob's") + ) + + with pytest.raises(UserDynamicNotFoundError): + saved_dynamics.get_user_dynamic( + principal=BOB, country_id="us", association_id=created.id + ) + with pytest.raises(UserDynamicNotFoundError): + saved_dynamics.patch_user_dynamic( + principal=BOB, + country_id="us", + association_id=created.id, + association_input=UserDynamicUpdateInput(name="Taken over"), + ) + with pytest.raises(UserDynamicNotFoundError): + saved_dynamics.delete_user_dynamic( + principal=BOB, country_id="us", association_id=created.id + ) + with pytest.raises(UserDynamicNotFoundError): + saved_dynamics.get_user_dynamic( + principal=ALICE, country_id="uk", association_id=created.id + ) + + bobs_names = [ + item.name + for item in saved_dynamics.list_user_dynamics( + principal=BOB, country_id="us" + ).items + ] + assert bobs_names == ["Bob's"] + assert ( + saved_dynamics.get_user_dynamic( + principal=ALICE, country_id="us", association_id=created.id + ) + == created + ) + + +def test_a_saved_dynamic_names_a_dynamic_stored_in_its_own_country( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + with pytest.raises(AssociationDynamicCountryConflictError): + saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.uk_dynamic_id) + ) + with pytest.raises(AssociationDynamicNotFoundError): + saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(uuid4()) + ) + + assert _saved_dynamic_count(store) == 0 + uk_saved = saved_dynamics.create_user_dynamic( + principal=ALICE, + association_input=_fields(store.uk_dynamic_id, country_id="uk"), + ) + assert uk_saved.country_id == "uk" + + +def test_patch_renames_and_repoints_within_the_country( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + created = saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + + renamed = saved_dynamics.patch_user_dynamic( + principal=ALICE, + country_id="us", + association_id=created.id, + association_input=UserDynamicUpdateInput(name="Renamed", description=None), + ) + repointed = saved_dynamics.patch_user_dynamic( + principal=ALICE, + country_id="us", + association_id=created.id, + association_input=UserDynamicUpdateInput(dynamic_id=store.other_dynamic_id), + ) + with pytest.raises(AssociationDynamicCountryConflictError): + saved_dynamics.patch_user_dynamic( + principal=ALICE, + country_id="us", + association_id=created.id, + association_input=UserDynamicUpdateInput(dynamic_id=store.uk_dynamic_id), + ) + with pytest.raises(AssociationDynamicNotFoundError): + saved_dynamics.patch_user_dynamic( + principal=ALICE, + country_id="us", + association_id=created.id, + association_input=UserDynamicUpdateInput(dynamic_id=uuid4()), + ) + + assert (renamed.name, renamed.description, renamed.dynamic_id) == ( + "Renamed", + None, + store.dynamic_id, + ) + assert renamed.updated_at > created.updated_at + assert (repointed.name, repointed.dynamic_id) == ( + "Renamed", + store.other_dynamic_id, + ) + assert (repointed.id, repointed.user_id, repointed.created_at) == ( + created.id, + created.user_id, + created.created_at, + ) + assert ( + saved_dynamics.get_user_dynamic( + principal=ALICE, country_id="us", association_id=created.id + ) + == repointed + ) + + +@pytest.mark.parametrize( + "update", + [{}, {"dynamic_id": None}, {"user_id": str(uuid4())}, {"name": "x" * 256}], +) +def test_an_update_names_a_change_and_never_clears_the_dynamic( + update: dict[str, object], +) -> None: + with pytest.raises(ValidationError): + UserDynamicUpdateInput.model_validate(update) + + +@pytest.mark.parametrize( + "fields", + [ + {"country_id": "us"}, + {"country_id": "us", "dynamic_id": None}, + {"country_id": "fr", "dynamic_id": str(uuid4())}, + {"country_id": "us", "dynamic_id": str(uuid4()), "user_id": str(uuid4())}, + {"country_id": "us", "dynamic_id": str(uuid4()), "legacy_policy_id": 1}, + ], +) +def test_a_save_names_one_dynamic_and_no_owner_or_v1_reference( + fields: dict[str, object], +) -> None: + with pytest.raises(ValidationError): + UserDynamicCreateFields.model_validate(fields) + + +def test_delete_removes_only_the_saved_dynamic( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + created = saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + + saved_dynamics.delete_user_dynamic( + principal=ALICE, country_id="us", association_id=created.id + ) + + with pytest.raises(UserDynamicNotFoundError): + saved_dynamics.get_user_dynamic( + principal=ALICE, country_id="us", association_id=created.id + ) + with pytest.raises(UserDynamicNotFoundError): + saved_dynamics.delete_user_dynamic( + principal=ALICE, country_id="us", association_id=created.id + ) + with store.sessions() as session: + assert session.get(Dynamic, store.dynamic_id) is not None + + +def test_list_pages_in_creation_order_and_filters_by_dynamic( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + created = [ + saved_dynamics.create_user_dynamic( + principal=ALICE, + association_input=_fields(dynamic_id, name=f"Saved {position}"), + ) + for position, dynamic_id in enumerate( + (store.dynamic_id, store.other_dynamic_id, store.dynamic_id) + ) + ] + + first_page = saved_dynamics.list_user_dynamics( + principal=ALICE, country_id="us", offset=0, limit=2 + ) + second_page = saved_dynamics.list_user_dynamics( + principal=ALICE, country_id="us", offset=2, limit=2 + ) + filtered = saved_dynamics.list_user_dynamics( + principal=ALICE, + country_id="us", + dynamic_filter=UserDynamicFilter(dynamic_id=store.dynamic_id), + ) + + assert [item.id for item in first_page.items] == [created[0].id, created[1].id] + assert first_page.has_more is True + assert [item.id for item in second_page.items] == [created[2].id] + assert second_page.has_more is False + assert [item.id for item in filtered.items] == [created[0].id, created[2].id] + assert ( + saved_dynamics.list_user_dynamics(principal=ALICE, country_id="uk").items == () + ) + + +def test_a_dynamic_that_a_user_saved_cannot_be_deleted( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + + with pytest.raises(IntegrityError), store.sessions.begin() as session: + session.execute(delete(Dynamic).where(Dynamic.id == store.dynamic_id)) + + +def test_deleting_a_user_deletes_their_saved_dynamics( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + alices = saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + bobs = saved_dynamics.create_user_dynamic( + principal=BOB, association_input=_fields(store.dynamic_id) + ) + + with store.sessions.begin() as session: + session.execute(delete(User).where(User.id == alices.user_id)) + + with store.sessions() as session: + assert session.get(UserDynamic, alices.id) is None + assert session.get(UserDynamic, bobs.id) is not None + assert session.get(Dynamic, store.dynamic_id) is not None + + +def test_signing_in_moves_a_browsers_saved_dynamics_to_the_account( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + accounts = V2AccountService(AccountDatabaseSession(store.sessions)) + alice_id = accounts.get_account(principal=ALICE, country_id="us").id + alices = saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + browsers = saved_dynamics.create_user_dynamic( + principal=SIGNED_OUT_BROWSER, + association_input=_fields(store.other_dynamic_id, name="Browser's"), + ) + + upgrade = accounts.upgrade_account( + principal=ALICE, + unauthenticated_user_id=SIGNED_OUT_BROWSER.user_id, + country_id="us", + ) + + assert upgrade.outcome is AccountConversionOutcome.MERGED + moved = saved_dynamics.get_user_dynamic( + principal=ALICE, country_id="us", association_id=browsers.id + ) + assert (moved.user_id, moved.name, moved.created_at, moved.updated_at) == ( + alice_id, + "Browser's", + browsers.created_at, + browsers.updated_at, + ) + assert [ + item.id + for item in saved_dynamics.list_user_dynamics( + principal=ALICE, country_id="us" + ).items + ] == [alices.id, browsers.id] + + +def test_the_account_export_lists_saved_dynamics_in_every_country( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + accounts = V2AccountService(AccountDatabaseSession(store.sessions)) + us_saved = saved_dynamics.create_user_dynamic( + principal=ALICE, association_input=_fields(store.dynamic_id) + ) + uk_saved = saved_dynamics.create_user_dynamic( + principal=ALICE, + association_input=_fields(store.uk_dynamic_id, country_id="uk"), + ) + saved_dynamics.create_user_dynamic( + principal=BOB, association_input=_fields(store.dynamic_id) + ) + + exported = accounts.export_account(principal=ALICE, country_id="us") + browser_export = accounts.export_account( + principal=SIGNED_OUT_BROWSER, country_id="us" + ) + + assert exported.dynamics == (us_saved, uk_saved) + assert browser_export.user is None + assert browser_export.dynamics == () + + +def test_the_migration_saves_a_dynamic_for_a_user_it_names( + store: V2Store, saved_dynamics: V2UserDynamicService +) -> None: + owner_id = ( + V2AccountService(AccountDatabaseSession(store.sessions)) + .get_account(principal=ALICE, country_id="us") + .id + ) + creation_input = UserDynamicCreationInput( + country_id="us", + user_id=owner_id, + dynamic_id=store.dynamic_id, + name="Saved reform's assumptions", + description=None, + ) + + with store.sessions.begin() as session: + created = create_user_dynamic_in_session(session, creation_input) + with ( + pytest.raises(AssociationDynamicCountryConflictError), + store.sessions.begin() as session, + ): + create_user_dynamic_in_session( + session, + creation_input.model_copy(update={"dynamic_id": store.uk_dynamic_id}), + ) + + assert created.user_id == owner_id + assert created.name == "Saved reform's assumptions" + assert ( + saved_dynamics.get_user_dynamic( + principal=ALICE, country_id="us", association_id=created.id + ) + == created + ) + assert _saved_dynamic_count(store) == 1 diff --git a/tests/unit/v2/test_user_route_auth.py b/tests/unit/v2/test_user_route_auth.py index 8da0adbb8..a0029164e 100644 --- a/tests/unit/v2/test_user_route_auth.py +++ b/tests/unit/v2/test_user_route_auth.py @@ -71,11 +71,19 @@ def install(claims: Mapping[str, Any] | Exception) -> FakeDecoder: def _services() -> tuple[dict[str, RecordingService], dict[str, Any]]: services = { name: RecordingService() - for name in ("account", "policy", "household", "simulation", "report") + for name in ( + "account", + "policy", + "dynamic", + "household", + "simulation", + "report", + ) } factories = { "v2_account_service_factory": lambda: services["account"], "v2_user_policy_service_factory": lambda: services["policy"], + "v2_user_dynamic_service_factory": lambda: services["dynamic"], "v2_user_household_service_factory": lambda: services["household"], "v2_user_simulation_service_factory": lambda: services["simulation"], "v2_user_report_service_factory": lambda: services["report"], @@ -95,8 +103,8 @@ def _user_operations() -> list[tuple[str, str]]: for method in methods if method in {"get", "post", "patch", "delete"} ) - # 5 account operations plus 5 for each of the 4 association resources. - assert len(operations) >= 25 + # 5 account operations plus 5 for each of the 5 association resources. + assert len(operations) >= 30 return operations @@ -420,7 +428,12 @@ def test_a_bearer_token_takes_precedence_over_the_unauthenticated_header( configured_auth({"iss": ISSUER, "sub": "google-oauth2|42"}) services, factories = _services() services["account"].next_result = AccountExport( - user=None, policies=(), households=(), simulations=(), reports=() + user=None, + policies=(), + dynamics=(), + households=(), + simulations=(), + reports=(), ) client, _flask_calls = user_route_client(require_user=None, **factories) diff --git a/tests/unit/v2/test_user_write_limits.py b/tests/unit/v2/test_user_write_limits.py index 16c64c8cf..5ec9e0246 100644 --- a/tests/unit/v2/test_user_write_limits.py +++ b/tests/unit/v2/test_user_write_limits.py @@ -49,11 +49,19 @@ def _services() -> tuple[dict[str, RecordingService], dict[str, Any]]: services = { name: RecordingService() - for name in ("account", "policy", "household", "simulation", "report") + for name in ( + "account", + "policy", + "dynamic", + "household", + "simulation", + "report", + ) } factories = { "v2_account_service_factory": lambda: services["account"], "v2_user_policy_service_factory": lambda: services["policy"], + "v2_user_dynamic_service_factory": lambda: services["dynamic"], "v2_user_household_service_factory": lambda: services["household"], "v2_user_simulation_service_factory": lambda: services["simulation"], "v2_user_report_service_factory": lambda: services["report"], diff --git a/tests/unit/v2/user_service_support.py b/tests/unit/v2/user_service_support.py index 6018df644..3e4488b45 100644 --- a/tests/unit/v2/user_service_support.py +++ b/tests/unit/v2/user_service_support.py @@ -14,6 +14,7 @@ from policyengine_api.data.v2.models import ( V2_METADATA, + Dynamic, Household, LegacyHouseholdMapping, LegacyPolicyMapping, @@ -108,6 +109,9 @@ class V2Store: uk_policy_id: UUID household_id: UUID uk_household_id: UUID + dynamic_id: UUID + other_dynamic_id: UUID + uk_dynamic_id: UUID @contextmanager @@ -177,7 +181,21 @@ def begin_transaction(connection) -> None: canonicalization_version=1, content_hash="f" * 64, ) - session.add_all([value, uk_policy, household, uk_household]) + dynamics = { + name: Dynamic( + country_id=country_id, + tax_benefit_model=model, + tax_benefit_model_version=version, + canonicalization_version=1, + content_hash=content_hash * 64, + ) + for name, country_id, content_hash in ( + ("us", "us", "1"), + ("other_us", "us", "2"), + ("uk", "uk", "3"), + ) + } + session.add_all([value, uk_policy, household, uk_household, *dynamics.values()]) session.flush() session.add_all( [ @@ -204,6 +222,9 @@ def begin_transaction(connection) -> None: uk_policy_id=uk_policy.id, household_id=household.id, uk_household_id=uk_household.id, + dynamic_id=dynamics["us"].id, + other_dynamic_id=dynamics["other_us"].id, + uk_dynamic_id=dynamics["uk"].id, ) try: yield store