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.
- ifdd_be_core-26.10.2/LICENSE +29 -0
- ifdd_be_core-26.10.2/PKG-INFO +539 -0
- ifdd_be_core-26.10.2/README.md +505 -0
- ifdd_be_core-26.10.2/pyproject.toml +59 -0
- ifdd_be_core-26.10.2/setup.cfg +4 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/__init__.py +13 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/app.py +134 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/auth/__init__.py +21 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/auth/oidc.py +273 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/cache_meta.py +160 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/config.py +184 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/contexts.py +192 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/db/__init__.py +12 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/db/base.py +10 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/db/session.py +163 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/assets.json +34 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/ifdd/docs.css +6 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/ifdd/swagger-init.js +52 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/redoc/LICENSE +22 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/redoc/redoc.standalone.js +1851 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/redoc/redoc.standalone.js.LICENSE.txt +102 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/LICENSE +202 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/NOTICE +2 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/oauth2-redirect.js +1 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/swagger-ui-bundle.js +2 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/swagger-ui-bundle.js.LICENSE.txt +129 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_assets/swagger-ui/swagger-ui.css +3 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/docs_ui.py +194 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/graph.py +124 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/helper.py +20 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/jsonld.py +65 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/logging.py +42 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/models.py +175 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/openapi.py +417 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/presentation.py +62 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/repository.py +308 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/__init__.py +17 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/aspects.py +162 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/graph_data.py +99 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/node_types.py +81 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/nodes.py +363 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/params.py +123 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/scopes.py +81 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/routers/versions.py +107 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/schemas.py +93 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/temporal.py +200 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/tools/__init__.py +1 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/tools/schema.py +108 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/version.py +30 -0
- ifdd_be_core-26.10.2/src/ifdd/be/core/writes.py +242 -0
- ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/PKG-INFO +539 -0
- ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/SOURCES.txt +63 -0
- ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/dependency_links.txt +1 -0
- ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/entry_points.txt +3 -0
- ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/requires.txt +25 -0
- ifdd_be_core-26.10.2/src/ifdd_be_core.egg-info/top_level.txt +1 -0
- ifdd_be_core-26.10.2/tests/test_app.py +58 -0
- ifdd_be_core-26.10.2/tests/test_auth.py +192 -0
- ifdd_be_core-26.10.2/tests/test_cache_meta.py +142 -0
- ifdd_be_core-26.10.2/tests/test_contexts.py +111 -0
- ifdd_be_core-26.10.2/tests/test_docs.py +258 -0
- ifdd_be_core-26.10.2/tests/test_docs_assets.py +49 -0
- ifdd_be_core-26.10.2/tests/test_jsonld.py +110 -0
- ifdd_be_core-26.10.2/tests/test_temporal.py +303 -0
- 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).
|