test-data-service 0.1.0__py3-none-any.whl

test_data_service-0.1.0.dist-info/METADATA

@@ -0,0 +1,229 @@
+Metadata-Version: 2.4
+Name: test-data-service
+Version: 0.1.0
+Summary: A disk-backed test data service with a REST API and web interface
+Author-email: Roy de Kleijn <dekleijn.roy@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/testsmith-io/test-data-service
+Project-URL: Documentation, https://github.com/testsmith-io/test-data-service#readme
+Project-URL: Repository, https://github.com/testsmith-io/test-data-service
+Project-URL: Issues, https://github.com/testsmith-io/test-data-service/issues
+Keywords: test-data,rest,api,fastapi,key-value,testing,mock-data
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Classifier: Framework :: FastAPI
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.27
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: black>=23.0; extra == "dev"
+Requires-Dist: flake8>=6.0; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Dynamic: license-file
+
+
+
+## Test Data Service
+
+A working prototype of the above. Data is stored as JSON files on disk
+(one file per namespace), exposed through a REST API and a web interface,
+with optional role-based access control.
+
+### Install & run
+
+```bash
+# from PyPI (once published)
+pip install test-data-service
+
+# start the server (API + web UI) on http://127.0.0.1:8000
+tds serve                       # or: python -m testdataservice serve
+# open http://127.0.0.1:8000 in a browser
+```
+
+From source, for development:
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/tds serve
+```
+
+Packaging/release details (build, `twine`, GitHub Actions publish-on-release)
+are in [CONTRIBUTING.md](CONTRIBUTING.md).
+
+#### Configure with a YAML file
+
+Drop a `tds.yml` (or `tds.yaml`) in your project root and just run `tds serve` —
+no flags needed. Environment variables override the file.
+
+```yaml
+# tds.yml
+data_dir: ./data        # where namespace files + .auth live
+auth: true              # turn on accounts / access control
+host: 127.0.0.1
+port: 8000
+```
+
+### Data model
+
+Each entry is a `key` / `value` pair inside a **namespace**. A value is one
+of four types: `string`, `boolean`, `number`, or `array`. The type is stored
+alongside the value and validated on write.
+
+### REST API
+
+`POST` targets the namespace (collection) with the key **in the body**; `PUT`
+targets a specific entry URI. They are not interchangeable — `POST` only creates,
+`PUT` only updates.
+
+| Method   | Path                    | Permission | Description                          |
+|----------|-------------------------|------------|--------------------------------------|
+| `GET`    | `/api/health`           | —          | Health + auth status                 |
+| `GET`    | `/api/whoami`           | —          | Caller's access summary              |
+| `GET`    | `/api/namespaces`       | any key    | List accessible namespaces           |
+| `GET`    | `/api/{ns}`             | read `ns`  | List entries in a namespace          |
+| `POST`   | `/api/{ns}`             | write `ns` | Create an entry (`409` if key exists) |
+| `GET`    | `/api/{ns}/{key}`       | read `ns`  | Get one entry                        |
+| `PUT`    | `/api/{ns}/{key}`       | write `ns` | Update an entry (`404` if missing)   |
+| `DELETE` | `/api/{ns}/{key}`       | write `ns` | Delete an entry                      |
+| `DELETE` | `/api/{ns}`             | write `ns` | Delete a namespace                   |
+
+```bash
+# create — POST to the namespace, key in the body
+curl -X POST localhost:8000/api/demo \
+  -H 'Content-Type: application/json' \
+  -d '{"key":"greeting","value":"hello","type":"string"}'
+
+# update — PUT to the entry's URI
+curl -X PUT localhost:8000/api/demo/greeting \
+  -H 'Content-Type: application/json' \
+  -d '{"value":"hi there","type":"string"}'
+
+curl localhost:8000/api/demo          # list entries
+```
+
+(The names `namespaces`, `health`, and `whoami` are reserved and can't be used
+as namespaces, since they'd collide with the routes above.)
+
+The API is self-documenting via OpenAPI. Interactive docs are available at:
+
+- **`/docs`** — Swagger UI (also linked as **API docs** in the web interface header)
+- **`/redoc`** — ReDoc
+- **`/openapi.json`** — raw OpenAPI schema
+
+When auth is enabled, each operation in Swagger exposes an `X-API-Key` header
+field you can fill in to try requests.
+
+### CSV import / export (web UI only)
+
+The web interface has **Download CSV** / **Import CSV** buttons on each
+namespace. These are a convenience of the web UI only — they are built on the
+regular entry API (export reads the entries; import creates/updates each row),
+so there are no dedicated CSV endpoints. The CSV has three columns —
+`key`, `type`, `value`:
+
+```csv
+key,type,value
+name,string,alice
+count,number,7
+tags,array,"[""x"", ""y""]"
+```
+
+On import the `type` column is optional — if omitted, each value's type is
+inferred from its text.
+
+### Access control (accounts + API keys)
+
+Off by default. **Turn it on** with `auth: true` in `tds.yml`, `--auth`, or
+`TDS_AUTH_ENABLED=1`. There are two credential types, and you can use both:
+
+* **User accounts** — username + password. Humans log into the **web UI**
+  (session cookie). Passwords are hashed with scrypt (a slow, salted KDF); the
+  plaintext is never stored.
+* **API keys** — long random tokens for scripts/CI. Only a SHA-256 hash is
+  stored; the token is shown **once**, at creation.
+
+Access is **scoped to each namespace**. A role of `admin` means full CRUD on
+that namespace; `reader` means read-only. A **global admin** manages everything.
+
+#### First run
+
+On first start with auth on, a default admin account is created:
+**username `admin`, password `admin`** — and the web UI **requires you to set a
+new password** before anything else.
+
+#### What the admin does (from the web UI)
+
+1. **Create namespaces** (the admin-only form in the sidebar).
+2. **Create user accounts** scoped to namespaces — e.g. `alice` with
+   `projects=admin` (full CRUD on `projects`). Users then log in and
+   create/read/update/delete data in their namespaces, from the web UI **and**
+   the API.
+
+#### Using the API as a user
+
+Each signed-in user can mint a personal **API key** (web UI → *My API keys*, or
+`POST /api/me/keys`) that inherits their namespace permissions:
+
+```bash
+# the token is returned once; then use it as a header
+curl -X POST localhost:8000/api/projects \
+  -H "X-API-Key: $TOKEN" -H "Content-Type: application/json" \
+  -d '{"key":"env","value":"staging","type":"string"}'
+```
+
+#### Auth & admin endpoints (summary)
+
+| Method   | Path                    | Who    | Purpose                              |
+|----------|-------------------------|--------|--------------------------------------|
+| `POST`   | `/api/login`            | anyone | Log in (sets session cookie)         |
+| `POST`   | `/api/logout`           | anyone | Clear session                        |
+| `POST`   | `/api/password`         | user   | Change your own password             |
+| `POST`   | `/api/namespaces`       | admin  | Create a namespace                   |
+| `GET`/`POST`/`DELETE` | `/api/accounts[/{user}]` | admin | Manage user accounts     |
+| `GET`/`POST`/`DELETE` | `/api/me/keys[/{id}]`    | user  | Manage your own API keys |
+| `GET`/`POST`/`PUT`/`DELETE` | `/api/keys[/{id}]` | admin | Manage standalone (machine) keys |
+
+Standalone machine-to-machine keys (not tied to an account) are still managed by
+an admin at `/api/keys`. For bootstrapping you may seed keys via `TDS_API_KEYS`
+or an admin token via `TDS_ADMIN_KEY` (both hashed in memory, never written to
+disk).
+
+### Configuration
+
+Settings come from `tds.yml`/`tds.yaml` in the project root, overridden by
+environment variables:
+
+| YAML key   | Env var            | Default      | Purpose                                  |
+|------------|--------------------|--------------|------------------------------------------|
+| `data_dir` | `TDS_DATA_DIR`     | `./tds-data` | Namespace files + `.auth/` live here     |
+| `auth`     | `TDS_AUTH_ENABLED` | `false`      | Turn access control on/off               |
+| `host`     | —                  | `127.0.0.1`  | Bind host                                |
+| `port`     | —                  | `8000`       | Bind port                                |
+| `secret`   | `TDS_SECRET`       | *(generated)*| Signs web-UI session cookies             |
+| `admin_key`| `TDS_ADMIN_KEY`    | *(empty)*    | Bootstrap machine admin token            |
+| `api_keys` | `TDS_API_KEYS`     | *(empty)*    | Seed machine keys + grants               |
+| —          | `TDS_KEY_PEPPER`   | *(empty)*    | Optional pepper for API-key hashing      |
+
+Credentials live under `<data_dir>/.auth/` (`accounts.json`, `keys.json`,
+`secret`) — all hashed/secret material, never plaintext passwords or tokens.
+
+### Tests
+
+```bash
+.venv/bin/python -m pytest
+```

test_data_service-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+test_data_service-0.1.0.dist-info/licenses/LICENSE,sha256=ze0jaKIkC6jEhhTGJVgr0n_Ids0q_1Twp4ROzWDXvzs,1070
+testdataservice/__init__.py,sha256=cworwjgnLOi2wa5SXheaGiCEEkHZQ5SiTiOmOLGRy9o,518
+testdataservice/__main__.py,sha256=_8zFIS696CBDsh-PA0SvttOtN85LzS7h6O18ainmWM0,299
+testdataservice/accounts.py,sha256=hC8vugO42NkbIZczXh8XzlEwoSZe60Oz9Ba5dnSPa0E,5467
+testdataservice/app.py,sha256=Vt11DZMUZH38oyNeoLIl5TCTBtld3VYq_cu9U1llcSI,20702
+testdataservice/auth.py,sha256=-_u-UJz-EFXwrP8OIDo44MTvxieaqvnK4JDP5YwfeSM,4902
+testdataservice/cli.py,sha256=hQcBjVtk_HRNMu_Fbs9NfBtcHTJesbR-BQMm9KhOCzg,2357
+testdataservice/config.py,sha256=QaLJua6Tj1SWnZXPEfA48vX0P8Gfv5pu96_u97e3M50,6214
+testdataservice/keystore.py,sha256=r4J1guP-jDGOIjUzTR_F0AutlXQ3ktgsZmZYqGaCI8E,5055
+testdataservice/passwords.py,sha256=jlGZ8Qd3WA9g-2sj-vWsveQ0ojaSO3qpOPP4JGNkBec,1242
+testdataservice/sessions.py,sha256=VnJwx8vdB6lwlPmjtpnoSwTaarb63VZfyij0ginqASY,1437
+testdataservice/storage.py,sha256=irhOCUaG1nulmJkg6mSZh4XHOmh6NcnI7G_K_bLsZU0,6870
+testdataservice/types.py,sha256=NDrC9_KO-AV5UgkG9HHsv37V12ayNwHveQtjaVR_8x8,1807
+testdataservice/web/static/app.js,sha256=CPoH39Xkeba4yMOYNE2ZOoJoe2JV10QGZ-9Xm7sTm9w,17788
+testdataservice/web/static/style.css,sha256=qMRq6P63lruVWkHUI02jguvRgsqRTUoz0zLWTCu8EaM,4858
+testdataservice/web/templates/index.html,sha256=J90JnhOsr-1cO8cUgoGvjfHcgp1VqoQNJzK8ErnwWv0,6316
+test_data_service-0.1.0.dist-info/METADATA,sha256=uFq2cNKKOWb4_hqj_3bB76rlKFV1SyswokMaFybo9pY,9465
+test_data_service-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+test_data_service-0.1.0.dist-info/entry_points.txt,sha256=cCLyBTnqx7W16VnY6WxK9KMH4MQvV_bA9kwetZcaqQw,49
+test_data_service-0.1.0.dist-info/top_level.txt,sha256=4OmyXKWIXnV8bjOiILXdsYTOrcLKLjd3o6wYa1ZUlqk,16
+test_data_service-0.1.0.dist-info/RECORD,,

test_data_service-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

test_data_service-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tds = testdataservice.cli:main

test_data_service-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Roy de Kleijn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

test_data_service-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+testdataservice

testdataservice/__init__.py

@@ -0,0 +1,26 @@
+"""Test Data Service — a disk-backed key/value store with an API and web UI."""
+
+from .app import create_app
+from .config import Config
+from .storage import (
+    Storage,
+    Entry,
+    KeyNotFoundError,
+    KeyExistsError,
+    InvalidNamespaceError,
+    InvalidKeyError,
+)
+from .types import ValueType
+
+__version__ = "0.1.0"
+__all__ = [
+    "create_app",
+    "Config",
+    "Storage",
+    "Entry",
+    "KeyNotFoundError",
+    "KeyExistsError",
+    "InvalidNamespaceError",
+    "InvalidKeyError",
+    "ValueType",
+]

testdataservice/__main__.py

@@ -0,0 +1,10 @@
+"""Module entry point: ``python -m testdataservice``.
+
+Equivalent to the ``tds`` console script, but launched through the interpreter
+directly — handy where the generated script shim isn't on PATH.
+"""
+
+from testdataservice.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

testdataservice/accounts.py

@@ -0,0 +1,168 @@
+"""Persistent user accounts (admin + users). Passwords are hashed, never stored
+in plaintext (see :mod:`testdataservice.passwords`).
+
+An account has per-namespace grants ({namespace: role}) exactly like an API key,
+so a user's API keys can inherit the account's permissions. ``is_admin`` marks a
+global admin who can manage namespaces, accounts, and keys.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+import threading
+from dataclasses import dataclass, asdict, field
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .passwords import hash_password, verify_password
+
+DEFAULT_ADMIN_USER = "admin"
+DEFAULT_ADMIN_PASSWORD = "admin"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+@dataclass
+class Account:
+    username: str
+    password_hash: str
+    is_admin: bool = False
+    grants: dict[str, str] = field(default_factory=dict)  # namespace -> role
+    must_change_password: bool = False
+    created_at: str = ""
+
+    def public(self) -> dict:
+        """Representation safe to return over the API (no password hash)."""
+        return {
+            "username": self.username,
+            "is_admin": self.is_admin,
+            "grants": self.grants,
+            "must_change_password": self.must_change_password,
+            "created_at": self.created_at,
+        }
+
+
+class UsernameExistsError(ValueError):
+    pass
+
+
+class AccountStore:
+    def __init__(self, path: str | os.PathLike[str]):
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._lock = threading.RLock()
+
+    # -- file helpers --------------------------------------------------
+    def _load(self) -> dict[str, dict]:
+        if not self.path.exists():
+            return {}
+        with self.path.open("r", encoding="utf-8") as fh:
+            return json.load(fh)
+
+    def _dump(self, data: dict[str, dict]) -> None:
+        fd, tmp = tempfile.mkstemp(dir=self.path.parent, suffix=".tmp")
+        try:
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
+                json.dump(data, fh, indent=2, sort_keys=True)
+            os.replace(tmp, self.path)
+        except BaseException:
+            Path(tmp).unlink(missing_ok=True)
+            raise
+
+    # -- public API ----------------------------------------------------
+    def list(self) -> list["Account"]:
+        with self._lock:
+            data = self._load()
+        return sorted((Account(**a) for a in data.values()), key=lambda a: a.username)
+
+    def get(self, username: str) -> "Account | None":
+        with self._lock:
+            data = self._load()
+        rec = data.get(username)
+        return Account(**rec) if rec else None
+
+    def exists(self) -> bool:
+        with self._lock:
+            return bool(self._load())
+
+    def create(
+        self,
+        username: str,
+        password: str,
+        *,
+        is_admin: bool = False,
+        grants: dict[str, str] | None = None,
+        must_change_password: bool = False,
+    ) -> "Account":
+        username = username.strip()
+        if not username:
+            raise ValueError("Username must be non-empty.")
+        if not password:
+            raise ValueError("Password must be non-empty.")
+        with self._lock:
+            data = self._load()
+            if username in data:
+                raise UsernameExistsError(f"Account {username!r} already exists.")
+            acct = Account(
+                username=username,
+                password_hash=hash_password(password),
+                is_admin=is_admin,
+                grants=dict(grants or {}),
+                must_change_password=must_change_password,
+                created_at=_now(),
+            )
+            data[username] = asdict(acct)
+            self._dump(data)
+        return acct
+
+    def set_password(self, username: str, new_password: str) -> bool:
+        if not new_password:
+            raise ValueError("Password must be non-empty.")
+        with self._lock:
+            data = self._load()
+            if username not in data:
+                return False
+            data[username]["password_hash"] = hash_password(new_password)
+            data[username]["must_change_password"] = False
+            self._dump(data)
+        return True
+
+    def update_grants(self, username: str, grants: dict[str, str]) -> "Account | None":
+        with self._lock:
+            data = self._load()
+            if username not in data:
+                return None
+            data[username]["grants"] = dict(grants)
+            self._dump(data)
+            return Account(**data[username])
+
+    def delete(self, username: str) -> bool:
+        with self._lock:
+            data = self._load()
+            if username not in data:
+                return False
+            del data[username]
+            self._dump(data)
+        return True
+
+    def verify(self, username: str, password: str) -> "Account | None":
+        acct = self.get(username)
+        if acct and verify_password(password, acct.password_hash):
+            return acct
+        return None
+
+    def ensure_default_admin(self) -> None:
+        """Seed the default admin/admin account (must change on first login)."""
+        with self._lock:
+            if self._load():
+                return
+            self.create(
+                DEFAULT_ADMIN_USER,
+                DEFAULT_ADMIN_PASSWORD,
+                is_admin=True,
+                must_change_password=True,
+            )