ifdd-be-core 26.10.2__tar.gz

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 (65) hide show
  1. ifdd_be_core-26.10.2/LICENSE +29 -0
  2. ifdd_be_core-26.10.2/PKG-INFO +539 -0
  3. ifdd_be_core-26.10.2/README.md +505 -0
  4. ifdd_be_core-26.10.2/pyproject.toml +59 -0
  5. ifdd_be_core-26.10.2/setup.cfg +4 -0
  6. ifdd_be_core-26.10.2/src/ifdd/be/core/__init__.py +13 -0
  7. ifdd_be_core-26.10.2/src/ifdd/be/core/app.py +134 -0
  8. ifdd_be_core-26.10.2/src/ifdd/be/core/auth/__init__.py +21 -0
  9. ifdd_be_core-26.10.2/src/ifdd/be/core/auth/oidc.py +273 -0
  10. ifdd_be_core-26.10.2/src/ifdd/be/core/cache_meta.py +160 -0
  11. ifdd_be_core-26.10.2/src/ifdd/be/core/config.py +184 -0
  12. ifdd_be_core-26.10.2/src/ifdd/be/core/contexts.py +192 -0
  13. ifdd_be_core-26.10.2/src/ifdd/be/core/db/__init__.py +12 -0
  14. ifdd_be_core-26.10.2/src/ifdd/be/core/db/base.py +10 -0
  15. ifdd_be_core-26.10.2/src/ifdd/be/core/db/session.py +163 -0
  16. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/assets.json +34 -0
  17. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/ifdd/docs.css +6 -0
  18. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/ifdd/swagger-init.js +52 -0
  19. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/redoc/LICENSE +22 -0
  20. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/redoc/redoc.standalone.js +1851 -0
  21. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/redoc/redoc.standalone.js.LICENSE.txt +102 -0
  22. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/LICENSE +202 -0
  23. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/NOTICE +2 -0
  24. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/oauth2-redirect.js +1 -0
  25. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/swagger-ui-bundle.js +2 -0
  26. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/swagger-ui-bundle.js.LICENSE.txt +129 -0
  27. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/swagger-ui.css +3 -0
  28. ifdd_be_core-26.10.2/src/ifdd/be/core/docs_ui.py +194 -0
  29. ifdd_be_core-26.10.2/src/ifdd/be/core/graph.py +124 -0
  30. ifdd_be_core-26.10.2/src/ifdd/be/core/helper.py +20 -0
  31. ifdd_be_core-26.10.2/src/ifdd/be/core/jsonld.py +65 -0
  32. ifdd_be_core-26.10.2/src/ifdd/be/core/logging.py +42 -0
  33. ifdd_be_core-26.10.2/src/ifdd/be/core/models.py +175 -0
  34. ifdd_be_core-26.10.2/src/ifdd/be/core/openapi.py +417 -0
  35. ifdd_be_core-26.10.2/src/ifdd/be/core/presentation.py +62 -0
  36. ifdd_be_core-26.10.2/src/ifdd/be/core/repository.py +308 -0
  37. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/__init__.py +17 -0
  38. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/aspects.py +162 -0
  39. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/graph_data.py +99 -0
  40. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/node_types.py +81 -0
  41. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/nodes.py +363 -0
  42. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/params.py +123 -0
  43. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/scopes.py +81 -0
  44. ifdd_be_core-26.10.2/src/ifdd/be/core/routers/versions.py +107 -0
  45. ifdd_be_core-26.10.2/src/ifdd/be/core/schemas.py +93 -0
  46. ifdd_be_core-26.10.2/src/ifdd/be/core/temporal.py +200 -0
  47. ifdd_be_core-26.10.2/src/ifdd/be/core/tools/__init__.py +1 -0
  48. ifdd_be_core-26.10.2/src/ifdd/be/core/tools/schema.py +108 -0
  49. ifdd_be_core-26.10.2/src/ifdd/be/core/version.py +30 -0
  50. ifdd_be_core-26.10.2/src/ifdd/be/core/writes.py +242 -0
  51. ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/PKG-INFO +539 -0
  52. ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/SOURCES.txt +63 -0
  53. ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/dependency_links.txt +1 -0
  54. ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/entry_points.txt +3 -0
  55. ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/requires.txt +25 -0
  56. ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/top_level.txt +1 -0
  57. ifdd_be_core-26.10.2/tests/test_app.py +58 -0
  58. ifdd_be_core-26.10.2/tests/test_auth.py +192 -0
  59. ifdd_be_core-26.10.2/tests/test_cache_meta.py +142 -0
  60. ifdd_be_core-26.10.2/tests/test_contexts.py +111 -0
  61. ifdd_be_core-26.10.2/tests/test_docs.py +258 -0
  62. ifdd_be_core-26.10.2/tests/test_docs_assets.py +49 -0
  63. ifdd_be_core-26.10.2/tests/test_jsonld.py +110 -0
  64. ifdd_be_core-26.10.2/tests/test_temporal.py +303 -0
  65. ifdd_be_core-26.10.2/tests/test_version.py +24 -0
@@ -0,0 +1,29 @@
1
+ BSD 3-Clause License
2
+
3
+ Copyright (c) 2026, Markus Leist
4
+ All rights reserved.
5
+
6
+ Redistribution and use in source and binary forms, with or without
7
+ modification, are permitted provided that the following conditions are met:
8
+
9
+ 1. Redistributions of source code must retain the above copyright notice, this
10
+ list of conditions and the following disclaimer.
11
+
12
+ 2. Redistributions in binary form must reproduce the above copyright notice,
13
+ this list of conditions and the following disclaimer in the documentation
14
+ and/or other materials provided with the distribution.
15
+
16
+ 3. Neither the name of the copyright holder nor the names of its
17
+ contributors may be used to endorse or promote products derived from
18
+ this software without specific prior written permission.
19
+
20
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
21
+ AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22
+ IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
23
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
24
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
26
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
27
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
28
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
29
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
@@ -0,0 +1,539 @@
1
+ Metadata-Version: 2.4
2
+ Name: ifdd-be-core
3
+ Version: 26.10.2
4
+ Summary: Shared runtime for IFDD JSON-LD micro services
5
+ License-Expression: BSD-3-Clause
6
+ Requires-Python: >=3.11
7
+ Description-Content-Type: text/markdown
8
+ License-File: LICENSE
9
+ Requires-Dist: fastapi[all]~=0.142.2
10
+ Requires-Dist: uvicorn[standard]~=0.54.0
11
+ Requires-Dist: slowapi~=0.1.10
12
+ Requires-Dist: SQLAlchemy~=2.1.3
13
+ Requires-Dist: greenlet~=3.5.6
14
+ Requires-Dist: psycopg[binary]~=3.3.6
15
+ Requires-Dist: pydantic~=2.13.5
16
+ Requires-Dist: pydantic-settings~=2.15.0
17
+ Requires-Dist: pyld~=3.3.0
18
+ Requires-Dist: rdflib~=7.6.0
19
+ Requires-Dist: requests~=2.34.2
20
+ Requires-Dist: requests-cache~=1.3.3
21
+ Requires-Dist: cachetools~=7.2.1
22
+ Requires-Dist: Authlib~=1.8.0
23
+ Requires-Dist: PyJWT~=2.15.1
24
+ Requires-Dist: PyYAML~=6.0.3
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest~=9.1.1; extra == "dev"
27
+ Requires-Dist: pytest-asyncio~=1.4.0; extra == "dev"
28
+ Requires-Dist: pytest-cov; extra == "dev"
29
+ Requires-Dist: httpx2; extra == "dev"
30
+ Requires-Dist: black; extra == "dev"
31
+ Requires-Dist: isort; extra == "dev"
32
+ Requires-Dist: flake8; extra == "dev"
33
+ Dynamic: license-file
34
+
35
+ # ifdd-be-core
36
+
37
+ GitHub: `ifdd-de/be-core` — the shared runtime used by services generated from
38
+ the `ifdd-de/be` template.
39
+
40
+ Shared runtime for IFDD JSON-LD micro services. This package holds everything
41
+ that is identical across generated service instances: the bitemporal data
42
+ model and its queries, JSON-LD processing, OIDC authentication, the generic routers and the
43
+ FastAPI application factory.
44
+
45
+ It contains no template placeholders and is developed, tested and released like
46
+ any other Python library.
47
+
48
+ ## Usage from a generated instance
49
+
50
+ ```python
51
+ from ifdd.be.core import create_app
52
+ from app.settings import Settings
53
+
54
+ app = create_app(Settings())
55
+ ```
56
+
57
+ ## Configuration
58
+
59
+ All configuration is read from the environment (and from `.env`). The instance
60
+ may subclass `ifdd.be.core.CoreSettings` to add its own fields.
61
+
62
+ Two settings replace what used to be hard-coded in the template:
63
+
64
+ | Setting | Purpose |
65
+ |---|---|
66
+ | `IFDD_ASPECTS` | JSON object mapping REST path segment to aspect name |
67
+ | `IFDD_GRAPH_PREDICATES` | JSON object mapping predicate to traversal depth |
68
+
69
+ Context access (see [Contexts and access](#contexts-and-access)):
70
+
71
+ | Setting | Purpose |
72
+ |---|---|
73
+ | `IFDD_SCHEMA_URL` | contexts are accepted only from below this URL |
74
+ | `IFDD_CONTEXT_ROOT` | context pattern of the development user (`IFDD_BE_AUTH_ENABLED=false`), default `ifdd.de` |
75
+
76
+ Example:
77
+
78
+ ```
79
+ IFDD_ASPECTS={"products":"product","functions":"function"}
80
+ ```
81
+
82
+ Version and title:
83
+
84
+ | Setting | Purpose |
85
+ |---|---|
86
+ | `IFDD_BE_VERSION` | version of the instance, shown by `/version`, `/prot_version` and the OpenAPI document; default: the version of this package |
87
+ | `API_TITLE`, `API_SUMMARY` | title and summary of the OpenAPI document |
88
+
89
+ `ifdd.be.core.__version__` is read from the package metadata, so it always
90
+ equals the version in `pyproject.toml`. `API_VERSION` no longer exists; a
91
+ value left in an old `.env` is ignored.
92
+
93
+ Token cache:
94
+
95
+ | Setting | Purpose |
96
+ |---|---|
97
+ | `IFDD_TOKEN_CACHE_SIZE` | number of checked tokens kept, default 1000 |
98
+ | `IFDD_TOKEN_CACHE_TTL` | seconds a checked token is kept, default 300 |
99
+
100
+ A cache hit does not check the token's expiry again, so a token that expires
101
+ while it is cached is still accepted until its entry ends, at most
102
+ `IFDD_TOKEN_CACHE_TTL` seconds. This is accepted; a smaller value shortens the
103
+ window at the cost of more signature checks.
104
+
105
+ ## API documentation
106
+
107
+ The backend serves its documentation itself:
108
+
109
+ | Path | Content |
110
+ |---|---|
111
+ | `/docs` | Swagger UI |
112
+ | `/redoc` | ReDoc |
113
+ | `/openapi.json` | the OpenAPI 3.1 document |
114
+ | `/docs/oauth2-redirect` | where the realm returns the browser after "Authorize" |
115
+ | `/docs/assets/…` | the static files of both pages |
116
+
117
+ The pages and the document are open: they describe the API and give no
118
+ access to data. Every data endpoint still needs an access token and its
119
+ roles. The document explains the concepts (contexts, access, time, cache
120
+ metadata), describes every endpoint with the role it needs and the errors it
121
+ answers, and carries examples from the example domains `grid` and `ops`.
122
+
123
+ FastAPI's own pages are switched off: they start Swagger UI with an inline
124
+ script and load it from a CDN, which the proxy's Content-Security-Policy
125
+ forbids (the page stayed empty). The pages of `ifdd.be.core.docs_ui` contain
126
+ no inline script or style; Swagger UI is started by
127
+ `docs_assets/ifdd/swagger-init.js`, which reads the values of the instance
128
+ from `data-*` attributes. A CSP for the backend host needs:
129
+
130
+ ```
131
+ default-src 'self'; frame-ancestors 'none'; img-src 'self' data:;
132
+ style-src 'self' 'unsafe-inline'; script-src 'self';
133
+ connect-src 'self' <realm origin>; worker-src 'self' blob:
134
+ ```
135
+
136
+ `connect-src` names the origin of the realm (for example `https://id`):
137
+ "Authorize" fetches the token there. `worker-src … blob:` is for the search
138
+ of ReDoc, which runs in a worker. `style-src 'unsafe-inline'` is for ReDoc,
139
+ which inserts its styles at run time (Swagger UI works without it). ReDoc
140
+ also tries to load its
141
+ logo from `cdn.redoc.ly`; the policy blocks it, which only leaves the logo
142
+ out.
143
+
144
+ **"Authorize"** in Swagger UI signs in at the realm with the authorization
145
+ code flow and PKCE, as the public client `IFDD_OIDC_JWKS_AUDIENCE`, which must
146
+ allow the redirect URI `<backend URL>/docs/oauth2-redirect` exactly. Swagger UI
147
+ keeps the token in the browser's `localStorage` of the backend host
148
+ (`persistAuthorization`), so a reload keeps the login until the token
149
+ expires. Alternatively, paste an access token obtained elsewhere (for
150
+ example with client credentials) under `BearerToken`. With
151
+ `IFDD_BE_AUTH_ENABLED=false` there is no login; every request acts as the
152
+ development user.
153
+
154
+ Meta endpoints:
155
+
156
+ | Endpoint | Token | Answer |
157
+ |---|---|---|
158
+ | `/version` | none | `{"version": IFDD_BE_VERSION}`; for health checks and tests through the proxy |
159
+ | `/prot_version` | role `IFDD_ROLE_PUBLIC` | `{"version": "<IFDD_BE_VERSION>_prot"}`; ifdd-ui shows it on its dashboard, keep it stable |
160
+ | `/whoami` | any valid token | `preferred_username`, `client_roles` (without a dot) and `context_patterns` (with a dot, lower-case), both sorted: what the backend reads from the token |
161
+
162
+ ## Third-party files
163
+
164
+ `src/ifdd/be/core/docs_assets/` holds unchanged copies of these npm
165
+ packages; `docs_assets/assets.json` names version, tarball, npm integrity and
166
+ the SHA-256 of every file, and `tests/test_docs_assets.py` checks them.
167
+
168
+ | Package | Version | License | Files |
169
+ |---|---|---|---|
170
+ | `swagger-ui-dist` | 5.33.0 | Apache-2.0 (with `NOTICE`) | `swagger-ui-bundle.js`, `swagger-ui.css`, `oauth2-redirect.js` |
171
+ | `redoc` | 2.5.4 | MIT | `bundles/redoc.standalone.js` |
172
+
173
+ The license texts (`LICENSE`, `NOTICE`, and the `*.LICENSE.txt` of the
174
+ bundles, which list the bundled dependencies) are shipped next to the files
175
+ and in the wheel. The bundles contain code under further licenses, mainly
176
+ MIT, also BSD-3-Clause (`ieee754`) and DOMPurify ("Apache license 2.0 and
177
+ Mozilla Public License 2.0", see `swagger-ui-bundle.js.LICENSE.txt`).
178
+ `docs_assets/ifdd/` is part of this package (BSD-3-Clause).
179
+
180
+ To update, for each package:
181
+
182
+ ```bash
183
+ npm pack swagger-ui-dist@<version> # or redoc@<version>
184
+ tar -xzf swagger-ui-dist-<version>.tgz # unpacks to package/
185
+ cp package/{swagger-ui-bundle.js,swagger-ui.css,oauth2-redirect.js,LICENSE,NOTICE,swagger-ui-bundle.js.LICENSE.txt} \
186
+ src/ifdd/be/core/docs_assets/swagger-ui/
187
+ # redoc: package/LICENSE, package/bundles/redoc.standalone.js{,.LICENSE.txt} -> docs_assets/redoc/
188
+ ```
189
+
190
+ then enter version, tarball, integrity (`npm view <package>@<version>
191
+ dist.integrity`) and the new SHA-256 values (`sha256sum`) in `assets.json`,
192
+ and check the pages in a browser behind the proxy. Prefer a version that has
193
+ been published for a while over one from the same week.
194
+
195
+ ## Documentation (`docs/`)
196
+
197
+ `docs/en` and `docs/de` are Sphinx sources (MyST Markdown) for a
198
+ documentation project that covers all IFDD services: an introduction, the
199
+ HTTP API (`sphinxcontrib-openapi`, from an `openapi.json` exported at build
200
+ time, see `docs/en/api-http.md`) and the Python API (`sphinx.ext.autodoc`
201
+ with `sphinx.ext.napoleon`, from the docstrings). Labels start with
202
+ `ifdd-be-core-`. The project that copies them needs those extensions and this
203
+ package installed. `tests/check_docs.py` checks that both languages have the
204
+ same files, labels and headings and that each builds without warnings
205
+ (configuration `tests/docs/conf.py`, versions `tests/docs/requirements.txt`).
206
+
207
+ ## Storage model
208
+
209
+ Every document is stored as **versions** of the pair (`@id`, `@context`), one
210
+ row each in the table `nodes`. A version has two half-open periods
211
+ `[start, end)`:
212
+
213
+ | Period | Column | Set by | Meaning |
214
+ |---|---|---|---|
215
+ | valid time | `valid_period` | the source, via `c_validNotBefore` / `c_validNotAfter`; default `[now, infinity)` | when the version holds in the real world |
216
+ | system time | `sys_period` | the backend | when the backend knew the version; open-ended = current |
217
+
218
+ ### Cache metadata (`c_*`)
219
+
220
+ Six terms with the prefix `c_` are defined by every schema. They are never
221
+ stored inside the document (neither `json` nor `expanded`); their values are
222
+ columns of the row, and every read adds them again.
223
+
224
+ | Term | Origin | Column |
225
+ |---|---|---|
226
+ | `c_created`, `c_modified` | source, kept as sent | `src_created`, `src_modified` |
227
+ | `c_validNotBefore`, `c_validNotAfter` | source | bounds of `valid_period` |
228
+ | `c_cacheCreated` | backend: first time the document was stored | `cache_created` |
229
+ | `c_cacheUpdated` | backend: when a write last stored or confirmed this version | `cache_updated` |
230
+
231
+ Backend values sent by a client are discarded. Any other `c_*` term, or a
232
+ `c_*` term written as an IRI (`"product:c_created"`), is answered with 422.
233
+ Values without a time zone are read as UTC; all values are answered in UTC,
234
+ whatever time zone the database session uses. Lists add the terms as plain
235
+ terms; a single GET adds them per context in that context's namespace
236
+ (`product:c_cacheUpdated` next to `location:c_cacheUpdated`).
237
+
238
+ ### Writing
239
+
240
+ `PUT /{segment}/{id}` writes a document for the valid time it names. It
241
+ replaces only that part of the valid time, as SQL:2011 `FOR PORTION OF`:
242
+
243
+ ```
244
+ stored: A [2020 ---------------------------------->
245
+ PUT B for [2027 --> 2028)
246
+ stored: A [2020 -> 2027) B [2027 -> 2028) A [2028 ->
247
+ ```
248
+
249
+ - The versions overlapping the written period end in system time; the parts
250
+ of them outside it are recorded again unchanged.
251
+ - If the content (expanded form without `c_*`, plus `c_created` and
252
+ `c_modified`) is already known for the whole period, no version is written
253
+ (`200 No changes detected`). Adjacent versions with the same content count
254
+ together. The versions the write repeated are confirmed: their
255
+ `c_cacheUpdated` becomes the time of the write, in place, with or without
256
+ versioning. Versions outside the written period are not touched.
257
+ - A PUT never shortens a version: to end the validity at a time, `DELETE`
258
+ from that time on.
259
+ - Without valid time, a write applies from now on and therefore also replaces
260
+ versions planned for later.
261
+
262
+ `PATCH` takes the version valid at the start of the named valid time
263
+ (default: now), replaces the fields sent (top level) and writes the result
264
+ like a PUT, confirmation included; without such a version it answers 404. `DELETE` ends the document
265
+ in every context for the valid time in its optional body
266
+ (`c_validNotBefore`, `c_validNotAfter`; default: from now on), and only if
267
+ the client may write every one of them (403 otherwise, nothing is ended in
268
+ part). `DELETE …?context=<context URL>` ends that one context only, e.g. a
269
+ domain source withdrawing its values.
270
+
271
+ Every write checks that the path of the `@id` is the request path (the host
272
+ is not compared) and that `aspect` belongs to the first path segment
273
+ (`IFDD_ASPECTS`); otherwise 422. The context must qualify (see
274
+ [Contexts and access](#contexts-and-access)); otherwise 422, or 403 for a
275
+ domain context without a matching pattern.
276
+
277
+ Writes of one document are serialised with a transaction-level advisory lock
278
+ and use the database clock, so all workers agree on "now". An exclusion
279
+ constraint (`btree_gist`) refuses two versions of a document that overlap in
280
+ both times; should it ever fire, the answer is 409.
281
+
282
+ ### Reading
283
+
284
+ All read endpoints (`/{segment}`, `/{segment}/{id}`, `/nodes/`, `/types`,
285
+ `/scopes`, `/graph_data`) take one optional instant `at` (ISO 8601, default
286
+ now). They return what the backend knows now and is valid at that instant,
287
+ so a document appears at most once per context. Planned versions are seen
288
+ with an `at` in the future. Queries of the system time (history) are not
289
+ offered yet.
290
+
291
+ Every read sees the base and aspect contexts and the domain contexts the
292
+ client has a pattern for. Lists, `/types` and `/scopes` leave the others out
293
+ (`X-Total-Count` counts what is visible); a list asked for a foreign domain
294
+ context with `context=` answers 403. A single document leaves out foreign
295
+ domain contexts and answers 403 only if none of its contexts is visible.
296
+ `/graph_data` follows base and aspect contexts only and labels nodes with
297
+ their `objName`.
298
+
299
+ The single document `GET /{segment}/{id}` merges all visible contexts. The
300
+ prefix of each context is its name, and `@context` maps the names to their
301
+ namespaces, so every JSON-LD processor expands the answer again:
302
+
303
+ ```json
304
+ {
305
+ "@context": {"product": "https://type/v1/product/",
306
+ "breaker.grid.example.ifdd.de": "https://type/v1/breaker.grid.example.ifdd.de/"},
307
+ "@id": "https://rest/products/7f5d",
308
+ "product:objName": "Q1",
309
+ "breaker.grid.example.ifdd.de:serialNumber": "SN-1"
310
+ }
311
+ ```
312
+
313
+ Lists sort by `sort` (default `c_cacheUpdated`, order `ASC`). Allowed keys
314
+ are the six `c_*` terms and `objName`, `objType`, `objScope`; each has an
315
+ index, so a sorted page stops after the page. Any other key is answered with
316
+ 422 (the OpenAPI schema lists the keys).
317
+
318
+ ### Versioning switch
319
+
320
+ | `IFDD_VERSIONING` | A write replaces a version by ... | Table holds |
321
+ |---|---|---|
322
+ | `true` (default) | ending it in system time | current versions and their history |
323
+ | `false` | deleting it | current versions only |
324
+
325
+ Valid-time periods are kept either way.
326
+
327
+ ### Read performance
328
+
329
+ Reads only touch current rows, so every read index is partial on
330
+ `upper_inf(sys_period)`: history does not make them larger. Indexes cover the
331
+ single document by path, `@id` lookups, the aspect at an instant (GiST over
332
+ context and valid time), `objType`/`objScope` filters (GIN, `@>`), the
333
+ full-text search (`pg_trgm`) and every sort key (the `c_*` columns and
334
+ expression indexes on `objName`, `objType`, `objScope`). Lists do not
335
+ load the expanded form. A page and its total are two queries: with a window
336
+ count in the page query, PostgreSQL 18 read and sorted every match before the
337
+ LIMIT, about five times slower for 20,000 documents. A page that is not full
338
+ needs no count at all.
339
+
340
+ ## JSON-LD contexts
341
+
342
+ The `@context` URLs of the documents are fetched over HTTP, typically from the
343
+ schema service through the proxy. Each process keeps them in memory for
344
+ `JSONLD_CACHE_EXPIRE_AFTER` seconds (default 120); `JSONLD_LOADER_TIMEOUT`
345
+ (default 10 s) limits each request. An HTTP error status fails the fetch
346
+ instead of being parsed as JSON.
347
+
348
+ A request whose JSON-LD processing fails is answered with
349
+
350
+ - **502** if a document or context could not be fetched; the detail names the
351
+ URL and the cause, e.g. `429 Client Error: Too Many Requests`;
352
+ - **422** for every other JSON-LD error.
353
+
354
+ ## Contexts and access
355
+
356
+ Every row has one `@context` URL. Its last path segment without `.jsonld` is
357
+ the context name; the version in the path does not count. Contexts are
358
+ accepted only from below `IFDD_SCHEMA_URL`, and there are three kinds:
359
+
360
+ | Kind | Names | Read | Write |
361
+ |---|---|---|---|
362
+ | base | `base` | node read role | node write role |
363
+ | aspect | the values of `IFDD_ASPECTS` | node read role | node write role |
364
+ | domain | dotted lower-case names, e.g. `sub1.dom1.ifdd.de` | node read role **and** a matching pattern | node write role **and** a matching pattern |
365
+
366
+ Any other name is refused with 422, so a typo never makes a context readable
367
+ for everyone. Every context must define the six `c_*` terms in one
368
+ namespace that ends with `/` or `#` (JSON-LD 1.1 uses a term as a prefix
369
+ only then); otherwise writes answer 422. The backend finds that namespace by
370
+ expanding the `c_*` terms with the context itself and assumes nothing about
371
+ prefixes.
372
+
373
+ A **context pattern** is a client role of the backend client
374
+ (`resource_access.<audience>.roles`) whose name contains a dot. It matches
375
+ the domain context of the same name and every one below it, at label
376
+ boundaries: `dom1.ifdd.de` matches `sub1.dom1.ifdd.de`, not
377
+ `xdom1.ifdd.de`. Read and write are not given per pattern: the node roles
378
+ apply to every context a client may use. Without a pattern a client sees no
379
+ domain context.
380
+
381
+ | Client pattern | `sub1.dom1.ifdd.de` | `sub2.dom1.ifdd.de` | `sub1.dom2.ifdd.de` |
382
+ |---|---|---|---|
383
+ | `ifdd.de` | yes | yes | yes |
384
+ | `dom1.ifdd.de` | yes | yes | no |
385
+ | `sub1.dom2.ifdd.de` | no | no | yes |
386
+
387
+ The table keeps the name of a domain context in the column `domain` (NULL
388
+ for base and aspects); reads filter on it.
389
+
390
+ ## Maintenance commands
391
+
392
+ ```
393
+ ifdd-be-create-tables # create the extensions, the nodes table and its indexes
394
+ ifdd-be-purge # end the current versions not written for 50 hours
395
+ ```
396
+
397
+ `ifdd-be-create-tables` needs PostgreSQL 13 or later (the extensions
398
+ `btree_gist` and `pg_trgm` are trusted there, so the database owner may
399
+ create them). It creates what is missing and never alters a table; there are
400
+ no migrations. A `nodes` table of 26.10.2 or earlier, or one without the
401
+ `domain` column, is refused with a message: drop it and load the data again.
402
+
403
+ `ifdd-be-purge` ends stale versions in system time (with versioning) or
404
+ deletes them (without). An unchanged PUT or PATCH renews `c_cacheUpdated`,
405
+ so a document its source keeps sending is not purged.
406
+
407
+ ## Tests
408
+
409
+ ```
410
+ pip install -e ".[dev]"
411
+ pytest # unit tests only
412
+ IFDD_TEST_DB_URL=postgresql+psycopg://ifdd:ifdd@localhost:5432/ifdd_test pytest
413
+ ```
414
+
415
+ With `IFDD_TEST_DB_URL` the tests in `tests/db` run against that database;
416
+ they drop and create the `nodes` table. They serve their own JSON-LD contexts
417
+ from `tests/db/contexts` on a local port. `tests/test_temporal.py` describes
418
+ the write semantics as timelines without a database.
419
+
420
+ `benchmarks/read_paths.py` (optional, not part of the suite) fills the test
421
+ database and reports how a read splits into database and JSON-LD time.
422
+
423
+ ## CI
424
+
425
+ | Workflow | Trigger | Does |
426
+ |---|---|---|
427
+ | `test.yml` | push, PR | pytest on Python 3.11-3.14 against a `postgres:18` service container; checks and builds `docs/en` and `docs/de`; builds the distribution and verifies that `ifdd` and `ifdd.be` stay implicit namespace packages and that the wheel carries the documentation assets |
428
+ | `release.yml` | tag `v*` | checks that the tag matches the project version, then publishes to PyPI |
429
+
430
+ Publishing uses PyPI Trusted Publishing, so no API token is stored here. The
431
+ publisher has to be configured once on PyPI for this repository, workflow
432
+ `release.yml` and environment `pypi`.
433
+
434
+ ## Honesty notes
435
+
436
+ Documentation `docs/` (2026-10-13): `tests/check_docs.py` passes (Sphinx
437
+ 9.1.0, myst-parser 5.1.0, sphinxcontrib-mermaid 2.1.1, sphinxcontrib-openapi
438
+ 0.10.0, Python 3.13) with the OpenAPI document exported as in the CI job;
439
+ both languages build with `-W`. The HTTP page shows every endpoint with
440
+ examples; `sphinxcontrib-openapi` stopped with a `KeyError` when the option
441
+ `:request:` was added (a request body given as a `$ref`), so the page does
442
+ without it. autodoc needs the docstring tables to be valid reST: the table
443
+ in `docs_ui` was not and is fixed. The `docs` job passes actionlint 1.7.12;
444
+ it has not run on GitHub.
445
+
446
+ API documentation (2026-10-13): tested on Python 3.14.6 and 3.11.17 with
447
+ FastAPI 0.142.4 against PostgreSQL 18.4 (zonky binaries, see above): 226
448
+ tests each. Counter-check: the 41 new or changed tests in `test_docs.py`,
449
+ `test_docs_assets.py`, `test_version.py`, `test_app.py` and `test_auth.py`
450
+ were run against the previous state; 33 fail there (among them the inline
451
+ script on `/docs`, `/docs/oauth2-redirect` and `/redoc`). Of the other
452
+ eight, five guard unchanged behaviour (`/version`, `/prot_version`, the
453
+ configured aspect routes) and three pass there only because the old pages
454
+ reference no local asset. The wheel check fails for a wheel built from the previous state
455
+ (no `docs_assets`). End to end in headless Chromium (Playwright 1.56.0,
456
+ Chromium build 1194) behind Traefik v3.7.13 with the rendered proxy
457
+ configuration and the Keycloak 26.8.0 distribution with the rendered realm
458
+ (no Docker): Swagger UI renders under the new CSP without violations;
459
+ "Authorize" opens the realm's login, returns through `/docs/oauth2-redirect`
460
+ and fetches the token; "Try it out" sends it (`/whoami`, `/prot_version`,
461
+ `/nodes/`, `/products` answer 200); after a reload the login is still there;
462
+ ReDoc renders and its search works. Counter-checks in the same setup: the
463
+ previous package under the previous CSP refuses the inline script of `/docs`
464
+ (the error seen in a real instance), this package under the previous CSP
465
+ cannot fetch the token (`connect-src`), without `worker-src … blob:` ReDoc's
466
+ search finds nothing, and without `style-src 'unsafe-inline'` ReDoc's styles
467
+ are refused (Swagger UI keeps working). Not checked: the container image,
468
+ other browsers than Chromium, and the CI workflow itself.
469
+
470
+ Known and accepted (2026-10-14): a validated token is kept in the token
471
+ cache for `IFDD_TOKEN_CACHE_TTL` seconds (default 300) by its text, and a
472
+ cache hit does not check the expiry again; a token that expires meanwhile is
473
+ accepted until its cache entry ends (see [Configuration](#configuration)).
474
+ Read in `auth/oidc.py`, not tested.
475
+
476
+ JSON-LD loader and errors (2026-10-05): before, the context cache never took
477
+ effect (PyLD 3.3 creates its requests session when the loader is created, and
478
+ the cache was installed globally afterwards), so every document fetched its
479
+ contexts again; through the proxy this ran into its rate limit (429), and the
480
+ error handler failed on `err.cause`, which PyLD 3.3 does not have (500
481
+ instead of the intended answer). Checked: `tests/test_jsonld.py` (fails
482
+ against the previous code), and with PostgreSQL 16, the Keycloak 26.8.0
483
+ distribution and the ct integration tests: 224 documents loaded with 5 context
484
+ fetches instead of 448. Not checked: the path through the proxy after the
485
+ change, and the image.
486
+
487
+ Dependency update (2026-10-05): fastapi 0.142.2, SQLAlchemy 2.1.3,
488
+ cachetools 7.2.1, PyJWT 2.15.1; the other pins were already current. Resolved
489
+ and tested on Python 3.14 (the backend image now uses python:3.14-slim) as
490
+ well as 3.11-3.13 in CI: the unit tests pass, and the ct integration tests
491
+ (real Keycloak 26.8.0, PostgreSQL 16) pass with the updated packages. The
492
+ FastAPI route test known to fail (see the be template) still fails; the
493
+ version is unchanged (26.10.2).
494
+
495
+ Bitemporal storage (2026-10-06): tested on Python 3.14 and 3.11 against
496
+ PostgreSQL 18.6, built from the `REL_18_STABLE` sources with `btree_gist` and
497
+ `pg_trgm` (no Docker available): 138 tests, of which 73 need the database.
498
+ Counter-checks: ten deliberate faults (no write lock, no idempotency check,
499
+ c_* left in the document, lost remainders, reads ignoring system time, a
500
+ versioning switch without effect, no path check, unescaped search wildcards,
501
+ `c_cacheCreated` overwritten, constraint on one period only) each make tests
502
+ fail; without the write lock the exclusion constraint stops the second
503
+ writer. The planner tests document what PostgreSQL 18 picks for 20,000
504
+ current documents; other versions or statistics may choose differently.
505
+ Measured with `benchmarks/read_paths.py` (2,000 documents, median): GET of a
506
+ single document 1.0 ms database plus 0.5 ms PyLD compaction; a list page of
507
+ 100 documents 5.6 ms database plus 0.7 ms presentation. Not checked: the CI
508
+ workflow itself, the `postgres:18` image (its contrib extensions are assumed
509
+ to be present), the ui and ct against the new API (next round), and the be template
510
+ (not run in this round).
511
+
512
+ Confirmation, sort keys, UTC (2026-10-06, second round): tested on Python
513
+ 3.14 against PostgreSQL 18.4 (zonky binaries from the npm package
514
+ `@embedded-postgres/linux-x64` 18.4.0-beta.17; the sandbox could no longer
515
+ reach the PostgreSQL sources): 149 tests. The 15 new or changed tests fail
516
+ against the previous state. The time zone fault was found by that cluster: it
517
+ runs in Europe/Berlin, and nine tests of the first round failed because the
518
+ API answered in the time zone of the database session.
519
+
520
+ Context access (2026-10-12): tested on Python 3.14 against PostgreSQL 18.4
521
+ (same zonky binaries): 189 tests. Counter-check: the new tests were run
522
+ against the previous state; the unit tests (`tests/test_contexts.py`) and 16
523
+ of 17 new API tests fail there, the remaining one guards unchanged behaviour
524
+ (aspect lists show the aspect context only), and the changed expectation of
525
+ the single document's `@context` fails there too. The planner tests now carry
526
+ the access filter and a tenth of the rows in a domain context; PostgreSQL 18
527
+ still picks the same partial indexes. Dotted client role and group names were
528
+ checked against the Keycloak 26.8.0 distribution: a role
529
+ `grid.example.ifdd.de` reached `resource_access.<client>.roles` of a
530
+ user's access token through a group. That the answer of the single document
531
+ expands again was checked with PyLD 3.3.0 in the tests and, by hand, with
532
+ jsonld.js 8.3.3. Measured with `benchmarks/read_paths.py` (1,000 documents,
533
+ median, previous state against this one in the same sandbox): the JSON-LD
534
+ part of a single GET first grew from 0.6 ms to 1.7 ms, because the namespace
535
+ of each context was found by expansion on every read; it is now kept per
536
+ context URL for `JSONLD_CACHE_EXPIRE_AFTER` seconds, back to 0.6 ms. A list
537
+ page of 100 took 6.5 ms in the database before and 6.9 to 8.3 ms after, within
538
+ the spread of repeated runs. Not checked: the CI workflow, the be template
539
+ image, the ui and ct against this state (later steps of the same round).