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,44 @@
|
|
|
1
|
+
"""The storage seam for app authors: the repository contract and the query
|
|
2
|
+
vocabulary.
|
|
3
|
+
|
|
4
|
+
from graphcore.public.entities import register_entity
|
|
5
|
+
|
|
6
|
+
def configure(entities) -> None:
|
|
7
|
+
entities.bind_storage(Board, BoardModel)
|
|
8
|
+
|
|
9
|
+
A record is an entity's own ``to_dict()``/``from_dict()`` - there is no
|
|
10
|
+
mapper. Backend-neutral - nothing here imports a database. An app registers
|
|
11
|
+
its storage from a ``configure(entities)`` hook named by its
|
|
12
|
+
``GraphCoreAppConfig.graphcore_persistence``. Storage models come from
|
|
13
|
+
``graphcore.public.persistence.django``.
|
|
14
|
+
|
|
15
|
+
Every column of a bound model is filterable: pass a predicate as
|
|
16
|
+
``EntityFilter(type_ids=..., where=Equal('slug', 'roadmap'))`` to
|
|
17
|
+
``EntityService.list_entities`` to narrow a listing to a typed app column,
|
|
18
|
+
conjoined with the caller's access predicate in one storage statement.
|
|
19
|
+
"""
|
|
20
|
+
from graphcore.persistence.repository import (
|
|
21
|
+
DeleteReceipt, DeletedEntity, EntityRepository, SaveReceipt,
|
|
22
|
+
)
|
|
23
|
+
from graphcore.types.entities import EntityFilter
|
|
24
|
+
from graphcore.types.query import (
|
|
25
|
+
AllOf, AnyOf, ContainsAny, ContainsValue, Equal, EntityQuery, InValues,
|
|
26
|
+
PageRequest, Predicate,
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
__all__ = [
|
|
30
|
+
"AllOf",
|
|
31
|
+
"AnyOf",
|
|
32
|
+
"ContainsAny",
|
|
33
|
+
"ContainsValue",
|
|
34
|
+
"DeleteReceipt",
|
|
35
|
+
"DeletedEntity",
|
|
36
|
+
"EntityFilter",
|
|
37
|
+
"EntityQuery",
|
|
38
|
+
"EntityRepository",
|
|
39
|
+
"Equal",
|
|
40
|
+
"InValues",
|
|
41
|
+
"PageRequest",
|
|
42
|
+
"Predicate",
|
|
43
|
+
"SaveReceipt",
|
|
44
|
+
]
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
"""Storage models for the Django backend.
|
|
2
|
+
|
|
3
|
+
from graphcore.public.persistence.django import EntityModel
|
|
4
|
+
|
|
5
|
+
class BoardModel(EntityModel):
|
|
6
|
+
column_order = models.JSONField(default=list)
|
|
7
|
+
|
|
8
|
+
Subclass ``EntityModel`` only when a type needs its own columns; bind it to
|
|
9
|
+
its entity class from the app's ``graphcore_persistence`` hook
|
|
10
|
+
(``entities.bind_storage(Board, BoardModel)``).
|
|
11
|
+
Requires ``django.setup()``.
|
|
12
|
+
"""
|
|
13
|
+
from graphcore.persistence.django.models import (
|
|
14
|
+
EntityModel, GrantModel, GroupModel, ServiceAccountModel, StrategyRequestModel, UserModel,
|
|
15
|
+
)
|
|
16
|
+
|
|
17
|
+
__all__ = [
|
|
18
|
+
"EntityModel",
|
|
19
|
+
"GrantModel",
|
|
20
|
+
"GroupModel",
|
|
21
|
+
"ServiceAccountModel",
|
|
22
|
+
"StrategyRequestModel",
|
|
23
|
+
"UserModel",
|
|
24
|
+
]
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
"""The scheduling seam: where recurring strategy requests are stored and
|
|
2
|
+
fired.
|
|
3
|
+
|
|
4
|
+
from graphcore.public.scheduling import Scheduler
|
|
5
|
+
|
|
6
|
+
A deployment supplies its own ``Scheduler`` from its
|
|
7
|
+
``GRAPHCORE_RUNTIME_FACTORY`` and proves it with
|
|
8
|
+
``graphcore.public.testing.SchedulerContract``.
|
|
9
|
+
|
|
10
|
+
On each tick a scheduler loads the template as its owner, skips it unless
|
|
11
|
+
it is scheduled and enabled, and submits ``template.to_payload()`` to the
|
|
12
|
+
executor (docs/SCHEDULING_TDD.md). ``Scheduler.held`` lists what it holds,
|
|
13
|
+
as ``HeldTask``s, for ``graphcore status``.
|
|
14
|
+
"""
|
|
15
|
+
from graphcore.scheduling.scheduler import Scheduler
|
|
16
|
+
from graphcore.types.schedules import HeldTask, ScheduleInfo, ScheduleSpec
|
|
17
|
+
|
|
18
|
+
__all__ = [
|
|
19
|
+
"HeldTask",
|
|
20
|
+
"ScheduleInfo",
|
|
21
|
+
"ScheduleSpec",
|
|
22
|
+
"Scheduler",
|
|
23
|
+
]
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
"""The strategy base class, its decorator, the strategy-request entity, and
|
|
2
|
+
the kernel's built-in strategies.
|
|
3
|
+
|
|
4
|
+
from graphcore.public.strategies import Strategy, register_strategy
|
|
5
|
+
from graphcore.public.entities import Entity
|
|
6
|
+
|
|
7
|
+
@register_strategy(Entity)
|
|
8
|
+
class ArchiveBoard(Strategy):
|
|
9
|
+
async def apply(self):
|
|
10
|
+
return self.strategy_request, self.entity
|
|
11
|
+
|
|
12
|
+
Most built-ins below are registered against ``Entity``, so each runs against
|
|
13
|
+
any entity type. A strategy reaches the graph through ``self.session`` (a
|
|
14
|
+
``StrategySession``) and declares its ``workload``. Nest one in your own
|
|
15
|
+
strategy by building its request with the ``request_constructor``
|
|
16
|
+
classmethod, which returns a ``StrategyRequestPayload``, and passing it to
|
|
17
|
+
``self.execute_request``. Requires ``django.setup()`` — imports Django models.
|
|
18
|
+
"""
|
|
19
|
+
from graphcore.domain.entity.request_template.RequestTemplate import RequestTemplate
|
|
20
|
+
from graphcore.domain.entity.strategy_request.StrategyRequest import StrategyRequest
|
|
21
|
+
from graphcore.domain.strategy.runner import ChangeTracker, StrategyRunner
|
|
22
|
+
from graphcore.domain.strategy.session import StrategySession
|
|
23
|
+
from graphcore.types.strategy import RequestStatus, StrategyRequestPayload, Workload
|
|
24
|
+
from graphcore.domain.strategy.BaseStrategy import (
|
|
25
|
+
CreateEntity,
|
|
26
|
+
DeleteEntity,
|
|
27
|
+
FindAndReplace,
|
|
28
|
+
RemoveAttribute,
|
|
29
|
+
ReorderChild,
|
|
30
|
+
ReparentChild,
|
|
31
|
+
SetAttributes,
|
|
32
|
+
Strategy,
|
|
33
|
+
)
|
|
34
|
+
from graphcore.domain.strategy.DeploymentStrategies import SetNewUserDefaults
|
|
35
|
+
from graphcore.domain.strategy.GrantStrategies import (
|
|
36
|
+
ChangeGrantRole,
|
|
37
|
+
CreateGrant,
|
|
38
|
+
RevokeGrant,
|
|
39
|
+
)
|
|
40
|
+
from graphcore.domain.strategy.GroupStrategies import (
|
|
41
|
+
AddMember,
|
|
42
|
+
CreateGroup,
|
|
43
|
+
ModifyGroup,
|
|
44
|
+
RemoveMember,
|
|
45
|
+
)
|
|
46
|
+
from graphcore.domain.strategy.InviteStrategies import CreateInvite
|
|
47
|
+
from graphcore.domain.strategy.RequestTemplateStrategies import (
|
|
48
|
+
CreateRequestTemplate,
|
|
49
|
+
ManageRequestTemplate,
|
|
50
|
+
)
|
|
51
|
+
from graphcore.domain.strategy.ViewStrategies import CreateView, SetViewState
|
|
52
|
+
from graphcore.registry.decorators import register_strategy
|
|
53
|
+
|
|
54
|
+
__all__ = [
|
|
55
|
+
"AddMember",
|
|
56
|
+
"ChangeGrantRole",
|
|
57
|
+
"ChangeTracker",
|
|
58
|
+
"CreateEntity",
|
|
59
|
+
"CreateGrant",
|
|
60
|
+
"CreateGroup",
|
|
61
|
+
"CreateInvite",
|
|
62
|
+
"CreateRequestTemplate",
|
|
63
|
+
"CreateView",
|
|
64
|
+
"DeleteEntity",
|
|
65
|
+
"FindAndReplace",
|
|
66
|
+
"ManageRequestTemplate",
|
|
67
|
+
"ModifyGroup",
|
|
68
|
+
"RemoveAttribute",
|
|
69
|
+
"RemoveMember",
|
|
70
|
+
"RequestStatus",
|
|
71
|
+
"RequestTemplate",
|
|
72
|
+
"ReorderChild",
|
|
73
|
+
"ReparentChild",
|
|
74
|
+
"RevokeGrant",
|
|
75
|
+
"SetAttributes",
|
|
76
|
+
"SetNewUserDefaults",
|
|
77
|
+
"SetViewState",
|
|
78
|
+
"Strategy",
|
|
79
|
+
"StrategyRequest",
|
|
80
|
+
"StrategyRequestPayload",
|
|
81
|
+
"StrategyRunner",
|
|
82
|
+
"StrategySession",
|
|
83
|
+
"Workload",
|
|
84
|
+
"register_strategy",
|
|
85
|
+
]
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""Settings for running an app's tests without a project. An app's
|
|
2
|
+
`test_settings.py` is:
|
|
3
|
+
|
|
4
|
+
from graphcore.public.test_settings import app_test_settings
|
|
5
|
+
|
|
6
|
+
globals().update(app_test_settings('notes'))
|
|
7
|
+
|
|
8
|
+
and its tests run with
|
|
9
|
+
`python -m django test notes --settings=notes.test_settings`. They get the
|
|
10
|
+
kernel's own test settings plus the app, on the database `GRAPHCORE_TEST_DB`
|
|
11
|
+
names (`postgresql`, the default, or `sqlite`) and a test database of their
|
|
12
|
+
own. Inside a project, `graphcore test` uses the project's settings instead.
|
|
13
|
+
"""
|
|
14
|
+
from graphcore.testing.settings import app_test_settings
|
|
15
|
+
|
|
16
|
+
__all__ = ['app_test_settings']
|
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
"""Test support for app authors: run your strategies against a real GraphCore
|
|
2
|
+
runtime as users you create, and discover your apps' tests.
|
|
3
|
+
|
|
4
|
+
from graphcore.public.testing import GraphCoreTestCase
|
|
5
|
+
|
|
6
|
+
class PublishTests(GraphCoreTestCase):
|
|
7
|
+
async def test_owner_can_publish(self):
|
|
8
|
+
owner = await self.create_user('owner')
|
|
9
|
+
publication = await self.create_entity(Publication, owner)
|
|
10
|
+
await self.run_strategy(
|
|
11
|
+
owner, PublishPublication.request_constructor(publication.entity_id),
|
|
12
|
+
)
|
|
13
|
+
|
|
14
|
+
`open_place` and `call_tool` render an agent view and call its tools as a
|
|
15
|
+
principal, as an agent does over `/mcp`:
|
|
16
|
+
|
|
17
|
+
async def test_the_owner_creates_a_note_from_notes(self):
|
|
18
|
+
owner = await self.create_user('owner')
|
|
19
|
+
place = await self.open_place(owner, '/notes')
|
|
20
|
+
self.assertIn('create_note', place.tools)
|
|
21
|
+
await self.call_tool(owner, '/notes', 'create_note', {'name': 'Roadmap'})
|
|
22
|
+
self.assertIn('Roadmap', (await self.open_place(owner, '/notes')).text)
|
|
23
|
+
|
|
24
|
+
A project enables app test discovery with
|
|
25
|
+
``TEST_RUNNER = 'graphcore.public.testing.GraphCoreTestRunner'``.
|
|
26
|
+
|
|
27
|
+
A deployment that replaces a port from its ``GRAPHCORE_RUNTIME_FACTORY``
|
|
28
|
+
proves its implementation with that port's contract:
|
|
29
|
+
|
|
30
|
+
class MySchedulerTests(SchedulerContract, TestCase):
|
|
31
|
+
def make_scheduler(self):
|
|
32
|
+
return MyScheduler()
|
|
33
|
+
|
|
34
|
+
`StrategySessionContract` and `DispatcherContract` do the same for a
|
|
35
|
+
strategy session adapter and an execution environment.
|
|
36
|
+
"""
|
|
37
|
+
from graphcore.agent_frontend.testing import Place
|
|
38
|
+
from graphcore.execution.tests.contract import DispatcherContract, StrategySessionContract
|
|
39
|
+
from graphcore.persistence.tests.contract import EntityRepositoryContract
|
|
40
|
+
from graphcore.scheduling.tests.contract import SchedulerContract
|
|
41
|
+
from graphcore.testing.case import GraphCoreTestCase
|
|
42
|
+
from graphcore.testing.runner import GraphCoreTestRunner
|
|
43
|
+
|
|
44
|
+
__all__ = [
|
|
45
|
+
'DispatcherContract', 'EntityRepositoryContract', 'GraphCoreTestCase', 'GraphCoreTestRunner',
|
|
46
|
+
'Place', 'SchedulerContract', 'StrategySessionContract',
|
|
47
|
+
]
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
"""
|
|
2
|
+
EntityDirectory - Central registry for all entity classes in the framework.
|
|
3
|
+
|
|
4
|
+
Replaces the old EntityEnum system with a dynamic, class-based directory
|
|
5
|
+
that uses class names as keys.
|
|
6
|
+
"""
|
|
7
|
+
import logging
|
|
8
|
+
from typing import Dict, Iterable, Optional, Set, Tuple, Type
|
|
9
|
+
|
|
10
|
+
from django.apps import apps
|
|
11
|
+
|
|
12
|
+
from graphcore.errors import KernelError
|
|
13
|
+
|
|
14
|
+
logger = logging.getLogger(__name__)
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
class EntityAlreadyRegisteredError(KernelError):
|
|
18
|
+
"""Raised when a second `register_entity` call for the same
|
|
19
|
+
`entity_type_id` declares a different `principal` flag than the first.
|
|
20
|
+
The flag is read live, at request time, by several independent decision
|
|
21
|
+
sites (grant creation, principal creation) that all need to agree, so
|
|
22
|
+
nothing may change what a
|
|
23
|
+
type_id was first registered as - which concrete class currently backs
|
|
24
|
+
that type_id may still be rebound (e.g. module re-import, or a test
|
|
25
|
+
recreating a throwaway type under the same name)."""
|
|
26
|
+
|
|
27
|
+
code = 'entity_already_registered'
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class EntityDirectoryClosedError(KernelError):
|
|
31
|
+
"""Raised when registration is attempted after discovery closes."""
|
|
32
|
+
|
|
33
|
+
code = 'entity_directory_closed'
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class StorageNotBound(KernelError):
|
|
37
|
+
"""Raised when neither an entity class nor any of its ancestors has a
|
|
38
|
+
bound storage handle."""
|
|
39
|
+
|
|
40
|
+
code = 'storage_not_bound'
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class EntityDirectoryClass:
|
|
44
|
+
"""
|
|
45
|
+
Directory for managing entity class registrations.
|
|
46
|
+
|
|
47
|
+
Uses class names as keys (e.g., 'Entity', 'Document', 'ApiModel')
|
|
48
|
+
instead of the old EntityEnum values.
|
|
49
|
+
"""
|
|
50
|
+
|
|
51
|
+
def __init__(self):
|
|
52
|
+
self._directory: Dict[str, Type] = {} # Maps entity_type_id -> class
|
|
53
|
+
self._registered_classes: Set[Type] = set() # Classes decorated with @register_entity()
|
|
54
|
+
self._app_labels: Dict[Type, str] = {} # Explicit override or resolved owner, keyed by exact class
|
|
55
|
+
self._principal_types: Set[str] = set() # entity_type_id values registered principal=True
|
|
56
|
+
self._storage: Dict[Type, object] = {} # entity class -> opaque storage handle
|
|
57
|
+
self._closed = False
|
|
58
|
+
|
|
59
|
+
def _check_open(self) -> None:
|
|
60
|
+
if self._closed:
|
|
61
|
+
raise EntityDirectoryClosedError(
|
|
62
|
+
"Entity registration is closed after application discovery."
|
|
63
|
+
)
|
|
64
|
+
|
|
65
|
+
def close(self) -> None:
|
|
66
|
+
"""Freeze entity classes and registration metadata."""
|
|
67
|
+
self._closed = True
|
|
68
|
+
|
|
69
|
+
@property
|
|
70
|
+
def closed(self) -> bool:
|
|
71
|
+
return self._closed
|
|
72
|
+
|
|
73
|
+
def register_entity(
|
|
74
|
+
self,
|
|
75
|
+
entity_class: Type,
|
|
76
|
+
app_label: Optional[str] = None,
|
|
77
|
+
principal: bool = False,
|
|
78
|
+
) -> None:
|
|
79
|
+
"""
|
|
80
|
+
Register an entity class in the directory.
|
|
81
|
+
|
|
82
|
+
Args:
|
|
83
|
+
entity_class: The entity class to register
|
|
84
|
+
app_label: Explicit owning app id, overriding module-based resolution
|
|
85
|
+
principal: Whether this type can act - a valid grant subject in its
|
|
86
|
+
own right, and a valid backing type for a Principal
|
|
87
|
+
"""
|
|
88
|
+
self._check_open()
|
|
89
|
+
if app_label is None:
|
|
90
|
+
app_config = apps.get_containing_app_config(entity_class.__module__)
|
|
91
|
+
app_label = getattr(app_config, 'graphcore_app_id', None)
|
|
92
|
+
if app_label is None:
|
|
93
|
+
raise ValueError(
|
|
94
|
+
f"Entity class {entity_class.__name__} (module {entity_class.__module__}) "
|
|
95
|
+
f"does not live inside an installed graphcore app. Move it into an app's "
|
|
96
|
+
f"entities/strategies package, or declare @register_entity(app_label='...')."
|
|
97
|
+
)
|
|
98
|
+
|
|
99
|
+
entity_type_id = f"{app_label}.{entity_class.__name__}"
|
|
100
|
+
existing_type_id = entity_class.__dict__.get('_graphcore_entity_type_id')
|
|
101
|
+
if existing_type_id is not None and existing_type_id != entity_type_id:
|
|
102
|
+
raise EntityAlreadyRegisteredError(
|
|
103
|
+
f"Entity class {entity_class.__name__} is already identified as "
|
|
104
|
+
f"'{existing_type_id}', not '{entity_type_id}'."
|
|
105
|
+
)
|
|
106
|
+
|
|
107
|
+
if entity_type_id in self._directory:
|
|
108
|
+
existing_principal = entity_type_id in self._principal_types
|
|
109
|
+
if existing_principal != principal:
|
|
110
|
+
raise EntityAlreadyRegisteredError(
|
|
111
|
+
f"Entity '{entity_type_id}' is already registered with "
|
|
112
|
+
f"principal={existing_principal} - cannot re-register with principal={principal}."
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
entity_class._graphcore_entity_type_id = entity_type_id
|
|
116
|
+
self._registered_classes.add(entity_class)
|
|
117
|
+
self._app_labels[entity_class] = app_label
|
|
118
|
+
self._directory[entity_type_id] = entity_class
|
|
119
|
+
if principal:
|
|
120
|
+
self._principal_types.add(entity_type_id)
|
|
121
|
+
logger.debug(f"Registered entity: {entity_type_id}")
|
|
122
|
+
|
|
123
|
+
def is_principal(self, entity_type_id: str) -> bool:
|
|
124
|
+
"""Whether the type at this entity_type_id was registered principal=True."""
|
|
125
|
+
return entity_type_id in self._principal_types
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def principal_type_ids(self) -> frozenset[str]:
|
|
129
|
+
"""Return the immutable set of registered principal entity type IDs."""
|
|
130
|
+
return frozenset(self._principal_types)
|
|
131
|
+
|
|
132
|
+
def get_entity_type_id(self, entity_class: Type) -> str:
|
|
133
|
+
"""
|
|
134
|
+
Get the stable entity_type_id for a class.
|
|
135
|
+
|
|
136
|
+
The owning app is resolved from the class's own module via
|
|
137
|
+
``apps.get_containing_app_config``, not from the order apps were
|
|
138
|
+
drained during discovery - so a cross-app import that pulls this
|
|
139
|
+
class into another app's module as a side effect can't stamp it with
|
|
140
|
+
the wrong owner, and entity_type_id doesn't depend on INSTALLED_APPS
|
|
141
|
+
order. An explicit ``@register_entity(app_label=...)`` overrides that
|
|
142
|
+
lookup. The resolution is cached per class after the first call.
|
|
143
|
+
|
|
144
|
+
Lookup requires the exact class to have been registered - an
|
|
145
|
+
undecorated subclass of a registered entity does not inherit its
|
|
146
|
+
parent's label.
|
|
147
|
+
|
|
148
|
+
Args:
|
|
149
|
+
entity_class: The entity class
|
|
150
|
+
|
|
151
|
+
Returns:
|
|
152
|
+
The entity_type_id (e.g., 'graphcore.Document')
|
|
153
|
+
"""
|
|
154
|
+
if entity_class not in self._registered_classes:
|
|
155
|
+
raise ValueError(
|
|
156
|
+
f"Entity class {entity_class.__name__} is not registered. "
|
|
157
|
+
f"Decorate it with @register_entity()."
|
|
158
|
+
)
|
|
159
|
+
|
|
160
|
+
entity_type_id = entity_class.__dict__.get('_graphcore_entity_type_id')
|
|
161
|
+
if entity_type_id is None:
|
|
162
|
+
raise ValueError(
|
|
163
|
+
f"Entity class {entity_class.__name__} has no registered type ID."
|
|
164
|
+
)
|
|
165
|
+
return entity_type_id
|
|
166
|
+
|
|
167
|
+
def get_entity_class(self, entity_type_id: str) -> Optional[Type]:
|
|
168
|
+
"""
|
|
169
|
+
Get an entity class by its entity_type_id.
|
|
170
|
+
|
|
171
|
+
Args:
|
|
172
|
+
entity_type_id: The entity type ID (e.g., 'graphcore.Document')
|
|
173
|
+
|
|
174
|
+
Returns:
|
|
175
|
+
The entity class, or None if not found
|
|
176
|
+
"""
|
|
177
|
+
return self._directory.get(entity_type_id)
|
|
178
|
+
|
|
179
|
+
def get_all_entities(self) -> Dict[str, Type]:
|
|
180
|
+
"""
|
|
181
|
+
Get all registered entity classes.
|
|
182
|
+
|
|
183
|
+
Returns:
|
|
184
|
+
Dictionary mapping class names to entity classes
|
|
185
|
+
"""
|
|
186
|
+
return self._directory.copy()
|
|
187
|
+
|
|
188
|
+
def get_entity_directory(self) -> Dict[str, dict]:
|
|
189
|
+
"""
|
|
190
|
+
Get a serialized version of the entity directory for API responses.
|
|
191
|
+
|
|
192
|
+
Returns:
|
|
193
|
+
Dictionary mapping entity_type_id to entity metadata
|
|
194
|
+
"""
|
|
195
|
+
result = {}
|
|
196
|
+
|
|
197
|
+
for entity_type_id, entity_class in self._directory.items():
|
|
198
|
+
entity_info = {
|
|
199
|
+
'entity_type_id': entity_type_id,
|
|
200
|
+
'name': entity_class.__name__,
|
|
201
|
+
'principal': entity_type_id in self._principal_types,
|
|
202
|
+
}
|
|
203
|
+
|
|
204
|
+
result[entity_type_id] = entity_info
|
|
205
|
+
|
|
206
|
+
return result
|
|
207
|
+
|
|
208
|
+
def bind_storage(self, entity_cls: Type, storage: object) -> None:
|
|
209
|
+
"""Bind `entity_cls` to an opaque storage handle (a Django model
|
|
210
|
+
class for the Django repository). Last registration for the same
|
|
211
|
+
class wins, so an app can rebind a kernel type."""
|
|
212
|
+
self._check_open()
|
|
213
|
+
self._storage[entity_cls] = storage
|
|
214
|
+
|
|
215
|
+
def storage(self, entity_cls: Type) -> object:
|
|
216
|
+
"""The storage handle for `entity_cls`: exact match first, then the
|
|
217
|
+
nearest bound ancestor in the MRO - so a subclass that adds no
|
|
218
|
+
columns inherits its parent's storage without binding one."""
|
|
219
|
+
for candidate in entity_cls.__mro__:
|
|
220
|
+
storage = self._storage.get(candidate)
|
|
221
|
+
if storage is not None:
|
|
222
|
+
return storage
|
|
223
|
+
raise StorageNotBound(
|
|
224
|
+
f"No storage bound for {entity_cls.__name__} or any of its ancestors."
|
|
225
|
+
)
|
|
226
|
+
|
|
227
|
+
def storage_classes(self) -> Set[object]:
|
|
228
|
+
"""Every storage handle bound to a registered entity type - for
|
|
229
|
+
backends that need to enumerate their tables (e.g. deriving
|
|
230
|
+
filterable fields)."""
|
|
231
|
+
return {self.storage(entity_cls) for entity_cls in self.get_all_entities().values()}
|
|
232
|
+
|
|
233
|
+
def register_pending(
|
|
234
|
+
self, entity_registrations: Iterable[Tuple[Type, Optional[str], bool]]
|
|
235
|
+
) -> None:
|
|
236
|
+
"""
|
|
237
|
+
Register (entity_class, app_label_override, principal) tuples
|
|
238
|
+
discovered during startup.
|
|
239
|
+
"""
|
|
240
|
+
for entity_class, app_label, principal in entity_registrations:
|
|
241
|
+
self.register_entity(entity_class, app_label, principal=principal)
|
|
242
|
+
|
|
243
|
+
|
|
244
|
+
# Global singleton instance
|
|
245
|
+
EntityDirectory = EntityDirectoryClass()
|
|
246
|
+
|
|
@@ -0,0 +1,147 @@
|
|
|
1
|
+
# The registry: how types reach the kernel
|
|
2
|
+
|
|
3
|
+
The registry is the binding layer between application code and the kernel.
|
|
4
|
+
It answers two questions at startup — *which types exist* and *what facts
|
|
5
|
+
are attached to them* — and then freezes, so every request sees the same
|
|
6
|
+
answers. Nothing here is a service; it holds no per-request state.
|
|
7
|
+
|
|
8
|
+
For the rule deciding *where* a type-level fact belongs (class attribute vs.
|
|
9
|
+
external declaration), see [`TYPE_METADATA_PLACEMENT.md`](TYPE_METADATA_PLACEMENT.md).
|
|
10
|
+
|
|
11
|
+
## What an app is
|
|
12
|
+
|
|
13
|
+
One `GraphCoreAppConfig` subclass (`apps.py`) is one app. The kernel itself is
|
|
14
|
+
an app (`GraphCoreConfig`, id `graphcore`) and goes through the same machinery
|
|
15
|
+
as everything else. The config's attributes are the whole opt-in surface:
|
|
16
|
+
|
|
17
|
+
| Attribute | Meaning |
|
|
18
|
+
|---|---|
|
|
19
|
+
| `graphcore_app_id` | Stable id that namespaces the app's entity type ids (`<app_id>.<ClassName>`) and keys its mount folder. Required. |
|
|
20
|
+
| `graphcore_packages` | Sub-packages discovery imports so decorators fire. Default `('entities', 'strategies')`; the kernel uses `('domain.entity', 'domain.strategy')`. |
|
|
21
|
+
| `graphcore_authorization` | Dotted path to a `configure(policy: AccessPolicy)` function. Optional. |
|
|
22
|
+
| `graphcore_persistence` | Dotted path to a `configure(entities: EntityDirectory)` function that binds entity types to storage. Optional. |
|
|
23
|
+
| `graphcore_service_clients` | Names of confidential clients the app's own processes sign in with (client-credentials grant), registered at the issuer as `<app_id>-<name>` by the distro's `graphcore identity apply`. A token issued to one authenticates as a `ServiceAccount` (`graphcore.auth.authn.service_accounts`). Default `()`. |
|
|
24
|
+
|
|
25
|
+
Which apps are installed is a project concern (`app_discovery.py`: entry
|
|
26
|
+
points in the `graphcore.apps` group plus an `apps/` directory scan), settled
|
|
27
|
+
before Django starts. The registry only ever sees `apps.get_app_configs()`.
|
|
28
|
+
|
|
29
|
+
## Two registration shapes
|
|
30
|
+
|
|
31
|
+
Every type-level fact enters through one of two shapes. Knowing which is
|
|
32
|
+
which explains most of this package.
|
|
33
|
+
|
|
34
|
+
### 1. Decorators (import-driven, per class)
|
|
35
|
+
|
|
36
|
+
`@register_entity(...)` and `@register_strategy(EntityClass)` in
|
|
37
|
+
`decorators.py`. A decorator does **not** register anything when it runs; it
|
|
38
|
+
appends the class to a module-level pending list. Registration only happens
|
|
39
|
+
when discovery drains that list. This indirection is what lets the kernel
|
|
40
|
+
stamp each class with its owning app and refuse late registrations.
|
|
41
|
+
|
|
42
|
+
Because a decorator only fires when its module is imported, and Django only
|
|
43
|
+
imports `models.py`, `apps.py` and `migrations/` on its own, discovery has to
|
|
44
|
+
import the rest. That is what `graphcore_packages` is for: each named package
|
|
45
|
+
is walked recursively (`_import_package`, tests skipped) so every decorated
|
|
46
|
+
class is seen. A package that does not exist is fine; a package that exists
|
|
47
|
+
and fails to import stops startup rather than being swallowed.
|
|
48
|
+
|
|
49
|
+
Facts carried this way describe one type alone: `group`, `principal`, the
|
|
50
|
+
owning app, the strategy → entity pairing.
|
|
51
|
+
|
|
52
|
+
### 2. Configurators (explicit call, per app)
|
|
53
|
+
|
|
54
|
+
An app names a function; the kernel calls it once with the registry object it
|
|
55
|
+
may write to. Today there are two:
|
|
56
|
+
|
|
57
|
+
- `graphcore_authorization` → `configure(policy)` receives the `AccessPolicy`
|
|
58
|
+
and declares each of the app's types with `policy.define(Type, ...)`, adds
|
|
59
|
+
roles to other apps' types with `policy.extend`, and declares groups with
|
|
60
|
+
`policy.declare_group`.
|
|
61
|
+
- `graphcore_persistence` → `configure(entities)` receives the
|
|
62
|
+
`EntityDirectory` and calls `bind_storage(entity_cls, storage)`.
|
|
63
|
+
|
|
64
|
+
Configurators run **after** every decorator has been drained, so they can
|
|
65
|
+
refer to any registered class from any app. They run in `INSTALLED_APPS`
|
|
66
|
+
order, and later calls win where the target allows it, which is how an app
|
|
67
|
+
overrides a kernel default: the kernel's own configurator runs first because
|
|
68
|
+
`graphcore` precedes apps in `INSTALLED_APPS`.
|
|
69
|
+
|
|
70
|
+
Facts carried this way either pair two independently defined types (an
|
|
71
|
+
entity with a role, an entity with a strategy allowlist) or bind a type to
|
|
72
|
+
infrastructure (a storage model). Neither can live on the class without an
|
|
73
|
+
import cycle — see the relational test in `TYPE_METADATA_PLACEMENT.md`.
|
|
74
|
+
|
|
75
|
+
## Startup sequence
|
|
76
|
+
|
|
77
|
+
`GraphCoreConfig.ready()` calls `discovery.discover_all()`, which is the
|
|
78
|
+
whole registration lifecycle:
|
|
79
|
+
|
|
80
|
+
1. For each app config with a `graphcore_app_id`: import its
|
|
81
|
+
`graphcore_packages`, then drain the pending decorator lists into the
|
|
82
|
+
registry (`register_pending`). Entity type ids are resolved from
|
|
83
|
+
the class's *own* module via `apps.get_containing_app_config`, so a
|
|
84
|
+
cross-app import cannot mis-stamp a class and ids do not depend on
|
|
85
|
+
`INSTALLED_APPS` order.
|
|
86
|
+
2. Configurators, each over `apps.get_app_configs()` in `INSTALLED_APPS`
|
|
87
|
+
order: first every app's `graphcore_persistence`, then every app's
|
|
88
|
+
`graphcore_authorization`. The kernel is just another app here - its
|
|
89
|
+
persistence hook is `persistence/django/bindings.configure` and its
|
|
90
|
+
authorization hook is `auth/authz/kernel_policy.configure`, both declared
|
|
91
|
+
on `GraphCoreConfig` like any other app, and both run first because
|
|
92
|
+
`graphcore` precedes apps in `INSTALLED_APPS`.
|
|
93
|
+
3. `finalize()` — every registry closes.
|
|
94
|
+
|
|
95
|
+
## The registry
|
|
96
|
+
|
|
97
|
+
`registry.Registry` is one struct holding the three registries for one
|
|
98
|
+
process (or one test):
|
|
99
|
+
|
|
100
|
+
| Field | Type | Holds |
|
|
101
|
+
|---|---|---|
|
|
102
|
+
| `entities` | `EntityDirectoryClass` | `entity_type_id ↔ class`, the `principal` set, owning app per class, storage handle per class (exact match, then nearest ancestor in the MRO) |
|
|
103
|
+
| `strategies` | `StrategyDirectoryClass` | entity class name → strategy dotted paths (stored as strings for lazy import), `read_only_strategy` captured at registration |
|
|
104
|
+
| `policy` | `AccessPolicy` | one `define` per type (shareable, roles, strategies, create, creatable, public, read, delete, can_contain, contained_by), roles added with `extend`, declared groups |
|
|
105
|
+
|
|
106
|
+
`DEFAULT_REGISTRY` is the process-wide instance, built from the module-level
|
|
107
|
+
singletons (`EntityDirectory`, `StrategyDirectory`, `DEFAULT_POLICY`). This
|
|
108
|
+
is registry binding, not dependency injection: a type is the lookup key,
|
|
109
|
+
never a consumer of the bound value. Live infrastructure — the repository,
|
|
110
|
+
cache, access adapter, broadcaster — is composed separately, over a
|
|
111
|
+
`Registry`, by `graphcore/runtime.py`; see that module's docstring for the
|
|
112
|
+
composition root's own rules.
|
|
113
|
+
|
|
114
|
+
## Closing
|
|
115
|
+
|
|
116
|
+
`finalize()` calls `close()`/`freeze()` on every registry. After that, any
|
|
117
|
+
`register_*` raises a typed `*ClosedError`. This is the consistency guarantee
|
|
118
|
+
from `TYPE_METADATA_PLACEMENT.md`: facts read at more than one decision site
|
|
119
|
+
within a request (`shareable`, a strategy's required permission, a role's
|
|
120
|
+
permission set) are captured once, before serving, and cannot drift.
|
|
121
|
+
|
|
122
|
+
Two consequences follow. `EntityDirectory.register_entity` refuses to
|
|
123
|
+
re-register a type id with *different* flags even before closing, because
|
|
124
|
+
several decision sites read those flags. And `StrategyDirectory` snapshots
|
|
125
|
+
`read_only_strategy` at registration and exposes `is_read_only()` so policy
|
|
126
|
+
never does a live `getattr` on the class.
|
|
127
|
+
|
|
128
|
+
## Forking for tests
|
|
129
|
+
|
|
130
|
+
`Registry.fork_open()` deep-copies every registry into a new, *unclosed*
|
|
131
|
+
`Registry`. A test that needs a throwaway entity type or a custom role
|
|
132
|
+
registers into the fork, then calls `graphcore.runtime.django_runtime(fork)`
|
|
133
|
+
(or `build_runtime(...)` directly, for fakes) to get services wired over it;
|
|
134
|
+
the process-wide registry is untouched. This is why services take a
|
|
135
|
+
`registry` argument rather than reaching for the singletons directly.
|
|
136
|
+
|
|
137
|
+
## Files
|
|
138
|
+
|
|
139
|
+
| File | Role |
|
|
140
|
+
|---|---|
|
|
141
|
+
| `decorators.py` | `register_entity`, `register_strategy`; pending lists |
|
|
142
|
+
| `discovery.py` | `discover_all()` — the startup sequence above |
|
|
143
|
+
| `EntityDirectory.py` | entity type registry, storage bindings (`bind_storage`/`storage`) |
|
|
144
|
+
| `StrategyDirectory.py` | strategy registry, lazy class loading, debug reload |
|
|
145
|
+
| `registry.py` | `Registry`, `DEFAULT_REGISTRY`, `fork_open` |
|
|
146
|
+
| `app_discovery.py` | which apps a project installs (entry points + `apps/` scan) |
|
|
147
|
+
| `TYPE_METADATA_PLACEMENT.md` | where a type-level fact belongs |
|