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.
Files changed (343) hide show
  1. graphcore/__init__.py +5 -0
  2. graphcore/agent_frontend/__init__.py +8 -0
  3. graphcore/agent_frontend/api.py +69 -0
  4. graphcore/agent_frontend/base/__init__.py +11 -0
  5. graphcore/agent_frontend/base/views.py +167 -0
  6. graphcore/agent_frontend/client.py +31 -0
  7. graphcore/agent_frontend/context.py +157 -0
  8. graphcore/agent_frontend/errors.py +12 -0
  9. graphcore/agent_frontend/loading.py +54 -0
  10. graphcore/agent_frontend/registry.py +42 -0
  11. graphcore/agent_frontend/render.py +207 -0
  12. graphcore/agent_frontend/server.py +103 -0
  13. graphcore/agent_frontend/signatures.py +35 -0
  14. graphcore/agent_frontend/testing.py +45 -0
  15. graphcore/agent_frontend/tests/__init__.py +0 -0
  16. graphcore/agent_frontend/tests/fakes.py +114 -0
  17. graphcore/agent_frontend/tests/test_frontend.py +447 -0
  18. graphcore/agent_frontend/tests/test_loading.py +83 -0
  19. graphcore/agent_frontend/tests/test_server.py +109 -0
  20. graphcore/agent_frontend/tools.py +137 -0
  21. graphcore/api/__init__.py +4 -0
  22. graphcore/api/graph_api.py +378 -0
  23. graphcore/api/predicate_codec.py +81 -0
  24. graphcore/api/tests/__init__.py +0 -0
  25. graphcore/api/tests/test_changed_entities.py +109 -0
  26. graphcore/api/tests/test_graph_api.py +290 -0
  27. graphcore/api/tests/test_graph_api_access.py +94 -0
  28. graphcore/api/tests/test_graph_api_grants.py +90 -0
  29. graphcore/api/tests/test_predicate_codec.py +83 -0
  30. graphcore/api/tests/test_subtree_query.py +79 -0
  31. graphcore/apps.py +71 -0
  32. graphcore/auth/__init__.py +1 -0
  33. graphcore/auth/authn/README.md +178 -0
  34. graphcore/auth/authn/__init__.py +3 -0
  35. graphcore/auth/authn/authenticator.py +120 -0
  36. graphcore/auth/authn/onboarding.py +105 -0
  37. graphcore/auth/authn/principals.py +20 -0
  38. graphcore/auth/authn/resource_metadata.py +43 -0
  39. graphcore/auth/authn/service_accounts.py +96 -0
  40. graphcore/auth/authn/testing.py +96 -0
  41. graphcore/auth/authn/tests/__init__.py +0 -0
  42. graphcore/auth/authn/tests/test_authenticator.py +145 -0
  43. graphcore/auth/authn/tests/test_onboarding.py +145 -0
  44. graphcore/auth/authn/tests/test_service_accounts.py +180 -0
  45. graphcore/auth/authn/users.py +59 -0
  46. graphcore/auth/authz/__init__.py +0 -0
  47. graphcore/auth/authz/access_port.py +120 -0
  48. graphcore/auth/authz/adapter/__init__.py +0 -0
  49. graphcore/auth/authz/adapter/default_access_adapter.py +556 -0
  50. graphcore/auth/authz/adapter/tests/__init__.py +0 -0
  51. graphcore/auth/authz/adapter/tests/test_default_adapter.py +543 -0
  52. graphcore/auth/authz/adapter/tests/test_entity_write_hooks.py +207 -0
  53. graphcore/auth/authz/adapter/tests/test_group_types.py +70 -0
  54. graphcore/auth/authz/adapter/tests/test_sync_support.py +209 -0
  55. graphcore/auth/authz/defaults.py +26 -0
  56. graphcore/auth/authz/kernel_policy.py +191 -0
  57. graphcore/auth/authz/kernel_writes.py +31 -0
  58. graphcore/auth/authz/lookups.py +25 -0
  59. graphcore/auth/authz/policy.py +403 -0
  60. graphcore/auth/authz/tests/__init__.py +0 -0
  61. graphcore/auth/authz/tests/test_can_contain.py +150 -0
  62. graphcore/auth/authz/tests/test_contained_by.py +167 -0
  63. graphcore/auth/authz/tests/test_creation.py +391 -0
  64. graphcore/auth/authz/tests/test_delete_permission.py +82 -0
  65. graphcore/auth/authz/tests/test_granted_to_me.py +160 -0
  66. graphcore/auth/authz/tests/test_integration.py +637 -0
  67. graphcore/auth/authz/tests/test_invites.py +184 -0
  68. graphcore/auth/authz/tests/test_kernel_policy.py +140 -0
  69. graphcore/auth/authz/tests/test_lockout.py +132 -0
  70. graphcore/auth/authz/tests/test_policy.py +329 -0
  71. graphcore/auth/authz/tests/test_primitives.py +73 -0
  72. graphcore/auth/authz/tests/test_principal_creation.py +62 -0
  73. graphcore/bootstrap/__init__.py +0 -0
  74. graphcore/bootstrap/deployment.py +67 -0
  75. graphcore/bootstrap/signals.py +16 -0
  76. graphcore/bootstrap/tests/__init__.py +0 -0
  77. graphcore/bootstrap/tests/test_deployment_seed.py +154 -0
  78. graphcore/broadcast/__init__.py +4 -0
  79. graphcore/broadcast/broadcaster.py +201 -0
  80. graphcore/broadcast/channels.py +56 -0
  81. graphcore/broadcast/tests/__init__.py +0 -0
  82. graphcore/broadcast/tests/test_broadcaster.py +444 -0
  83. graphcore/celery.py +14 -0
  84. graphcore/docs/AGENT_FRONTEND_TDD.md +389 -0
  85. graphcore/docs/ARCHITECTURE_PRINCIPLES.md +152 -0
  86. graphcore/docs/AUTHORIZATION_TECHNICAL_TDD.md +1379 -0
  87. graphcore/docs/ENTITY_REFERENCE_TDD.md +561 -0
  88. graphcore/docs/GRAPHAPI_FRONT_DOOR.md +173 -0
  89. graphcore/docs/RUNTIME.md +90 -0
  90. graphcore/docs/SCHEDULING_TDD.md +244 -0
  91. graphcore/docs/STRATEGY_EXECUTION_TDD.md +1043 -0
  92. graphcore/docs/VIEW_ENTITY_TDD.md +522 -0
  93. graphcore/docs/VIEW_SYSTEM_TDD.md +307 -0
  94. graphcore/docs/__init__.py +0 -0
  95. graphcore/docs/doc_topics.py +97 -0
  96. graphcore/docs/docs_discovery.py +64 -0
  97. graphcore/docs/public_api.py +56 -0
  98. graphcore/domain/__init__.py +0 -0
  99. graphcore/domain/entity/Entity.py +204 -0
  100. graphcore/domain/entity/__init__.py +0 -0
  101. graphcore/domain/entity/deployment/Deployment.py +25 -0
  102. graphcore/domain/entity/deployment/__init__.py +0 -0
  103. graphcore/domain/entity/grant/Grant.py +31 -0
  104. graphcore/domain/entity/grant/__init__.py +0 -0
  105. graphcore/domain/entity/group/Group.py +48 -0
  106. graphcore/domain/entity/group/README.md +88 -0
  107. graphcore/domain/entity/group/__init__.py +0 -0
  108. graphcore/domain/entity/invite/Invite.py +31 -0
  109. graphcore/domain/entity/invite/__init__.py +0 -0
  110. graphcore/domain/entity/request_template/RequestTemplate.py +48 -0
  111. graphcore/domain/entity/request_template/__init__.py +0 -0
  112. graphcore/domain/entity/request_template/tests/__init__.py +0 -0
  113. graphcore/domain/entity/request_template/tests/test_request_template.py +52 -0
  114. graphcore/domain/entity/service_account/ServiceAccount.py +41 -0
  115. graphcore/domain/entity/service_account/__init__.py +0 -0
  116. graphcore/domain/entity/strategy_request/StrategyRequest.py +61 -0
  117. graphcore/domain/entity/strategy_request/__init__.py +0 -0
  118. graphcore/domain/entity/strategy_request/tests/__init__.py +0 -0
  119. graphcore/domain/entity/strategy_request/tests/test_strategy_request_entity.py +35 -0
  120. graphcore/domain/entity/tests/__init__.py +0 -0
  121. graphcore/domain/entity/tests/test_entity.py +227 -0
  122. graphcore/domain/entity/tests/test_grant_group_entities.py +36 -0
  123. graphcore/domain/entity/tests/test_write_once_fields.py +98 -0
  124. graphcore/domain/entity/user/User.py +39 -0
  125. graphcore/domain/entity/user/__init__.py +0 -0
  126. graphcore/domain/entity/user/tests/__init__.py +0 -0
  127. graphcore/domain/entity/user/tests/test_user_entity.py +33 -0
  128. graphcore/domain/entity/view/View.py +37 -0
  129. graphcore/domain/entity/view/__init__.py +0 -0
  130. graphcore/domain/entity/view/position.py +78 -0
  131. graphcore/domain/entity/view/tests/__init__.py +0 -0
  132. graphcore/domain/entity/view/tests/test_position.py +71 -0
  133. graphcore/domain/entity/view/tests/test_view_entity.py +134 -0
  134. graphcore/domain/strategy/BaseStrategy.py +759 -0
  135. graphcore/domain/strategy/DeploymentStrategies.py +55 -0
  136. graphcore/domain/strategy/GrantStrategies.py +189 -0
  137. graphcore/domain/strategy/GroupStrategies.py +193 -0
  138. graphcore/domain/strategy/InviteStrategies.py +84 -0
  139. graphcore/domain/strategy/RequestTemplateStrategies.py +126 -0
  140. graphcore/domain/strategy/ViewStrategies.py +219 -0
  141. graphcore/domain/strategy/__init__.py +0 -0
  142. graphcore/domain/strategy/runner.py +84 -0
  143. graphcore/domain/strategy/session.py +56 -0
  144. graphcore/domain/strategy/tests/BaseStrategyTest.py +167 -0
  145. graphcore/domain/strategy/tests/__init__.py +0 -0
  146. graphcore/domain/strategy/tests/test_BaseStrategies.py +870 -0
  147. graphcore/domain/strategy/tests/test_grant_strategies.py +245 -0
  148. graphcore/domain/strategy/tests/test_group_strategies.py +99 -0
  149. graphcore/domain/strategy/tests/test_runner.py +220 -0
  150. graphcore/domain/strategy/tests/test_strategy_locks.py +446 -0
  151. graphcore/domain/strategy/tests/test_utils.py +95 -0
  152. graphcore/domain/strategy/tests/test_view_strategies.py +436 -0
  153. graphcore/errors.py +145 -0
  154. graphcore/execution/README.md +97 -0
  155. graphcore/execution/StrategyExecutorService.py +333 -0
  156. graphcore/execution/__init__.py +0 -0
  157. graphcore/execution/dispatcher.py +19 -0
  158. graphcore/execution/environments/__init__.py +0 -0
  159. graphcore/execution/environments/celery.py +59 -0
  160. graphcore/execution/environments/in_process.py +55 -0
  161. graphcore/execution/local_session.py +117 -0
  162. graphcore/execution/redis_run_events.py +74 -0
  163. graphcore/execution/requests.py +22 -0
  164. graphcore/execution/run_events.py +85 -0
  165. graphcore/execution/strategy_context.py +54 -0
  166. graphcore/execution/tasks.py +34 -0
  167. graphcore/execution/tests/__init__.py +5 -0
  168. graphcore/execution/tests/contract.py +171 -0
  169. graphcore/execution/tests/support.py +310 -0
  170. graphcore/execution/tests/test_dispatchers.py +76 -0
  171. graphcore/execution/tests/test_executor.py +368 -0
  172. graphcore/execution/tests/test_local_session.py +95 -0
  173. graphcore/execution/tests/test_reconcile_runs.py +134 -0
  174. graphcore/execution/tests/test_run_events.py +106 -0
  175. graphcore/execution/tests/test_strategy_context.py +62 -0
  176. graphcore/gateway/__init__.py +1 -0
  177. graphcore/gateway/remote.py +35 -0
  178. graphcore/gateway/tests/__init__.py +0 -0
  179. graphcore/gateway/tests/test_remote.py +30 -0
  180. graphcore/graph/EntityService.py +710 -0
  181. graphcore/graph/__init__.py +0 -0
  182. graphcore/graph/entity_cache.py +152 -0
  183. graphcore/graph/tests/__init__.py +4 -0
  184. graphcore/graph/tests/test_EntityService.py +908 -0
  185. graphcore/graph/tests/test_EntityService_list.py +170 -0
  186. graphcore/graph/tests/test_EntityService_model_resolution.py +339 -0
  187. graphcore/graph/tests/test_EntityService_referrers.py +236 -0
  188. graphcore/graph/tests/test_EntityService_routing.py +119 -0
  189. graphcore/graph/tests/test_dependent_on.py +141 -0
  190. graphcore/graph/tests/test_engine_is_type_agnostic.py +25 -0
  191. graphcore/graph/tests/test_engine_resolves_read_permission.py +93 -0
  192. graphcore/graph/tests/test_entity_cache.py +159 -0
  193. graphcore/graph/tests/test_null_entity_cache.py +12 -0
  194. graphcore/management/__init__.py +0 -0
  195. graphcore/management/commands/__init__.py +0 -0
  196. graphcore/management/commands/dev_reset.py +18 -0
  197. graphcore/management/commands/graphcore_createadmin.py +65 -0
  198. graphcore/management/commands/graphcore_policy.py +59 -0
  199. graphcore/management/commands/graphcore_status.py +98 -0
  200. graphcore/management/tests/__init__.py +0 -0
  201. graphcore/management/tests/test_createadmin.py +78 -0
  202. graphcore/management/tests/test_policy_command.py +46 -0
  203. graphcore/management/tests/test_status_command.py +85 -0
  204. graphcore/migrations/0001_initial.py +186 -0
  205. graphcore/migrations/0002_invite.py +26 -0
  206. graphcore/migrations/__init__.py +0 -0
  207. graphcore/models.py +11 -0
  208. graphcore/persistence/ENTITY_REPOSITORY_TECHNICAL_TDD.md +396 -0
  209. graphcore/persistence/__init__.py +6 -0
  210. graphcore/persistence/django/__init__.py +0 -0
  211. graphcore/persistence/django/backends.py +43 -0
  212. graphcore/persistence/django/bindings.py +28 -0
  213. graphcore/persistence/django/cache.py +38 -0
  214. graphcore/persistence/django/compiler.py +214 -0
  215. graphcore/persistence/django/identity.py +18 -0
  216. graphcore/persistence/django/models.py +252 -0
  217. graphcore/persistence/django/repository.py +525 -0
  218. graphcore/persistence/django/tests/__init__.py +0 -0
  219. graphcore/persistence/django/tests/test_backends.py +68 -0
  220. graphcore/persistence/django/tests/test_compiler.py +269 -0
  221. graphcore/persistence/django/tests/test_repository.py +472 -0
  222. graphcore/persistence/django/tests/test_shared_column.py +120 -0
  223. graphcore/persistence/django/tests/test_threads.py +50 -0
  224. graphcore/persistence/django/tests/test_update_shape.py +175 -0
  225. graphcore/persistence/django/threads.py +38 -0
  226. graphcore/persistence/repository.py +172 -0
  227. graphcore/persistence/tests/__init__.py +0 -0
  228. graphcore/persistence/tests/contract.py +688 -0
  229. graphcore/persistence/tests/evaluate.py +51 -0
  230. graphcore/persistence/tests/fixtures.py +32 -0
  231. graphcore/persistence/tests/memory.py +263 -0
  232. graphcore/persistence/tests/test_memory_repository.py +10 -0
  233. graphcore/persistence/tests/test_query_types.py +127 -0
  234. graphcore/public/__init__.py +9 -0
  235. graphcore/public/api.py +9 -0
  236. graphcore/public/apps.py +10 -0
  237. graphcore/public/auth/__init__.py +1 -0
  238. graphcore/public/auth/grants.py +7 -0
  239. graphcore/public/auth/onboarding.py +8 -0
  240. graphcore/public/auth/perms.py +7 -0
  241. graphcore/public/auth/policy.py +10 -0
  242. graphcore/public/auth/roles.py +8 -0
  243. graphcore/public/auth/subjects.py +7 -0
  244. graphcore/public/entities/__init__.py +32 -0
  245. graphcore/public/errors.py +19 -0
  246. graphcore/public/persistence/__init__.py +44 -0
  247. graphcore/public/persistence/django.py +24 -0
  248. graphcore/public/scheduling.py +23 -0
  249. graphcore/public/strategies/__init__.py +85 -0
  250. graphcore/public/test_settings.py +16 -0
  251. graphcore/public/testing.py +47 -0
  252. graphcore/registry/EntityDirectory.py +246 -0
  253. graphcore/registry/README.md +147 -0
  254. graphcore/registry/StrategyDirectory.py +308 -0
  255. graphcore/registry/TYPE_METADATA_PLACEMENT.md +66 -0
  256. graphcore/registry/__init__.py +0 -0
  257. graphcore/registry/app_discovery.py +108 -0
  258. graphcore/registry/decorators.py +77 -0
  259. graphcore/registry/discovery.py +111 -0
  260. graphcore/registry/registry.py +79 -0
  261. graphcore/registry/tests/__init__.py +0 -0
  262. graphcore/registry/tests/test_agent_frontend_discovery.py +56 -0
  263. graphcore/registry/tests/test_app_config.py +36 -0
  264. graphcore/registry/tests/test_discovery.py +147 -0
  265. graphcore/registry/tests/test_entity_directory_storage.py +73 -0
  266. graphcore/registry/tests/test_import_package.py +87 -0
  267. graphcore/registry/tests/test_principal_flag.py +67 -0
  268. graphcore/registry/tests/test_strategy_directory.py +29 -0
  269. graphcore/routes/__init__.py +116 -0
  270. graphcore/routes/tests/__init__.py +0 -0
  271. graphcore/routes/tests/test_routes.py +90 -0
  272. graphcore/runtime.py +243 -0
  273. graphcore/scheduling/__init__.py +0 -0
  274. graphcore/scheduling/beat_scheduler.py +164 -0
  275. graphcore/scheduling/beat_tasks.py +63 -0
  276. graphcore/scheduling/scheduler.py +37 -0
  277. graphcore/scheduling/tests/__init__.py +0 -0
  278. graphcore/scheduling/tests/contract.py +136 -0
  279. graphcore/scheduling/tests/memory.py +42 -0
  280. graphcore/scheduling/tests/test_beat_scheduler.py +87 -0
  281. graphcore/scheduling/tests/test_memory_scheduler.py +15 -0
  282. graphcore/scheduling/tests/test_ticks.py +143 -0
  283. graphcore/tasks.py +9 -0
  284. graphcore/test_settings.py +78 -0
  285. graphcore/testing/__init__.py +0 -0
  286. graphcore/testing/case.py +112 -0
  287. graphcore/testing/runner.py +32 -0
  288. graphcore/testing/settings.py +26 -0
  289. graphcore/testing/tests/__init__.py +0 -0
  290. graphcore/testing/tests/agent_view_fixture.py +19 -0
  291. graphcore/testing/tests/test_case_and_runner.py +219 -0
  292. graphcore/testing/tests/test_settings_for_apps.py +50 -0
  293. graphcore/tests/__init__.py +0 -0
  294. graphcore/tests/ids.py +14 -0
  295. graphcore/tests/public_api_manifest.py +102 -0
  296. graphcore/tests/runs.py +7 -0
  297. graphcore/tests/test_app_discovery.py +90 -0
  298. graphcore/tests/test_composition_boundaries.py +231 -0
  299. graphcore/tests/test_docs_discovery.py +108 -0
  300. graphcore/tests/test_no_print.py +70 -0
  301. graphcore/tests/test_packaging.py +64 -0
  302. graphcore/tests/test_public_api_boundaries.py +229 -0
  303. graphcore/tests/test_public_api_contract.py +62 -0
  304. graphcore/tests/test_public_api_docs.py +28 -0
  305. graphcore/tests/test_runtime.py +42 -0
  306. graphcore/tests/test_shared_type_boundaries.py +128 -0
  307. graphcore/tests/test_shared_types.py +144 -0
  308. graphcore/tests/test_test_settings.py +45 -0
  309. graphcore/transport/__init__.py +0 -0
  310. graphcore/transport/agent_asgi.py +68 -0
  311. graphcore/transport/agent_client.py +85 -0
  312. graphcore/transport/channel_layer.py +68 -0
  313. graphcore/transport/consumers.py +507 -0
  314. graphcore/transport/routing.py +6 -0
  315. graphcore/transport/tests/__init__.py +0 -0
  316. graphcore/transport/tests/test_agent_client.py +31 -0
  317. graphcore/transport/tests/test_api_views.py +733 -0
  318. graphcore/transport/tests/test_channel_layer.py +96 -0
  319. graphcore/transport/tests/test_consumers.py +963 -0
  320. graphcore/transport/tests/test_resource_metadata.py +67 -0
  321. graphcore/transport/urls.py +29 -0
  322. graphcore/transport/views.py +358 -0
  323. graphcore/types/__init__.py +4 -0
  324. graphcore/types/access.py +114 -0
  325. graphcore/types/api.py +76 -0
  326. graphcore/types/entities.py +100 -0
  327. graphcore/types/entity_id.py +85 -0
  328. graphcore/types/execution.py +41 -0
  329. graphcore/types/identity.py +20 -0
  330. graphcore/types/onboarding.py +20 -0
  331. graphcore/types/query.py +116 -0
  332. graphcore/types/schedules.py +91 -0
  333. graphcore/types/strategy.py +73 -0
  334. graphcore/types/tests/__init__.py +0 -0
  335. graphcore/types/tests/test_entity_id.py +50 -0
  336. graphcore/urls.py +5 -0
  337. graphcore_kernel-0.1.0.dist-info/METADATA +94 -0
  338. graphcore_kernel-0.1.0.dist-info/RECORD +343 -0
  339. graphcore_kernel-0.1.0.dist-info/WHEEL +5 -0
  340. graphcore_kernel-0.1.0.dist-info/entry_points.txt +2 -0
  341. graphcore_kernel-0.1.0.dist-info/licenses/LICENSE +202 -0
  342. graphcore_kernel-0.1.0.dist-info/licenses/NOTICE +2 -0
  343. graphcore_kernel-0.1.0.dist-info/top_level.txt +1 -0
@@ -0,0 +1,100 @@
1
+ """Entity read criteria and results."""
2
+ from __future__ import annotations
3
+
4
+ import hashlib
5
+ import json
6
+ from dataclasses import dataclass
7
+ from typing import TYPE_CHECKING, Generic, Literal, Optional, Protocol, TypeVar, Union
8
+
9
+ from graphcore.errors import InvalidRequest
10
+
11
+ if TYPE_CHECKING:
12
+ from graphcore.types.query import Predicate
13
+
14
+ TombstoneCause = Literal['forbidden', 'missing', 'unreachable', 'undelegated', 'deleted']
15
+
16
+
17
+ class ClientSerializable(Protocol):
18
+ """Structural contract every `EntityResult` member satisfies. `Entity`
19
+ and `Tombstone` share no base class, but transports (see
20
+ `transport/consumers.py`'s `handle_entity_subscriptions`) read a mixed
21
+ `Entity | Tombstone` collection through `.to_client()` uniformly - this
22
+ is what a type checker verifies that against."""
23
+
24
+ def to_client(self) -> dict: ...
25
+
26
+
27
+ def client_view(result: ClientSerializable) -> dict:
28
+ """What every transport sends for an entity or tombstone: `to_client()`
29
+ plus its `etag`, which a client echoes back on resync."""
30
+ view = result.to_client()
31
+ return {**view, 'etag': view_etag(view)}
32
+
33
+
34
+ def view_etag(view: dict) -> str:
35
+ """An opaque hash of a client view. Covers every field, including
36
+ projections that change without a version bump."""
37
+ canonical = json.dumps(view, sort_keys=True, separators=(',', ':'), default=str)
38
+ return hashlib.blake2b(canonical.encode(), digest_size=8).hexdigest()
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class Tombstone:
43
+ """Uniform absence/denial result for reads."""
44
+
45
+ entity_id: str
46
+ cause: TombstoneCause
47
+
48
+ def to_dict(self) -> dict:
49
+ if self.cause == 'deleted':
50
+ # Wire shape the frontend keys off (`store.ts`'s `deleted === true`) -
51
+ # no `forbidden`/`cause` keys here.
52
+ return {'id': self.entity_id, 'entity_id': self.entity_id, 'deleted': True}
53
+ if self.cause == 'forbidden':
54
+ return {
55
+ 'id': self.entity_id,
56
+ 'entity_id': self.entity_id,
57
+ 'forbidden': True,
58
+ }
59
+ return {
60
+ 'id': self.entity_id,
61
+ 'entity_id': self.entity_id,
62
+ 'forbidden': True if self.cause == 'forbidden' else False,
63
+ 'cause': self.cause,
64
+ }
65
+
66
+ def to_client(self) -> dict:
67
+ """Matches Entity's to_client()/to_dict() split - satisfies
68
+ `ClientSerializable` so transports can call `.to_client()`
69
+ uniformly on `Entity | Tombstone` results."""
70
+ return self.to_dict()
71
+
72
+
73
+ T = TypeVar('T', bound=ClientSerializable)
74
+ EntityResult = Union[T, Tombstone]
75
+
76
+
77
+ @dataclass(frozen=True)
78
+ class EntityPage(Generic[T]):
79
+ """One page of entities; next_cursor is the last ID when more remain."""
80
+
81
+ entities: list[T]
82
+ next_cursor: Optional[str]
83
+
84
+
85
+ @dataclass(frozen=True)
86
+ class EntityFilter:
87
+ type_ids: frozenset[str]
88
+ parent_id: Optional[str] = None
89
+ where: Optional['Predicate'] = None
90
+ """An additional predicate narrowing the result, e.g. a typed app
91
+ column. Conjoined with `type_ids`/`parent_id` and the access predicate -
92
+ never applied as a separate post-filter."""
93
+ granted_to_me: bool = False
94
+ """Only entities the caller holds a grant on, directly or through a
95
+ group they belong to; grants to `PUBLIC` do not count. Resolved by
96
+ `EntityService.list_entities`, since it depends on the caller."""
97
+
98
+ def __post_init__(self) -> None:
99
+ if not self.type_ids:
100
+ raise InvalidRequest('type_ids cannot be empty')
@@ -0,0 +1,85 @@
1
+ """The entity identifier: `gc://<backend_id>/<local_id>`.
2
+
3
+ One form everywhere above the entity repository (see
4
+ `docs/ENTITY_REFERENCE_TDD.md`, Entity identifier) - a bare local id is not
5
+ an identifier anywhere in the kernel, on the wire, or in entity data. The
6
+ backend segment names the deployment that minted the entity; only
7
+ `EntityService` reads it.
8
+
9
+ Both segments are fixed-length lowercase Crockford base32: 10 characters
10
+ (50 bits) for a backend, 12 (60 bits) for an entity. Uniqueness is enforced
11
+ where it matters rather than bought with length - the store's primary key
12
+ for entities, the peer table for backends.
13
+ """
14
+ from __future__ import annotations
15
+
16
+ import hashlib
17
+ import re
18
+ import secrets
19
+
20
+ from graphcore.errors import InvalidRequest
21
+
22
+ PREFIX = 'gc://'
23
+ ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz'
24
+ BACKEND_ID_LENGTH = 10
25
+ LOCAL_ID_LENGTH = 12
26
+ _CHAR = '[0-9a-hjkmnp-tv-z]'
27
+ # The trailing guard keeps a scan from clipping a longer run into a false
28
+ # identifier, so the scan and `is_entity_id` agree on what an id is.
29
+ ENTITY_ID_RE = re.compile(
30
+ rf'{PREFIX}({_CHAR}{{{BACKEND_ID_LENGTH}}})/({_CHAR}{{{LOCAL_ID_LENGTH}}})(?![0-9A-Za-z])'
31
+ )
32
+
33
+
34
+ def _random(length: int) -> str:
35
+ return ''.join(secrets.choice(ALPHABET) for _ in range(length))
36
+
37
+
38
+ def new_backend_id() -> str:
39
+ return _random(BACKEND_ID_LENGTH)
40
+
41
+
42
+ def is_entity_id(value) -> bool:
43
+ return isinstance(value, str) and ENTITY_ID_RE.fullmatch(value) is not None
44
+
45
+
46
+ DEPLOYMENT_LOCAL_ID = '0' * LOCAL_ID_LENGTH
47
+ """The `Deployment`'s local id: well-known, so its identifier follows
48
+ from the backend identity with no lookup, and never minted at random."""
49
+
50
+
51
+ def new_entity_id(backend_id: str) -> str:
52
+ local_id = _random(LOCAL_ID_LENGTH)
53
+ while local_id == DEPLOYMENT_LOCAL_ID:
54
+ local_id = _random(LOCAL_ID_LENGTH)
55
+ return f"{PREFIX}{backend_id}/{local_id}"
56
+
57
+
58
+ def derived_entity_id(backend_id: str, seed: str) -> str:
59
+ """The same identifier for the same `seed`, so a retried attempt mints
60
+ what its request's earlier attempt minted."""
61
+ bits = int.from_bytes(hashlib.sha256(seed.encode()).digest()[:8], 'big') >> 4
62
+ local_id = ''.join(ALPHABET[(bits >> 5 * i) & 31] for i in reversed(range(LOCAL_ID_LENGTH)))
63
+ if local_id == DEPLOYMENT_LOCAL_ID:
64
+ return derived_entity_id(backend_id, seed + '/')
65
+ return f"{PREFIX}{backend_id}/{local_id}"
66
+
67
+
68
+ def deployment_entity_id(backend_id: str) -> str:
69
+ return f"{PREFIX}{backend_id}/{DEPLOYMENT_LOCAL_ID}"
70
+
71
+
72
+ def backend_of(entity_id: str) -> str:
73
+ """The minting deployment's backend identity. `EntityService` is the
74
+ only component that may ask."""
75
+ match = ENTITY_ID_RE.fullmatch(entity_id) if isinstance(entity_id, str) else None
76
+ if match is None:
77
+ raise InvalidRequest(f"{entity_id!r} is not an entity identifier")
78
+ return match.group(1)
79
+
80
+
81
+ def find_entity_ids(text: str) -> list[str]:
82
+ """Every identifier appearing anywhere in `text`, deduplicated and
83
+ sorted - the reference projection over an entity's serialized
84
+ attributes."""
85
+ return sorted({match.group(0) for match in ENTITY_ID_RE.finditer(text)})
@@ -0,0 +1,41 @@
1
+ """What crosses the `Dispatcher` port: one attempt out to an execution
2
+ environment, and its result back. Plain data, never a token or an entity."""
3
+ from __future__ import annotations
4
+
5
+ from dataclasses import asdict, dataclass, fields
6
+ from typing import Literal, Optional
7
+
8
+ AttemptOutcome = Literal['succeeded', 'conflict', 'failed']
9
+
10
+
11
+ @dataclass(frozen=True)
12
+ class ExecutionAttempt:
13
+ request_id: str
14
+ attempt: int
15
+ strategy_name: str
16
+ target_entity_id: Optional[str]
17
+ owner_id: str
18
+ backend_id: str
19
+
20
+ def to_dict(self) -> dict:
21
+ return asdict(self)
22
+
23
+ @classmethod
24
+ def from_dict(cls, data: dict) -> 'ExecutionAttempt':
25
+ return cls(**{f.name: data.get(f.name) for f in fields(cls)})
26
+
27
+
28
+ @dataclass(frozen=True)
29
+ class AttemptResult:
30
+ request_id: str
31
+ attempt: int
32
+ outcome: AttemptOutcome
33
+ ret_val: Optional[dict] = None
34
+ error: Optional[dict] = None # the failing `KernelError.to_dict()`
35
+
36
+ def to_dict(self) -> dict:
37
+ return asdict(self)
38
+
39
+ @classmethod
40
+ def from_dict(cls, data: dict) -> 'AttemptResult':
41
+ return cls(**{f.name: data.get(f.name) for f in fields(cls)})
@@ -0,0 +1,20 @@
1
+ """Identity of a kernel caller.
2
+
3
+ Identity is ``(iss, sub)``; ``principal_entity_id`` is the local mapping of that
4
+ pair. ``token`` is the raw bearer for live in-process token-exchange; Celery
5
+ and Beat reconstruct an identity-only Principal (no token).
6
+ """
7
+ from dataclasses import dataclass
8
+
9
+ PUBLIC = '*'
10
+ """The well-known subject id implicitly included in every authenticated
11
+ principal's subject set."""
12
+
13
+
14
+ @dataclass(frozen=True)
15
+ class Principal:
16
+ principal_entity_id: str
17
+ iss: str | None = None
18
+ sub: str | None = None
19
+ token: str | None = None
20
+ expires_at: int | None = None # the token's ``exp``, when it came from a live bearer
@@ -0,0 +1,20 @@
1
+ """What a principal-created hook returns."""
2
+ from __future__ import annotations
3
+
4
+ from dataclasses import dataclass, field
5
+
6
+ from graphcore.types.strategy import StrategyRequestPayload
7
+
8
+
9
+ @dataclass
10
+ class Onboarding:
11
+ """`groups`, `group_ids`, and `roles` are applied by the kernel itself;
12
+ `requests` run as the new principal under every ordinary check. See
13
+ docs/AUTHORIZATION_TECHNICAL_TDD.md (Identity-based policy, Onboarding)."""
14
+
15
+ groups: list[str] = field(default_factory=list)
16
+ """Group keys to add the principal to."""
17
+ group_ids: list[str] = field(default_factory=list)
18
+ roles: list[str] = field(default_factory=list)
19
+ """Roles registered on `Deployment`, granted to the principal there."""
20
+ requests: list[StrategyRequestPayload] = field(default_factory=list)
@@ -0,0 +1,116 @@
1
+ """Neutral query vocabulary for entity reads.
2
+
3
+ A six-node filter tree over plain field names and literal values - not a
4
+ query language. Every query targets the entity collection; there is no
5
+ projection, no correlation, and no field-to-field comparison. Backends
6
+ compile the tree (see ``persistence/django/compiler.py``); the in-memory
7
+ evaluator in ``persistence/tests/evaluate.py`` pins its semantics.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass
12
+ from typing import Any, Optional
13
+ from uuid import UUID
14
+
15
+ from graphcore.errors import InvalidQuery
16
+ from graphcore.types.entities import EntityFilter
17
+
18
+ LITERAL_TYPES = (str, UUID, bool, int, float, type(None))
19
+ """What may appear as a value in a predicate."""
20
+
21
+
22
+ class Predicate:
23
+ """Base for the six filter nodes. Backends dispatch on the exact node
24
+ type - a subclass nothing has registered a handler for is refused, never
25
+ silently treated as its base."""
26
+
27
+ @classmethod
28
+ def from_filter(cls, criteria: EntityFilter) -> 'Predicate':
29
+ """The caller-facing `EntityFilter` as a predicate. `granted_to_me`
30
+ depends on the caller, so the service resolves it and clears it first."""
31
+ if criteria.granted_to_me:
32
+ raise InvalidQuery('granted_to_me is resolved per caller, not by from_filter')
33
+ predicates: list[Predicate] = [InValues('entity_type_id', criteria.type_ids)]
34
+ if criteria.parent_id is not None:
35
+ predicates.append(Equal('parent_id', criteria.parent_id))
36
+ if criteria.where is not None:
37
+ predicates.append(criteria.where)
38
+ return AllOf(tuple(predicates))
39
+
40
+
41
+ @dataclass(frozen=True)
42
+ class Equal(Predicate):
43
+ """`field` equals `value`; ``Equal(field, None)`` is an explicit null check."""
44
+
45
+ field: str
46
+ value: Any
47
+
48
+
49
+ @dataclass(frozen=True)
50
+ class InValues(Predicate):
51
+ """`field` is one of `values`. An empty set matches nothing."""
52
+
53
+ field: str
54
+ values: frozenset
55
+
56
+ def __post_init__(self) -> None:
57
+ object.__setattr__(self, 'values', frozenset(self.values))
58
+
59
+
60
+ @dataclass(frozen=True)
61
+ class ContainsValue(Predicate):
62
+ """The collection at `field` holds `value`."""
63
+
64
+ field: str
65
+ value: Any
66
+
67
+
68
+ @dataclass(frozen=True)
69
+ class ContainsAny(Predicate):
70
+ """The collection at `field` overlaps `values`. An empty set matches nothing."""
71
+
72
+ field: str
73
+ values: frozenset
74
+
75
+ def __post_init__(self) -> None:
76
+ object.__setattr__(self, 'values', frozenset(self.values))
77
+
78
+
79
+ @dataclass(frozen=True)
80
+ class AllOf(Predicate):
81
+ """Conjunction. Empty is true."""
82
+
83
+ predicates: tuple
84
+
85
+ def __post_init__(self) -> None:
86
+ object.__setattr__(self, 'predicates', tuple(self.predicates))
87
+
88
+
89
+ @dataclass(frozen=True)
90
+ class AnyOf(Predicate):
91
+ """Disjunction. Empty is false."""
92
+
93
+ predicates: tuple
94
+
95
+ def __post_init__(self) -> None:
96
+ object.__setattr__(self, 'predicates', tuple(self.predicates))
97
+
98
+
99
+ @dataclass(frozen=True)
100
+ class PageRequest:
101
+ """Keyset page over ascending `entity_id`."""
102
+
103
+ limit: int
104
+ cursor: Optional[str] = None
105
+
106
+ def __post_init__(self) -> None:
107
+ if not isinstance(self.limit, int) or isinstance(self.limit, bool) or self.limit <= 0:
108
+ raise InvalidQuery(f"page limit must be a positive integer, got {self.limit!r}")
109
+
110
+
111
+ @dataclass(frozen=True)
112
+ class EntityQuery:
113
+ """One page of the entity collection narrowed by `predicate`."""
114
+
115
+ predicate: Predicate
116
+ page: PageRequest
@@ -0,0 +1,91 @@
1
+ """What crosses the `Scheduler` port: a recurring schedule for one
2
+ request template, and its neutral status. No scheduler-specific ids."""
3
+ from __future__ import annotations
4
+
5
+ import re
6
+ from dataclasses import dataclass
7
+ from datetime import datetime
8
+ from typing import Optional
9
+
10
+ from graphcore.errors import InvalidRequest
11
+
12
+ _MONTHS = ('jan', 'feb', 'mar', 'apr', 'may', 'jun', 'jul', 'aug', 'sep', 'oct', 'nov', 'dec')
13
+ _DAYS = ('sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat')
14
+ # (low, high, names) per field; names count from `low`.
15
+ _FIELDS = ((0, 59, ()), (0, 23, ()), (1, 31, ()), (1, 12, _MONTHS), (0, 6, _DAYS))
16
+ _ITEM = re.compile(r'^(\*|(\w+)(?:-(\w+))?)(?:/(\d+))?$')
17
+
18
+
19
+ def _value(token: str, low: int, high: int, names: tuple) -> bool:
20
+ if token.isdigit():
21
+ return low <= int(token) <= high
22
+ return token.lower() in names
23
+
24
+
25
+ def _field_ok(field: str, low: int, high: int, names: tuple) -> bool:
26
+ for item in field.split(','):
27
+ match = _ITEM.match(item)
28
+ if not match:
29
+ return False
30
+ _, start, end, step = match.groups()
31
+ if step is not None and int(step) == 0:
32
+ return False
33
+ if start is not None and not _value(start, low, high, names):
34
+ return False
35
+ if end is not None and not _value(end, low, high, names):
36
+ return False
37
+ return True
38
+
39
+
40
+ def validate_cron(cron) -> str:
41
+ """A five-field cron expression: `minute hour day month weekday`, each
42
+ value within its field's range."""
43
+ parts = cron.split() if isinstance(cron, str) else []
44
+ if len(parts) != 5 or not all(_field_ok(part, *spec) for part, spec in zip(parts, _FIELDS)):
45
+ raise InvalidRequest(
46
+ f"Invalid cron expression: {cron!r}. "
47
+ "Expected format: 'minute hour day_of_month month_of_year day_of_week'"
48
+ )
49
+ return ' '.join(cron.split())
50
+
51
+
52
+ @dataclass(frozen=True)
53
+ class ScheduleSpec:
54
+ """The desired schedule for request template `target_id`, run as
55
+ `principal_id` on a five-field cron (`minute hour day month weekday`)."""
56
+
57
+ target_id: str
58
+ principal_id: str
59
+ cron: str
60
+ enabled: bool = True
61
+
62
+ def __post_init__(self):
63
+ if not self.target_id:
64
+ raise InvalidRequest("A schedule needs a target_id")
65
+ validate_cron(self.cron)
66
+
67
+ @property
68
+ def cron_fields(self) -> tuple[str, str, str, str, str]:
69
+ return tuple(self.cron.split())
70
+
71
+
72
+ @dataclass(frozen=True)
73
+ class ScheduleInfo:
74
+ target_id: str
75
+ cron: str
76
+ enabled: bool
77
+ last_run_at: Optional[datetime] = None
78
+ run_count: int = 0
79
+
80
+
81
+ @dataclass(frozen=True)
82
+ class HeldTask:
83
+ """One task a scheduler fires, as `Scheduler.held` reports it for
84
+ operators. `schedule` is a cron expression or `every <n>s`."""
85
+ name: str
86
+ task: str
87
+ schedule: str
88
+ enabled: bool
89
+ args: tuple = ()
90
+ last_run_at: Optional[datetime] = None
91
+ every_seconds: Optional[int] = None
@@ -0,0 +1,73 @@
1
+ """The un-executed strategy request, and the values every layer uses to
2
+ describe a run.
3
+
4
+ Every layer above the executor - the wire, an entity's `on_create` hook, a
5
+ strategy's `request_constructor` - speaks in `StrategyRequestPayload`. Only
6
+ `new_strategy_request` turns one into a `StrategyRequest`, because only the
7
+ kernel may mint that entity's identifier.
8
+ """
9
+ from __future__ import annotations
10
+
11
+ from dataclasses import dataclass, field, fields
12
+ from typing import ClassVar, Literal, Optional
13
+
14
+ from graphcore.errors import InvalidRequest
15
+
16
+
17
+ RequestStatus = Literal['pending', 'running', 'succeeded', 'failed']
18
+ TERMINAL_STATUSES: frozenset = frozenset({'succeeded', 'failed'})
19
+
20
+
21
+ @dataclass(frozen=True)
22
+ class Workload:
23
+ """The kind of environment a strategy's `apply()` needs. Open: a project
24
+ defines its own next to the strategies that declare it."""
25
+
26
+ name: str
27
+
28
+ IO: ClassVar['Workload']
29
+ CPU: ClassVar['Workload']
30
+
31
+
32
+ Workload.IO = Workload('io')
33
+ Workload.CPU = Workload('cpu')
34
+
35
+
36
+ @dataclass
37
+ class StrategyRequestPayload:
38
+ """Client-safe strategy request. Unknown keys (including entity_id) are dropped."""
39
+
40
+ strategy_name: str
41
+ param_config: dict = field(default_factory=dict)
42
+ target_entity_id: Optional[str] = None
43
+ callbacks: Optional[list] = None
44
+ client_request_id: Optional[str] = None
45
+
46
+ @classmethod
47
+ def from_json(cls, json_data) -> 'StrategyRequestPayload':
48
+ if not isinstance(json_data, dict):
49
+ raise InvalidRequest('strategy payload must be an object')
50
+ known = {f.name for f in fields(cls)}
51
+ kwargs = {k: v for k, v in json_data.items() if k in known}
52
+ if 'strategy_name' not in kwargs:
53
+ raise InvalidRequest('strategy_name is required')
54
+ if not isinstance(kwargs.get('param_config', {}), dict):
55
+ raise InvalidRequest('param_config must be an object')
56
+ callbacks = kwargs.get('callbacks')
57
+ if callbacks is not None:
58
+ if not isinstance(callbacks, list):
59
+ raise InvalidRequest('callbacks must be a list of strategy payloads')
60
+ kwargs['callbacks'] = [cls.from_json(c).to_dict() for c in callbacks]
61
+ return cls(**kwargs)
62
+
63
+ def to_dict(self) -> dict:
64
+ out = {
65
+ 'strategy_name': self.strategy_name,
66
+ 'param_config': dict(self.param_config or {}),
67
+ 'target_entity_id': self.target_entity_id,
68
+ }
69
+ if self.callbacks:
70
+ out['callbacks'] = list(self.callbacks)
71
+ if self.client_request_id is not None:
72
+ out['client_request_id'] = self.client_request_id
73
+ return out
File without changes
@@ -0,0 +1,50 @@
1
+ from django.test import SimpleTestCase
2
+
3
+ from graphcore.errors import InvalidRequest
4
+ from graphcore.types.entity_id import (
5
+ ENTITY_ID_RE, backend_of, find_entity_ids, is_entity_id, new_entity_id,
6
+ )
7
+
8
+ BACKEND = '0000000001'
9
+ OTHER = '1111111111'
10
+
11
+
12
+ class EntityIdTests(SimpleTestCase):
13
+ def test_a_minted_id_round_trips(self):
14
+ entity_id = new_entity_id(BACKEND)
15
+
16
+ self.assertTrue(is_entity_id(entity_id))
17
+ self.assertIsNotNone(ENTITY_ID_RE.fullmatch(entity_id))
18
+ self.assertEqual(backend_of(entity_id), BACKEND)
19
+
20
+ def test_a_bare_local_id_is_not_an_identifier(self):
21
+ bare = new_entity_id(BACKEND).rsplit('/', 1)[1]
22
+
23
+ self.assertFalse(is_entity_id(bare))
24
+ with self.assertRaises(InvalidRequest):
25
+ backend_of(bare)
26
+
27
+ def test_malformed_segments_are_not_an_identifier(self):
28
+ local = new_entity_id(BACKEND).rsplit('/', 1)[1]
29
+ for value in ('gc://x/y', f'gc://{BACKEND}/not-an-id', f'{BACKEND}/{local}',
30
+ f'http://{BACKEND}/{local}', f'gc://{BACKEND}/{local}0',
31
+ f'gc://{BACKEND}/{local.upper()}', f'gc://{BACKEND}/{local[:-1]}i',
32
+ f'gc://6279e06c-316b-40c3-b9c3-d62c0f817c0e/{local}', None, 42):
33
+ with self.subTest(value=value):
34
+ self.assertFalse(is_entity_id(value))
35
+
36
+ def test_find_entity_ids_scans_serialized_data(self):
37
+ import json
38
+
39
+ first, second = new_entity_id(BACKEND), new_entity_id(OTHER)
40
+ payload = json.dumps({
41
+ 'items': [first, {'nested': second}],
42
+ 'note': f'see {first} for details',
43
+ 'near_miss': 'gc://not-a-backend/nope',
44
+ })
45
+
46
+ self.assertEqual(find_entity_ids(payload), sorted({first, second}))
47
+
48
+ def test_find_entity_ids_on_text_without_identifiers(self):
49
+ self.assertEqual(find_entity_ids('nothing here'), [])
50
+
graphcore/urls.py ADDED
@@ -0,0 +1,5 @@
1
+ """Framework HTTP API. Deployments mount this with ``path('graphcore/', include('graphcore.urls'))``."""
2
+
3
+ from graphcore.transport.urls import urlpatterns # noqa: F401
4
+
5
+ __all__ = ['urlpatterns']