graphcore-kernel 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- graphcore/__init__.py +5 -0
- graphcore/agent_frontend/__init__.py +8 -0
- graphcore/agent_frontend/api.py +69 -0
- graphcore/agent_frontend/base/__init__.py +11 -0
- graphcore/agent_frontend/base/views.py +167 -0
- graphcore/agent_frontend/client.py +31 -0
- graphcore/agent_frontend/context.py +157 -0
- graphcore/agent_frontend/errors.py +12 -0
- graphcore/agent_frontend/loading.py +54 -0
- graphcore/agent_frontend/registry.py +42 -0
- graphcore/agent_frontend/render.py +207 -0
- graphcore/agent_frontend/server.py +103 -0
- graphcore/agent_frontend/signatures.py +35 -0
- graphcore/agent_frontend/testing.py +45 -0
- graphcore/agent_frontend/tests/__init__.py +0 -0
- graphcore/agent_frontend/tests/fakes.py +114 -0
- graphcore/agent_frontend/tests/test_frontend.py +447 -0
- graphcore/agent_frontend/tests/test_loading.py +83 -0
- graphcore/agent_frontend/tests/test_server.py +109 -0
- graphcore/agent_frontend/tools.py +137 -0
- graphcore/api/__init__.py +4 -0
- graphcore/api/graph_api.py +378 -0
- graphcore/api/predicate_codec.py +81 -0
- graphcore/api/tests/__init__.py +0 -0
- graphcore/api/tests/test_changed_entities.py +109 -0
- graphcore/api/tests/test_graph_api.py +290 -0
- graphcore/api/tests/test_graph_api_access.py +94 -0
- graphcore/api/tests/test_graph_api_grants.py +90 -0
- graphcore/api/tests/test_predicate_codec.py +83 -0
- graphcore/api/tests/test_subtree_query.py +79 -0
- graphcore/apps.py +71 -0
- graphcore/auth/__init__.py +1 -0
- graphcore/auth/authn/README.md +178 -0
- graphcore/auth/authn/__init__.py +3 -0
- graphcore/auth/authn/authenticator.py +120 -0
- graphcore/auth/authn/onboarding.py +105 -0
- graphcore/auth/authn/principals.py +20 -0
- graphcore/auth/authn/resource_metadata.py +43 -0
- graphcore/auth/authn/service_accounts.py +96 -0
- graphcore/auth/authn/testing.py +96 -0
- graphcore/auth/authn/tests/__init__.py +0 -0
- graphcore/auth/authn/tests/test_authenticator.py +145 -0
- graphcore/auth/authn/tests/test_onboarding.py +145 -0
- graphcore/auth/authn/tests/test_service_accounts.py +180 -0
- graphcore/auth/authn/users.py +59 -0
- graphcore/auth/authz/__init__.py +0 -0
- graphcore/auth/authz/access_port.py +120 -0
- graphcore/auth/authz/adapter/__init__.py +0 -0
- graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
- graphcore/auth/authz/adapter/tests/__init__.py +0 -0
- graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
- graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
- graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
- graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
- graphcore/auth/authz/defaults.py +26 -0
- graphcore/auth/authz/kernel_policy.py +191 -0
- graphcore/auth/authz/kernel_writes.py +31 -0
- graphcore/auth/authz/lookups.py +25 -0
- graphcore/auth/authz/policy.py +403 -0
- graphcore/auth/authz/tests/__init__.py +0 -0
- graphcore/auth/authz/tests/test_can_contain.py +150 -0
- graphcore/auth/authz/tests/test_contained_by.py +167 -0
- graphcore/auth/authz/tests/test_creation.py +391 -0
- graphcore/auth/authz/tests/test_delete_permission.py +82 -0
- graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
- graphcore/auth/authz/tests/test_integration.py +637 -0
- graphcore/auth/authz/tests/test_invites.py +184 -0
- graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
- graphcore/auth/authz/tests/test_lockout.py +132 -0
- graphcore/auth/authz/tests/test_policy.py +329 -0
- graphcore/auth/authz/tests/test_primitives.py +73 -0
- graphcore/auth/authz/tests/test_principal_creation.py +62 -0
- graphcore/bootstrap/__init__.py +0 -0
- graphcore/bootstrap/deployment.py +67 -0
- graphcore/bootstrap/signals.py +16 -0
- graphcore/bootstrap/tests/__init__.py +0 -0
- graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
- graphcore/broadcast/__init__.py +4 -0
- graphcore/broadcast/broadcaster.py +201 -0
- graphcore/broadcast/channels.py +56 -0
- graphcore/broadcast/tests/__init__.py +0 -0
- graphcore/broadcast/tests/test_broadcaster.py +444 -0
- graphcore/celery.py +14 -0
- graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
- graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
- graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
- graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
- graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
- graphcore/docs/RUNTIME.md +90 -0
- graphcore/docs/SCHEDULING_TDD.md +244 -0
- graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
- graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
- graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
- graphcore/docs/__init__.py +0 -0
- graphcore/docs/doc_topics.py +97 -0
- graphcore/docs/docs_discovery.py +64 -0
- graphcore/docs/public_api.py +56 -0
- graphcore/domain/__init__.py +0 -0
- graphcore/domain/entity/Entity.py +204 -0
- graphcore/domain/entity/__init__.py +0 -0
- graphcore/domain/entity/deployment/Deployment.py +25 -0
- graphcore/domain/entity/deployment/__init__.py +0 -0
- graphcore/domain/entity/grant/Grant.py +31 -0
- graphcore/domain/entity/grant/__init__.py +0 -0
- graphcore/domain/entity/group/Group.py +48 -0
- graphcore/domain/entity/group/README.md +88 -0
- graphcore/domain/entity/group/__init__.py +0 -0
- graphcore/domain/entity/invite/Invite.py +31 -0
- graphcore/domain/entity/invite/__init__.py +0 -0
- graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
- graphcore/domain/entity/request_template/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/__init__.py +0 -0
- graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
- graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
- graphcore/domain/entity/service_account/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
- graphcore/domain/entity/strategy_request/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
- graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
- graphcore/domain/entity/tests/__init__.py +0 -0
- graphcore/domain/entity/tests/test_entity.py +227 -0
- graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
- graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
- graphcore/domain/entity/user/User.py +39 -0
- graphcore/domain/entity/user/__init__.py +0 -0
- graphcore/domain/entity/user/tests/__init__.py +0 -0
- graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
- graphcore/domain/entity/view/View.py +37 -0
- graphcore/domain/entity/view/__init__.py +0 -0
- graphcore/domain/entity/view/position.py +78 -0
- graphcore/domain/entity/view/tests/__init__.py +0 -0
- graphcore/domain/entity/view/tests/test_position.py +71 -0
- graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
- graphcore/domain/strategy/BaseStrategy.py +759 -0
- graphcore/domain/strategy/DeploymentStrategies.py +55 -0
- graphcore/domain/strategy/GrantStrategies.py +189 -0
- graphcore/domain/strategy/GroupStrategies.py +193 -0
- graphcore/domain/strategy/InviteStrategies.py +84 -0
- graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
- graphcore/domain/strategy/ViewStrategies.py +219 -0
- graphcore/domain/strategy/__init__.py +0 -0
- graphcore/domain/strategy/runner.py +84 -0
- graphcore/domain/strategy/session.py +56 -0
- graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
- graphcore/domain/strategy/tests/__init__.py +0 -0
- graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
- graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
- graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
- graphcore/domain/strategy/tests/test_runner.py +220 -0
- graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
- graphcore/domain/strategy/tests/test_utils.py +95 -0
- graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
- graphcore/errors.py +145 -0
- graphcore/execution/README.md +97 -0
- graphcore/execution/StrategyExecutorService.py +333 -0
- graphcore/execution/__init__.py +0 -0
- graphcore/execution/dispatcher.py +19 -0
- graphcore/execution/environments/__init__.py +0 -0
- graphcore/execution/environments/celery.py +59 -0
- graphcore/execution/environments/in_process.py +55 -0
- graphcore/execution/local_session.py +117 -0
- graphcore/execution/redis_run_events.py +74 -0
- graphcore/execution/requests.py +22 -0
- graphcore/execution/run_events.py +85 -0
- graphcore/execution/strategy_context.py +54 -0
- graphcore/execution/tasks.py +34 -0
- graphcore/execution/tests/__init__.py +5 -0
- graphcore/execution/tests/contract.py +171 -0
- graphcore/execution/tests/support.py +310 -0
- graphcore/execution/tests/test_dispatchers.py +76 -0
- graphcore/execution/tests/test_executor.py +368 -0
- graphcore/execution/tests/test_local_session.py +95 -0
- graphcore/execution/tests/test_reconcile_runs.py +134 -0
- graphcore/execution/tests/test_run_events.py +106 -0
- graphcore/execution/tests/test_strategy_context.py +62 -0
- graphcore/gateway/__init__.py +1 -0
- graphcore/gateway/remote.py +35 -0
- graphcore/gateway/tests/__init__.py +0 -0
- graphcore/gateway/tests/test_remote.py +30 -0
- graphcore/graph/EntityService.py +710 -0
- graphcore/graph/__init__.py +0 -0
- graphcore/graph/entity_cache.py +152 -0
- graphcore/graph/tests/__init__.py +4 -0
- graphcore/graph/tests/test_EntityService.py +908 -0
- graphcore/graph/tests/test_EntityService_list.py +170 -0
- graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
- graphcore/graph/tests/test_EntityService_referrers.py +236 -0
- graphcore/graph/tests/test_EntityService_routing.py +119 -0
- graphcore/graph/tests/test_dependent_on.py +141 -0
- graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
- graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
- graphcore/graph/tests/test_entity_cache.py +159 -0
- graphcore/graph/tests/test_null_entity_cache.py +12 -0
- graphcore/management/__init__.py +0 -0
- graphcore/management/commands/__init__.py +0 -0
- graphcore/management/commands/dev_reset.py +18 -0
- graphcore/management/commands/graphcore_createadmin.py +65 -0
- graphcore/management/commands/graphcore_policy.py +59 -0
- graphcore/management/commands/graphcore_status.py +98 -0
- graphcore/management/tests/__init__.py +0 -0
- graphcore/management/tests/test_createadmin.py +78 -0
- graphcore/management/tests/test_policy_command.py +46 -0
- graphcore/management/tests/test_status_command.py +85 -0
- graphcore/migrations/0001_initial.py +186 -0
- graphcore/migrations/0002_invite.py +26 -0
- graphcore/migrations/__init__.py +0 -0
- graphcore/models.py +11 -0
- graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
- graphcore/persistence/__init__.py +6 -0
- graphcore/persistence/django/__init__.py +0 -0
- graphcore/persistence/django/backends.py +43 -0
- graphcore/persistence/django/bindings.py +28 -0
- graphcore/persistence/django/cache.py +38 -0
- graphcore/persistence/django/compiler.py +214 -0
- graphcore/persistence/django/identity.py +18 -0
- graphcore/persistence/django/models.py +252 -0
- graphcore/persistence/django/repository.py +525 -0
- graphcore/persistence/django/tests/__init__.py +0 -0
- graphcore/persistence/django/tests/test_backends.py +68 -0
- graphcore/persistence/django/tests/test_compiler.py +269 -0
- graphcore/persistence/django/tests/test_repository.py +472 -0
- graphcore/persistence/django/tests/test_shared_column.py +120 -0
- graphcore/persistence/django/tests/test_threads.py +50 -0
- graphcore/persistence/django/tests/test_update_shape.py +175 -0
- graphcore/persistence/django/threads.py +38 -0
- graphcore/persistence/repository.py +172 -0
- graphcore/persistence/tests/__init__.py +0 -0
- graphcore/persistence/tests/contract.py +688 -0
- graphcore/persistence/tests/evaluate.py +51 -0
- graphcore/persistence/tests/fixtures.py +32 -0
- graphcore/persistence/tests/memory.py +263 -0
- graphcore/persistence/tests/test_memory_repository.py +10 -0
- graphcore/persistence/tests/test_query_types.py +127 -0
- graphcore/public/__init__.py +9 -0
- graphcore/public/api.py +9 -0
- graphcore/public/apps.py +10 -0
- graphcore/public/auth/__init__.py +1 -0
- graphcore/public/auth/grants.py +7 -0
- graphcore/public/auth/onboarding.py +8 -0
- graphcore/public/auth/perms.py +7 -0
- graphcore/public/auth/policy.py +10 -0
- graphcore/public/auth/roles.py +8 -0
- graphcore/public/auth/subjects.py +7 -0
- graphcore/public/entities/__init__.py +32 -0
- graphcore/public/errors.py +19 -0
- graphcore/public/persistence/__init__.py +44 -0
- graphcore/public/persistence/django.py +24 -0
- graphcore/public/scheduling.py +23 -0
- graphcore/public/strategies/__init__.py +85 -0
- graphcore/public/test_settings.py +16 -0
- graphcore/public/testing.py +47 -0
- graphcore/registry/EntityDirectory.py +246 -0
- graphcore/registry/README.md +147 -0
- graphcore/registry/StrategyDirectory.py +308 -0
- graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
- graphcore/registry/__init__.py +0 -0
- graphcore/registry/app_discovery.py +108 -0
- graphcore/registry/decorators.py +77 -0
- graphcore/registry/discovery.py +111 -0
- graphcore/registry/registry.py +79 -0
- graphcore/registry/tests/__init__.py +0 -0
- graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
- graphcore/registry/tests/test_app_config.py +36 -0
- graphcore/registry/tests/test_discovery.py +147 -0
- graphcore/registry/tests/test_entity_directory_storage.py +73 -0
- graphcore/registry/tests/test_import_package.py +87 -0
- graphcore/registry/tests/test_principal_flag.py +67 -0
- graphcore/registry/tests/test_strategy_directory.py +29 -0
- graphcore/routes/__init__.py +116 -0
- graphcore/routes/tests/__init__.py +0 -0
- graphcore/routes/tests/test_routes.py +90 -0
- graphcore/runtime.py +243 -0
- graphcore/scheduling/__init__.py +0 -0
- graphcore/scheduling/beat_scheduler.py +164 -0
- graphcore/scheduling/beat_tasks.py +63 -0
- graphcore/scheduling/scheduler.py +37 -0
- graphcore/scheduling/tests/__init__.py +0 -0
- graphcore/scheduling/tests/contract.py +136 -0
- graphcore/scheduling/tests/memory.py +42 -0
- graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
- graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
- graphcore/scheduling/tests/test_ticks.py +143 -0
- graphcore/tasks.py +9 -0
- graphcore/test_settings.py +78 -0
- graphcore/testing/__init__.py +0 -0
- graphcore/testing/case.py +112 -0
- graphcore/testing/runner.py +32 -0
- graphcore/testing/settings.py +26 -0
- graphcore/testing/tests/__init__.py +0 -0
- graphcore/testing/tests/agent_view_fixture.py +19 -0
- graphcore/testing/tests/test_case_and_runner.py +219 -0
- graphcore/testing/tests/test_settings_for_apps.py +50 -0
- graphcore/tests/__init__.py +0 -0
- graphcore/tests/ids.py +14 -0
- graphcore/tests/public_api_manifest.py +102 -0
- graphcore/tests/runs.py +7 -0
- graphcore/tests/test_app_discovery.py +90 -0
- graphcore/tests/test_composition_boundaries.py +231 -0
- graphcore/tests/test_docs_discovery.py +108 -0
- graphcore/tests/test_no_print.py +70 -0
- graphcore/tests/test_packaging.py +64 -0
- graphcore/tests/test_public_api_boundaries.py +229 -0
- graphcore/tests/test_public_api_contract.py +62 -0
- graphcore/tests/test_public_api_docs.py +28 -0
- graphcore/tests/test_runtime.py +42 -0
- graphcore/tests/test_shared_type_boundaries.py +128 -0
- graphcore/tests/test_shared_types.py +144 -0
- graphcore/tests/test_test_settings.py +45 -0
- graphcore/transport/__init__.py +0 -0
- graphcore/transport/agent_asgi.py +68 -0
- graphcore/transport/agent_client.py +85 -0
- graphcore/transport/channel_layer.py +68 -0
- graphcore/transport/consumers.py +507 -0
- graphcore/transport/routing.py +6 -0
- graphcore/transport/tests/__init__.py +0 -0
- graphcore/transport/tests/test_agent_client.py +31 -0
- graphcore/transport/tests/test_api_views.py +733 -0
- graphcore/transport/tests/test_channel_layer.py +96 -0
- graphcore/transport/tests/test_consumers.py +963 -0
- graphcore/transport/tests/test_resource_metadata.py +67 -0
- graphcore/transport/urls.py +29 -0
- graphcore/transport/views.py +358 -0
- graphcore/types/__init__.py +4 -0
- graphcore/types/access.py +114 -0
- graphcore/types/api.py +76 -0
- graphcore/types/entities.py +100 -0
- graphcore/types/entity_id.py +85 -0
- graphcore/types/execution.py +41 -0
- graphcore/types/identity.py +20 -0
- graphcore/types/onboarding.py +20 -0
- graphcore/types/query.py +116 -0
- graphcore/types/schedules.py +91 -0
- graphcore/types/strategy.py +73 -0
- graphcore/types/tests/__init__.py +0 -0
- graphcore/types/tests/test_entity_id.py +50 -0
- graphcore/urls.py +5 -0
- graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
- graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
- graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
- graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
- graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
- graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
- graphcore_kernel-0.1.0.dist-info/top_level.txt +1 -0
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
# GraphAPI: the mutation front door
|
|
2
|
+
|
|
3
|
+
## The idea
|
|
4
|
+
|
|
5
|
+
Every mutation in the system — entity saves, deletes, grants, revokes —
|
|
6
|
+
enters through `GraphAPI`. Nothing calls `EntityService` directly to write.
|
|
7
|
+
|
|
8
|
+
This is not a routing formality. `graphcore/runtime.py` is the composition
|
|
9
|
+
root; `GraphAPI` is the facade it hands requests to, and the facade
|
|
10
|
+
sequences the cross-cutting concerns a mutation triggers — enforcement,
|
|
11
|
+
persistence, cache invalidation, live-update broadcast — without any
|
|
12
|
+
component knowing about the others. Today that concern is broadcasting; the
|
|
13
|
+
same seam absorbs whatever comes next (audit, webhooks) without touching
|
|
14
|
+
the writer.
|
|
15
|
+
|
|
16
|
+
## The pieces
|
|
17
|
+
|
|
18
|
+
| Component | Owns | Asks the `AccessPort` |
|
|
19
|
+
|---|---|---|
|
|
20
|
+
| `GraphAPI` | Sequencing: mutation → signal → delivery | `available_roles` / `list_grants` (share-surface reads, for managers only; grant *mutation* dispatches kernel strategies) |
|
|
21
|
+
| `EntityService` | Persistence + enforcement | `allows` / `read_filters`, asked for the perms the type policy names; `check_save` / `check_delete` (the lockout rule); `entity_saved` / `prepare_delete` / `entities_deleted` lifecycle hooks |
|
|
22
|
+
| `Broadcaster` | All delivery mechanics: channel layer, channel naming, subscriptions | `scopes` / `owner_principals` / `holders` / `granted_resources` / `covers` (propagation) |
|
|
23
|
+
|
|
24
|
+
All three share the one `AccessPort` instance, each using a disjoint slice
|
|
25
|
+
of it. That is deliberate dependency injection, not leakage: one source of
|
|
26
|
+
truth for access facts, one shared cache underneath, and the only component
|
|
27
|
+
that knows what grants, groups, or containment *mean* is the adapter. The
|
|
28
|
+
port's contract lives in [AUTHORIZATION_TECHNICAL_TDD.md](AUTHORIZATION_TECHNICAL_TDD.md).
|
|
29
|
+
|
|
30
|
+
`EntityService` publishes through the `Broadcaster` it was constructed with
|
|
31
|
+
but never touches the channel layer directly — that is the broadcaster's
|
|
32
|
+
own concern. The broadcaster never makes an authorization decision.
|
|
33
|
+
|
|
34
|
+
Shared identity and entity read types live in `graphcore.types.identity` and
|
|
35
|
+
`graphcore.types.entities`. Facade payloads live in `graphcore.types.api`;
|
|
36
|
+
conversion to strategy entities belongs to the API boundary. Services do
|
|
37
|
+
not depend on facade payloads.
|
|
38
|
+
|
|
39
|
+
## The flows
|
|
40
|
+
|
|
41
|
+
Entity write — the saved entity is itself the signal. The adapter's
|
|
42
|
+
lifecycle hook returns an `AccessChange` when the written entity was a
|
|
43
|
+
`Grant` (grants are entities; see the authz TDD's Grant storage), so
|
|
44
|
+
one flow carries both content and access changes:
|
|
45
|
+
|
|
46
|
+
```python
|
|
47
|
+
async def save(self, principal, entity):
|
|
48
|
+
change = await self.entity_service.save_entity(entity, principal)
|
|
49
|
+
# ^ enforce + commit + adapter hooks; hooks return AccessChange | None
|
|
50
|
+
await self.broadcaster.entity_saved(entity) # scopes() → publish per scope channel
|
|
51
|
+
if change:
|
|
52
|
+
await self.broadcaster.access_changed(change) # subscription joins/leaves + notification
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Grant mutation is not a separate pipeline: `GraphAPI.grant`/`revoke` are
|
|
56
|
+
sugar that dispatch the kernel grant strategies, whose saves flow through
|
|
57
|
+
`save` above like any other write. A scope channel carries what its
|
|
58
|
+
subscribers may `Read`, so a type read with another permission is routed
|
|
59
|
+
differently: a grant is read with `ManageAccess`, so its save goes to the
|
|
60
|
+
`owner_` channel of each principal `holders(ManageAccess, scopes)` returns,
|
|
61
|
+
never to the resource's scope channel. Its tombstone goes to both routes,
|
|
62
|
+
so a subject whose last managing grant was the deleted one still hears of
|
|
63
|
+
it.
|
|
64
|
+
|
|
65
|
+
Broadcaster consumption:
|
|
66
|
+
|
|
67
|
+
```python
|
|
68
|
+
async def entity_saved(self, entity):
|
|
69
|
+
for scope_id in await self.access.scopes(entity.entity_id, entity.parent_ids):
|
|
70
|
+
await self.channel_layer.group_send(f"scope_{scope_id}", update(entity))
|
|
71
|
+
|
|
72
|
+
async def access_changed(self, change: AccessChange):
|
|
73
|
+
# cheap direction: check connected principals, never expand a roster
|
|
74
|
+
for principal in await self.access.covers(change.subject_id, self.connected_principals()):
|
|
75
|
+
conn = self.connections[principal]
|
|
76
|
+
if change.new_role is None: # revoke
|
|
77
|
+
await conn.group_discard(f"scope_{change.resource_id}")
|
|
78
|
+
await conn.send(access_revoked(change.resource_id))
|
|
79
|
+
elif change.old_role is None: # fresh grant
|
|
80
|
+
await conn.group_add(f"scope_{change.resource_id}") # join BEFORE notify,
|
|
81
|
+
await conn.send(access_granted(change.resource_id)) # so no save lands in the gap
|
|
82
|
+
else: # role change, same read reach
|
|
83
|
+
await conn.send(access_changed_msg(change.resource_id, change.new_role))
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
On a fresh grant the client gets a channel join plus a lightweight
|
|
87
|
+
notification — never a data backfill. Subscribing to the scope's channel is
|
|
88
|
+
what covers the entire subtree, including entities created later; the
|
|
89
|
+
broadcaster never enumerates descendants.
|
|
90
|
+
|
|
91
|
+
Reads are unaffected: `get_entity` / `get_entities` stay on `EntityService`
|
|
92
|
+
(reads don't broadcast).
|
|
93
|
+
|
|
94
|
+
## Delivery and resync
|
|
95
|
+
|
|
96
|
+
The channel layer is Redis pub/sub: each update is delivered at most once,
|
|
97
|
+
and nothing records what a connection missed. Every update carries the whole
|
|
98
|
+
entity, so a later update repairs an earlier lost one; what needs repair is
|
|
99
|
+
a loss with nothing after it. The client closes that gap by resyncing
|
|
100
|
+
rather than the server by replaying:
|
|
101
|
+
|
|
102
|
+
- **`connected`** is sent after the socket has joined its channels, and
|
|
103
|
+
carries `max_batch_size`. The client resyncs on it, so nothing published
|
|
104
|
+
during the resync is missed.
|
|
105
|
+
- **`etag`**: every entity and tombstone a transport sends carries one
|
|
106
|
+
(`client_view`), an opaque hash of its whole client view. It changes with
|
|
107
|
+
the projections too (`children_ids`, `ancestor_ids`), which change
|
|
108
|
+
without a version bump. It is computed over the finished `to_client()`
|
|
109
|
+
output rather than inside it, because types override `to_client()` to
|
|
110
|
+
trim or add fields. So transports and the broadcaster send `client_view(x)`,
|
|
111
|
+
never `x.to_client()`; an entity sent without an etag comes back on every
|
|
112
|
+
resync.
|
|
113
|
+
- **`resync`** (client → server) sends `{entity_id: etag}` for what the
|
|
114
|
+
client holds, a batch at a time with a `resync_id`.
|
|
115
|
+
`GraphAPI.changed_entities` answers with one `get_entities` read: entities
|
|
116
|
+
whose etag differs, `deleted` tombstones for missing ids, and `forbidden`
|
|
117
|
+
stubs for unreadable ones. `resync_done` ends each batch, even on
|
|
118
|
+
failure.
|
|
119
|
+
- **`resync`** (server → client) asks for a resync. `PubSubChannelLayer`
|
|
120
|
+
(`transport/channel_layer.py`) queues `resync.requested` to every consumer
|
|
121
|
+
on its process when a Redis subscription reconnects, since everything
|
|
122
|
+
published while it was down is gone.
|
|
123
|
+
|
|
124
|
+
The client also treats a missed pong as a dead socket, checks the socket when
|
|
125
|
+
the page resumes, settles awaited runs from their saved `StrategyRequest`
|
|
126
|
+
after a reconnect, and ignores an entity older than the one it holds.
|
|
127
|
+
|
|
128
|
+
## Migration
|
|
129
|
+
|
|
130
|
+
Writers that bypass `GraphAPI` today, in full:
|
|
131
|
+
|
|
132
|
+
1. `BaseStrategy.save_entity` — the wrapper every strategy save routes
|
|
133
|
+
through; delegates to `graph_api.save(...)` instead. One line; strategy
|
|
134
|
+
subclasses unchanged.
|
|
135
|
+
2. `BaseStrategy`'s recursive delete — the one direct
|
|
136
|
+
`entity_service.delete_entities` call; same treatment.
|
|
137
|
+
3. `StrategyExecutorService`'s auto-persist of the target entity and
|
|
138
|
+
strategy-request bookkeeping after `apply()`.
|
|
139
|
+
4. `auth/` user-entity creation at first sign-in — either routed through `GraphAPI`
|
|
140
|
+
or explicitly carved out as pre-authz bootstrap.
|
|
141
|
+
|
|
142
|
+
Wiring is the real work, not call sites: `BaseStrategy.__init__` constructs
|
|
143
|
+
`EntityService()` itself today and needs `GraphAPI` handed to it instead.
|
|
144
|
+
Celery is not a blocker — the channel layer is Redis-backed, so broadcasts
|
|
145
|
+
from worker processes reach consumers the same way existing strategy
|
|
146
|
+
callbacks already do.
|
|
147
|
+
|
|
148
|
+
## Reverse-ref lookup: `get_referencing`
|
|
149
|
+
|
|
150
|
+
The query behind "what renders entity X" (view resolution, audit): enumerate
|
|
151
|
+
from the ref index, filter by ids, hydrate only what survives.
|
|
152
|
+
|
|
153
|
+
```python
|
|
154
|
+
async def get_referencing(self, principal, target_id, key=None):
|
|
155
|
+
source_ids = await self.ref_index.sources(target_id, key) # ids only
|
|
156
|
+
readable = await self.repository.list_ids(AllOf(( # ids in, ids out
|
|
157
|
+
InValues('entity_id', source_ids), await self._read_predicate(principal),
|
|
158
|
+
)))
|
|
159
|
+
return await self.entity_service.load_entities(readable) # hydrate survivors
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
The check runs after enumeration (the ref index is principal-free) but
|
|
163
|
+
before hydration — the read predicate is conjoined with the candidate ids
|
|
164
|
+
in storage, so unreadable sources are never loaded. Denied sources are
|
|
165
|
+
silently omitted, not tombstoned: in the reverse direction a tombstone would
|
|
166
|
+
itself leak that a hidden referencing entity exists. (Forward refs the
|
|
167
|
+
caller holds are the opposite: they tombstone on denial.)
|
|
168
|
+
|
|
169
|
+
No separate ref-change broadcast machinery is needed: creating an entity
|
|
170
|
+
that references X is a save of that entity, which already fans out through
|
|
171
|
+
its own `scopes()` channels — reaching exactly the watchers who may read it,
|
|
172
|
+
by construction. Clients maintain their own target→sources map from updates
|
|
173
|
+
they already receive.
|
|
@@ -0,0 +1,90 @@
|
|
|
1
|
+
# The runtime: one composition root
|
|
2
|
+
|
|
3
|
+
`graphcore/runtime.py` builds the kernel's live service graph once per
|
|
4
|
+
process and hands the same instances to every entrypoint. It is the only
|
|
5
|
+
place concrete infrastructure (a Django repository, a Redis-backed cache, a
|
|
6
|
+
Channels broadcaster) is named and wired together.
|
|
7
|
+
|
|
8
|
+
## The pieces
|
|
9
|
+
|
|
10
|
+
| Name | What it is |
|
|
11
|
+
|---|---|
|
|
12
|
+
| `Runtime` | Frozen dataclass holding one process's live graph: `registry`, `repository`, `cache`, `access`, `broadcaster`, `entity_service`, `executor`, `graph_api`, `gateway`, `backend_id`, `handle`. |
|
|
13
|
+
| `build_runtime(registry, repository, cache, access, broadcaster, gateway, max_batch_size, handle=None)` | Wires already-constructed components into a `Runtime`. No Django dependency — the extension point for any deployment. |
|
|
14
|
+
| `django_runtime(registry)` | The shipped default factory: constructs `DjangoEntityRepository`, `DjangoCache`, `DefaultAccessAdapter`, `ChannelsBroadcaster`, `NoRemoteGateway`, reads `GRAPHCORE_ENTITY_CACHE_TTL` / `GRAPHCORE_MAX_BATCH_SIZE` / `GRAPHCORE_HANDLE` / `GRAPHCORE_DB_THREADS`, then calls `build_runtime`. |
|
|
15
|
+
| `get_runtime()` | Lazy, process-wide accessor. Builds the `Runtime` on first call via `GRAPHCORE_RUNTIME_FACTORY` (default `django_runtime`) and caches it for the life of the process. |
|
|
16
|
+
|
|
17
|
+
## Store identity
|
|
18
|
+
|
|
19
|
+
`build_runtime` reads `repository.backend_id()` — the immutable identity
|
|
20
|
+
minted into the store when it was initialised — and puts it on
|
|
21
|
+
`Runtime.backend_id` and on the `EntityService` it constructs.
|
|
22
|
+
`EntityService.create(entity_cls, **kwargs)` is what mints
|
|
23
|
+
`gc://<backend_id>/<local_id>`, and the only thing that does: an entity is
|
|
24
|
+
constructed with its identifier, never without one. The identity is data,
|
|
25
|
+
never configuration: no setting, env var, or argument supplies it.
|
|
26
|
+
`Runtime.handle` is the
|
|
27
|
+
deployment's mutable human-readable name (`GRAPHCORE_HANDLE`), published in
|
|
28
|
+
the identity document at `/graphcore/.well-known/graphcore/` and nowhere
|
|
29
|
+
else. See `docs/ENTITY_REFERENCE_TDD.md`.
|
|
30
|
+
|
|
31
|
+
`Runtime.gateway` is the `RemoteGateway` port `EntityService` routes
|
|
32
|
+
identifiers minted by another deployment to. The shipped `NoRemoteGateway`
|
|
33
|
+
returns a `Tombstone` for every one of them.
|
|
34
|
+
|
|
35
|
+
`get_runtime()` is called only from process entrypoints — HTTP views, the
|
|
36
|
+
WebSocket consumer, Celery tasks, authn, `dev_reset` — never at import time
|
|
37
|
+
and never from `graph/`, `execution/` (besides `tasks.py`), `auth/authz/`,
|
|
38
|
+
`broadcast/`, `persistence/`, or `domain/`. It stays lazy on purpose: Celery
|
|
39
|
+
forks worker processes from a parent that has already run `ready()`, so
|
|
40
|
+
building the `Runtime` eagerly there would share one set of DB/Redis/channel
|
|
41
|
+
connections across every forked worker. Building it lazily inside each
|
|
42
|
+
entrypoint call means each process gets its own.
|
|
43
|
+
|
|
44
|
+
## Overriding it
|
|
45
|
+
|
|
46
|
+
Point `GRAPHCORE_RUNTIME_FACTORY` at your own
|
|
47
|
+
`(registry, *, worker) -> Runtime` function instead of patching the kernel.
|
|
48
|
+
`worker` is true in a Celery worker, which is the CPU environment: bind
|
|
49
|
+
`worker_dispatchers` there so CPU runs on the worker's own loop, and
|
|
50
|
+
`default_dispatchers` everywhere else:
|
|
51
|
+
|
|
52
|
+
```python
|
|
53
|
+
# myapp/runtime.py
|
|
54
|
+
from graphcore.runtime import build_runtime, default_dispatchers, worker_dispatchers
|
|
55
|
+
from graphcore.persistence.django.repository import DjangoEntityRepository
|
|
56
|
+
from graphcore.persistence.django.cache import DjangoCache
|
|
57
|
+
from graphcore.gateway.remote import NoRemoteGateway
|
|
58
|
+
from myapp.auth import MyAccessAdapter
|
|
59
|
+
from myapp.broadcast import MyBroadcaster
|
|
60
|
+
|
|
61
|
+
def build_my_runtime(registry, *, worker):
|
|
62
|
+
repository = DjangoEntityRepository(registry.entities)
|
|
63
|
+
cache = DjangoCache(entity_ttl=900)
|
|
64
|
+
access = MyAccessAdapter(registry, repository, cache)
|
|
65
|
+
broadcaster = MyBroadcaster(access, registry)
|
|
66
|
+
gateway = NoRemoteGateway()
|
|
67
|
+
return build_runtime(
|
|
68
|
+
registry, repository, cache, access, broadcaster, gateway, max_batch_size=100,
|
|
69
|
+
dispatchers=worker_dispatchers if worker else default_dispatchers,
|
|
70
|
+
)
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
```python
|
|
74
|
+
# settings.py
|
|
75
|
+
GRAPHCORE_RUNTIME_FACTORY = "myapp.runtime.build_my_runtime"
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`get_runtime()` resolves and calls this in place of `django_runtime` the
|
|
79
|
+
first time it's needed in each process — same laziness, same caching,
|
|
80
|
+
different components. Reuse whatever kernel pieces you still want
|
|
81
|
+
(`DjangoEntityRepository`, `DjangoCache`, ...) and swap only the ones you
|
|
82
|
+
don't.
|
|
83
|
+
|
|
84
|
+
There is no `set_runtime()`. A settable global invites the same
|
|
85
|
+
prefork bug the laziness above avoids — call it from the wrong place (an
|
|
86
|
+
`AppConfig.ready()`, a module top level) and it re-shares connections across
|
|
87
|
+
forked workers. A factory resolved lazily inside `get_runtime()` can't be
|
|
88
|
+
called too early by accident. `serve_as_worker()`, which the kernel's
|
|
89
|
+
Celery integration calls from `worker_init`, records only what kind of
|
|
90
|
+
process this is, never a runtime, and raises once the runtime is built.
|
|
@@ -0,0 +1,244 @@
|
|
|
1
|
+
# Scheduling Technical Design
|
|
2
|
+
|
|
3
|
+
## Introduction
|
|
4
|
+
|
|
5
|
+
A request template with a schedule produces a strategy request on every
|
|
6
|
+
tick of its cron expression. The `Scheduler` port separates the kernel from
|
|
7
|
+
the infrastructure that keeps time and fires ticks. A schedule is state on a
|
|
8
|
+
`RequestTemplate`, an ordinary entity; a scheduler keeps its infrastructure
|
|
9
|
+
in step with that state and, on each tick, submits a new request made from
|
|
10
|
+
the template to the executor's front door, exactly as any other caller
|
|
11
|
+
submits a request.
|
|
12
|
+
|
|
13
|
+
The template is the single source of truth for its schedule, following
|
|
14
|
+
`kernel/backend/graphcore/docs/ARCHITECTURE_PRINCIPLES.md` (rule 8). How a
|
|
15
|
+
submitted request runs is specified in `docs/STRATEGY_EXECUTION_TDD.md`.
|
|
16
|
+
|
|
17
|
+
## Definitions
|
|
18
|
+
|
|
19
|
+
- **Scheduled template**: a `RequestTemplate`
|
|
20
|
+
(`docs/STRATEGY_EXECUTION_TDD.md`, Strategy requests and request
|
|
21
|
+
templates) with a non-null `cron`.
|
|
22
|
+
- **Desired schedule**: the `ScheduleSpec` a scheduled template declares,
|
|
23
|
+
returned by `RequestTemplate.schedule_spec()`.
|
|
24
|
+
- **Scheduler**: an implementation of the `Scheduler` port.
|
|
25
|
+
- **Held schedule**: a schedule the scheduler's infrastructure holds, keyed
|
|
26
|
+
by the template's id.
|
|
27
|
+
- **Tick**: one firing of a held schedule.
|
|
28
|
+
|
|
29
|
+
## Requirements
|
|
30
|
+
|
|
31
|
+
1. A template's persisted state is the single source of truth for its
|
|
32
|
+
schedule.
|
|
33
|
+
2. Creating, changing, or cancelling a schedule is exactly one write, made
|
|
34
|
+
by a strategy and authorized at the persistence chokepoint like any
|
|
35
|
+
other.
|
|
36
|
+
3. A scheduler never writes entities, and no entity field records scheduler
|
|
37
|
+
status.
|
|
38
|
+
4. A scheduler failure never fails the write that caused it, and is
|
|
39
|
+
repaired without user action.
|
|
40
|
+
5. A tick never creates a request from a template that is deleted,
|
|
41
|
+
disabled, or unscheduled, however far the scheduler lags.
|
|
42
|
+
6. A tick's request runs as the template's `owner`. Templates are readable
|
|
43
|
+
and manageable by their owner only.
|
|
44
|
+
7. A tick's request is executed exactly like any other: it enters through
|
|
45
|
+
the front door and is routed by the strategy's workload.
|
|
46
|
+
8. A scheduler is swappable without changing `EntityService`, the executor,
|
|
47
|
+
or any strategy. Nothing scheduler-specific (row ids, task names, encoded
|
|
48
|
+
arguments) crosses the port.
|
|
49
|
+
|
|
50
|
+
## Architecture
|
|
51
|
+
|
|
52
|
+
Paths are relative to `kernel/backend/graphcore`:
|
|
53
|
+
|
|
54
|
+
```text
|
|
55
|
+
types/schedules.py # ScheduleSpec, ScheduleInfo
|
|
56
|
+
domain/entity/request_template/ # RequestTemplate.schedule_spec(), to_payload()
|
|
57
|
+
domain/strategy/RequestTemplateStrategies.py # CreateRequestTemplate, ManageRequestTemplate
|
|
58
|
+
scheduling/
|
|
59
|
+
scheduler.py # the Scheduler port
|
|
60
|
+
beat_scheduler.py # BeatScheduler, the default adapter
|
|
61
|
+
beat_tasks.py # BeatScheduler's tick and reconcile tasks
|
|
62
|
+
tests/contract.py # SchedulerContract
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### Desired state
|
|
66
|
+
|
|
67
|
+
A template declares its schedule:
|
|
68
|
+
|
|
69
|
+
| Field | Meaning |
|
|
70
|
+
|---|---|
|
|
71
|
+
| `cron` | Five-field cron expression; null for an unscheduled template |
|
|
72
|
+
| `enabled` | Whether ticks create requests |
|
|
73
|
+
| `owner` | The principal every tick's request runs as; set by the persistence chokepoint and immutable |
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
class RequestTemplate(Entity):
|
|
77
|
+
def schedule_spec(self) -> ScheduleSpec | None:
|
|
78
|
+
"""The desired schedule, or None when cron is null."""
|
|
79
|
+
def to_payload(self) -> StrategyRequestPayload:
|
|
80
|
+
"""The payload of a request made from this template."""
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
`ScheduleSpec(target_id, principal_id, cron, enabled)` carries the
|
|
84
|
+
template's id, `owner`, `cron`, and `enabled`. `schedule_spec()` is the only
|
|
85
|
+
mapping from entity to schedule.
|
|
86
|
+
|
|
87
|
+
Invariants:
|
|
88
|
+
|
|
89
|
+
- `cron` is validated as a five-field cron expression, each value within its
|
|
90
|
+
field's range (minute 0-59, hour 0-23, day 1-31, month 1-12 or `jan`-`dec`,
|
|
91
|
+
weekday 0-6 or `sun`-`sat`; `*`, ranges, non-zero steps, and lists), by
|
|
92
|
+
`CreateRequestTemplate` and `ManageRequestTemplate`, before
|
|
93
|
+
any write. A scheduler failure is never a validation failure.
|
|
94
|
+
- A `StrategyRequest` has no schedule fields. Only templates are scheduled.
|
|
95
|
+
|
|
96
|
+
### Creating and changing a schedule
|
|
97
|
+
|
|
98
|
+
`CreateRequestTemplate` creates a template, with or without `cron`
|
|
99
|
+
(`docs/STRATEGY_EXECUTION_TDD.md`, Strategy requests and request templates).
|
|
100
|
+
`ManageRequestTemplate` targets a template:
|
|
101
|
+
|
|
102
|
+
| Action | Write |
|
|
103
|
+
|---|---|
|
|
104
|
+
| `update` | sets any of `param_config`, `callbacks`, `cron`, `enabled`, saves; setting `cron` schedules an unscheduled template |
|
|
105
|
+
| `pause` | sets `enabled = False`, saves |
|
|
106
|
+
| `resume` | sets `enabled = True`, saves |
|
|
107
|
+
| `unschedule` | sets `cron = None`, saves; the template remains |
|
|
108
|
+
|
|
109
|
+
A template is deleted with `DeleteEntity`. Both template strategies
|
|
110
|
+
are ordinary strategies: they use only their `StrategySession`, never the
|
|
111
|
+
scheduler, and the persistence chokepoint authorizes each write and keeps the
|
|
112
|
+
template's `owner` unchanged. The scheduler's `entity_saved` hook picks up
|
|
113
|
+
every change. Deleting a template's target deletes the template
|
|
114
|
+
(`dependent_on`), and the scheduler's `entities_deleted` hook removes its
|
|
115
|
+
schedule.
|
|
116
|
+
|
|
117
|
+
### The port
|
|
118
|
+
|
|
119
|
+
```python
|
|
120
|
+
class Scheduler(ABC):
|
|
121
|
+
async def entity_saved(self, entity: Entity, previous: Entity | None) -> None: ...
|
|
122
|
+
async def entities_deleted(self, entity_ids: list[str]) -> None: ...
|
|
123
|
+
async def info(self, target_id: str) -> ScheduleInfo | None: ...
|
|
124
|
+
```
|
|
125
|
+
|
|
126
|
+
Contract:
|
|
127
|
+
|
|
128
|
+
- `entity_saved` and `entities_deleted` are post-commit hooks with the same
|
|
129
|
+
shape as `AccessPort.entity_saved`. `EntityService` calls them for every
|
|
130
|
+
committed write and names no entity type; a scheduler ignores entities
|
|
131
|
+
that are not request templates.
|
|
132
|
+
- A scheduler converges on the desired schedules of all scheduled templates,
|
|
133
|
+
including after a hook it missed or that failed. How and when it re-reads
|
|
134
|
+
the full desired state is the adapter's own concern; the kernel never
|
|
135
|
+
asks it to.
|
|
136
|
+
- The hooks never raise. A failure is logged and repaired by the adapter's
|
|
137
|
+
convergence.
|
|
138
|
+
- `info` reports the held schedule for a template, or `None`. It is the only
|
|
139
|
+
answer to "is this schedule live".
|
|
140
|
+
- On a tick, a scheduler loads the template as its `owner` (an
|
|
141
|
+
identity-only principal) and skips the tick if the template is missing,
|
|
142
|
+
unscheduled, or not `enabled`. Otherwise it builds the request with
|
|
143
|
+
`new_strategy_request(entity_service, template.to_payload(),
|
|
144
|
+
template_id=template.entity_id)` and calls
|
|
145
|
+
`executor.execute_request(request, principal, wait=False)`.
|
|
146
|
+
- A scheduler never writes entities. A tick's request is created by the
|
|
147
|
+
scheduler and saved by the front door.
|
|
148
|
+
|
|
149
|
+
Invariants:
|
|
150
|
+
|
|
151
|
+
- Only `EntityService` and the composition root reference the `Scheduler`
|
|
152
|
+
port. The executor has no scheduling code.
|
|
153
|
+
- A tick is authorized by the front door and again at the start of every
|
|
154
|
+
attempt, so a principal who lost access stops running and writes nothing.
|
|
155
|
+
- A scheduler depends on `RequestTemplate`, a kernel entity type, and
|
|
156
|
+
documents that dependence (rule 7).
|
|
157
|
+
|
|
158
|
+
### Default adapter: `BeatScheduler`
|
|
159
|
+
|
|
160
|
+
`BeatScheduler(repository, reconcile_interval=300, run_reconcile_interval=300)`
|
|
161
|
+
holds schedules in
|
|
162
|
+
django-celery-beat and reconciles them against the entity repository.
|
|
163
|
+
|
|
164
|
+
Held schedules:
|
|
165
|
+
|
|
166
|
+
- A held schedule is the `PeriodicTask` named `scheduled_strategy_<target_id>`,
|
|
167
|
+
with a crontab matching `spec.cron`, enabled per `spec.enabled`, invoking
|
|
168
|
+
the `graphcore.tasks.scheduled_tick` task with `[target_id, principal_id]`.
|
|
169
|
+
|
|
170
|
+
Reconciliation:
|
|
171
|
+
|
|
172
|
+
- `entity_saved`: for a `RequestTemplate` whose `schedule_spec()`
|
|
173
|
+
differs from `previous`'s, writes the `PeriodicTask` for the new spec, or
|
|
174
|
+
deletes it when the spec is `None`.
|
|
175
|
+
- `entities_deleted`: deletes the `PeriodicTask` for each id, in batches
|
|
176
|
+
under SQLite's bound-parameter limit.
|
|
177
|
+
- Full reconcile: the `graphcore.tasks.reconcile_schedules` task reads every
|
|
178
|
+
scheduled template from the repository, writes the `PeriodicTask` for each
|
|
179
|
+
desired schedule, and deletes every `scheduled_strategy_` row whose
|
|
180
|
+
template is absent or unscheduled. It runs when the Celery process
|
|
181
|
+
starts and every `reconcile_interval` seconds through the `PeriodicTask`
|
|
182
|
+
`graphcore_reconcile_schedules`, which it also ensures.
|
|
183
|
+
- It also ensures the `graphcore_reconcile_runs` `PeriodicTask`, which runs
|
|
184
|
+
the executor's `graphcore.tasks.reconcile_runs` every
|
|
185
|
+
`run_reconcile_interval` seconds (`docs/STRATEGY_EXECUTION_TDD.md`, Run
|
|
186
|
+
reconciliation). The composition root sets both intervals from
|
|
187
|
+
`GRAPHCORE_RECONCILE_INTERVAL`.
|
|
188
|
+
- `info`: reads the `PeriodicTask` and its crontab into a `ScheduleInfo`.
|
|
189
|
+
|
|
190
|
+
Ticks:
|
|
191
|
+
|
|
192
|
+
- `scheduled_tick` is a process entry point. It resolves the Celery
|
|
193
|
+
process's runtime and performs the port's tick contract against its
|
|
194
|
+
executor. The request is then routed by workload: an IO strategy runs on
|
|
195
|
+
that process's event loop through its `InProcessDispatcher`, and a CPU
|
|
196
|
+
strategy is enqueued by its `CeleryDispatcher`.
|
|
197
|
+
|
|
198
|
+
Invariants:
|
|
199
|
+
|
|
200
|
+
- `beat_scheduler.py` and `beat_tasks.py` are the only modules that import
|
|
201
|
+
`django_celery_beat`; `graphcore/tasks.py` re-exports the two tasks for
|
|
202
|
+
their stable task names.
|
|
203
|
+
- `BeatScheduler` is constructed only in the composition root.
|
|
204
|
+
- It reads the repository and never writes through it.
|
|
205
|
+
|
|
206
|
+
### Trade-offs
|
|
207
|
+
|
|
208
|
+
- **Schedules are eventually consistent.** A change is committed when the
|
|
209
|
+
template is saved and takes effect when a hook or a full
|
|
210
|
+
reconcile applies it. Because ticks check the entity, lag delays a new or
|
|
211
|
+
changed schedule but never runs a paused or cancelled one.
|
|
212
|
+
- **No synchronous scheduling error.** An invalid cron is rejected at
|
|
213
|
+
validation; an infrastructure failure is repaired by reconciliation and is
|
|
214
|
+
visible only through `info` and logs.
|
|
215
|
+
- **A full reconcile reads every scheduled template.** Its cost grows with
|
|
216
|
+
the number of scheduled templates, once per interval.
|
|
217
|
+
- **Ticks land in the Celery process.** With Beat, IO strategies on a
|
|
218
|
+
schedule run in the Celery process, not the ASGI process. A deployment
|
|
219
|
+
that wants them in the ASGI process uses a scheduler that fires ticks
|
|
220
|
+
there.
|
|
221
|
+
|
|
222
|
+
### Open Items
|
|
223
|
+
|
|
224
|
+
- **Reconcile interval.** Whether 300 seconds suits deployments with many
|
|
225
|
+
schedules, and whether it is exposed as a setting.
|
|
226
|
+
|
|
227
|
+
## Testing
|
|
228
|
+
|
|
229
|
+
`scheduling/tests/contract.py` holds `SchedulerContract`, exported from
|
|
230
|
+
`graphcore.public.testing` and run against an in-memory fake and
|
|
231
|
+
`BeatScheduler`. Each adapter supplies a fixture that triggers its full
|
|
232
|
+
convergence. The suite covers: a save applies its desired schedule; a
|
|
233
|
+
change to `cron` or `enabled` updates it; clearing `cron` or deleting the
|
|
234
|
+
template removes it; convergence restores a schedule removed behind the
|
|
235
|
+
scheduler's back and removes one whose template is gone; hooks never raise;
|
|
236
|
+
a tick submits a new request through the front door and skips missing,
|
|
237
|
+
unscheduled, and disabled templates.
|
|
238
|
+
|
|
239
|
+
Kernel tests cover: each schedule change is one write; a tick's request
|
|
240
|
+
runs as the template's `owner` and records `template_id`; another
|
|
241
|
+
principal cannot read or manage the template; an owner who loses access to
|
|
242
|
+
the target gets failed requests and no writes; a tick for a CPU strategy is
|
|
243
|
+
dispatched by its workload's dispatcher; the registered Celery task names
|
|
244
|
+
match what Beat enqueues.
|