h2hdb-opds 0.1.0__tar.gz

h2hdb_opds-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,119 @@
+name: Publish to PyPI
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - pyproject.toml
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    outputs:
+      bumped: ${{ steps.version.outputs.bumped }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 2
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.14"
+
+      - name: Install packaging tools
+        run: python -m pip install --upgrade packaging build
+
+      - name: Check version bump
+        id: version
+        run: |
+          python - <<'PY'
+          import os
+          from pathlib import Path
+          import subprocess
+          import tomllib
+
+          from packaging.version import Version
+
+
+          def project_version(document: str) -> Version:
+              return Version(str(tomllib.loads(document)["project"]["version"]))
+
+
+          current = project_version(
+              Path("pyproject.toml").read_text(encoding="utf-8")
+          )
+          previous_document = subprocess.run(
+              ["git", "show", "HEAD~1:pyproject.toml"],
+              check=False,
+              capture_output=True,
+              text=True,
+          )
+          previous = (
+              project_version(previous_document.stdout)
+              if previous_document.returncode == 0
+              else None
+          )
+          if previous is not None and current < previous:
+              raise SystemExit(
+                  f"project.version decreased from {previous} to {current}"
+              )
+
+          bumped = previous is None or current > previous
+          output_path = Path(os.environ["GITHUB_OUTPUT"])
+          with output_path.open("a", encoding="utf-8") as output:
+              print(f"current={current}", file=output)
+              print(f"previous={previous or ''}", file=output)
+              print(f"bumped={'true' if bumped else 'false'}", file=output)
+          PY
+
+      - name: Install project and development dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Check formatting
+        run: python -m black --check .
+
+      - name: Lint
+        run: python -m ruff check .
+
+      - name: Type-check
+        run: python -m mypy src tests
+
+      - name: Test
+        run: python -m pytest
+
+      - name: Build distributions
+        run: python -m build
+
+      - name: Smoke-test wheel
+        run: |
+          WHEEL="$(find dist -maxdepth 1 -name '*.whl' -print -quit)"
+          test -n "$WHEEL"
+          python -m pip install --force-reinstall --no-deps "$WHEEL"
+          python -c "import h2hdb_opds"
+
+      - name: Store distributions
+        if: steps.version.outputs.bumped == 'true'
+        uses: actions/upload-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    needs: validate
+    if: needs.validate.outputs.bumped == 'true'
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: distributions
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

h2hdb_opds-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.DS_Store
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+__pycache__/
+*.egg-info/
+*.py[cod]
+build/
+dist/
+htmlcov/
+uv.lock

h2hdb_opds-0.1.0/AGENTS.md

@@ -0,0 +1,98 @@
+# Agent Instructions
+
+## Project
+
+`h2hdb-opds` is the OPDS 2.0 HTTP service for H2HDB catalogs. Python must be
+run through `uv run --no-sync`, using the repository-local virtual environment.
+The supported Python version is defined by `requires-python` in
+`pyproject.toml`.
+
+## Ownership Boundary
+
+This repository owns:
+
+- FastAPI and ASGI integration;
+- OPDS 2.0 models and serialization;
+- navigation, publications, search, and pagination;
+- authentication;
+- acquisition, Range, and conditional HTTP responses.
+
+The `h2hdb` core package exclusively owns connectors, transactions, database
+schema and migrations, durable queues, coordination fencing, and catalog
+repositories. Depend only on core public interfaces. Do not import connector or
+repository internals and do not create or migrate schema here. Database access
+is always forced to read-only, and the service exposes only published catalog
+revisions. Production startup uses `open_database()` for its compatibility
+check. Injected readers are checked through their public `check_compatibility()`
+method. No startup path may call `migrate()`.
+
+## Module Layout and HTTP Invariants
+
+- `config.py` owns the frozen OPDS, server, authentication, and nested core
+  configuration models.
+- `app.py` wires the FastAPI lifespan and routes to a compatible public
+  `CatalogReader`.
+- `serialization.py` owns OPDS feed, publication, navigation, search template,
+  and pagination serialization.
+- `auth.py` owns Basic authentication and the public OPDS authentication
+  document. Credential comparisons must use `secrets.compare_digest`.
+- `acquisition.py` owns artifact file responses and HTTP validators/ranges.
+
+Feed responses use `application/opds+json`; standalone publications use
+`application/opds-publication+json`. Acquisition ETags are strong SHA-256
+validators from the verified artifact. Apply the RFC precondition order from
+`If-Match` through `If-Modified-Since`. Support only one byte range; invalid,
+multiple, and unsatisfiable byte ranges return 416 with `Content-Range`, unknown
+range units are ignored, and an `If-Range` mismatch returns the complete 200
+representation. An `If-Range` date comparison is exact.
+
+All acquisition paths must remain under the configured real artifact root and
+must be opened without following symlinks. Verify size and SHA-256 before sending
+a strong validator. Absolute links come only from the canonical public base URL,
+never the request Host header. Basic authentication requires an effective HTTPS
+request and either local TLS or an explicitly trusted TLS-terminating proxy.
+Catalog listing and counts use core's pinned `require_artifact` filter so every
+serialized OPDS Publication has an acquisition link.
+
+All feed, publication, pagination, and acquisition links carry their selected
+revision. Resolve an omitted revision to the current snapshot and an explicit
+revision through core's public revision-history lookup. Map a missing revision
+to an explicit 404, and pass the resolved `CatalogRevision` into every list,
+publication, and artifact read. Never fall back from a missing requested
+revision to current data or mix snapshots across pagination.
+
+## Environment and Commands
+
+This is a standalone repository, not a uv workspace. `uv.lock` is ignored and
+must not become a build, test, or runtime input.
+
+```bash
+uv venv --python 3.14
+uv pip install -e ".[dev]"
+uv run --no-sync ruff check .
+uv run --no-sync black --check .
+uv run --no-sync mypy src tests
+uv run --no-sync pytest
+uv run --no-sync python -m build
+```
+
+If the environment is damaged, run `scripts/rebuild-env.sh`.
+
+## Shared Finalization
+
+The repository keeps provider-neutral hooks in `scripts/hooks/`.
+
+- After changing Python, run `bash scripts/hooks/finalize-python.sh`.
+- After changing Markdown, run `bash scripts/hooks/finalize-markdown.sh`.
+
+Do not create agent-specific copies of these implementations.
+
+## Design and Compatibility
+
+The project is pre-1.0. Prefer clear responsibility boundaries and the cleanest
+end state over compatibility shims or deprecated aliases. Follow SOLID
+principles. Keep authentication, file I/O, and response streaming separate from
+catalog query construction and never perform schema mutation at service startup.
+
+`CLAUDE.md` documents the same repository rules. Keep both files synchronized
+when changing workflow, ownership, testing, or tooling conventions.

h2hdb_opds-0.1.0/CLAUDE.md

@@ -0,0 +1,95 @@
+# CLAUDE.md
+
+This file provides repository guidance to Claude Code and other coding agents.
+
+## Communication
+
+- Claude 必須以繁體中文回答所有對話內容；程式碼、指令、檔名與專有名詞維持原文。
+
+## Project
+
+`h2hdb-opds` exposes an H2HDB catalog through an OPDS 2.0 HTTP service. It owns
+FastAPI and ASGI integration, OPDS models and serialization, navigation,
+publications, search, pagination, authentication, and acquisition responses
+including Range and conditional HTTP behavior.
+
+The `h2hdb` core package exclusively owns database connectors, transactions,
+schema migrations, durable queues, coordination fencing, and catalog
+repositories. Use only core public interfaces. Never import connector or
+repository internals, create or migrate schema, or expose unpublished catalog
+state. Database access is always forced to read-only. Production startup calls
+the public `open_database()` compatibility path; injected readers call only
+`check_compatibility()`. No startup path may call `migrate()`.
+
+## Module Layout and HTTP Invariants
+
+- `config.py` owns the frozen OPDS, server, authentication, and nested core
+  configuration models.
+- `app.py` wires the FastAPI lifespan and routes to a compatible public
+  `CatalogReader`.
+- `serialization.py` owns OPDS feed, publication, navigation, search template,
+  and pagination serialization.
+- `auth.py` owns Basic authentication and the public OPDS authentication
+  document. Credential comparisons must use `secrets.compare_digest`.
+- `acquisition.py` owns artifact file responses and HTTP validators/ranges.
+
+Feed responses use `application/opds+json`; standalone publications use
+`application/opds-publication+json`. Acquisition ETags are strong SHA-256
+validators from the verified artifact. Apply the RFC precondition order from
+`If-Match` through `If-Modified-Since`. Support only one byte range; invalid,
+multiple, and unsatisfiable byte ranges return 416 with `Content-Range`, unknown
+range units are ignored, and an `If-Range` mismatch returns the complete 200
+representation. An `If-Range` date comparison is exact.
+
+All acquisition paths must remain under the configured real artifact root and
+must be opened without following symlinks. Verify size and SHA-256 before sending
+a strong validator. Absolute links come only from the canonical public base URL,
+never the request Host header. Basic authentication requires an effective HTTPS
+request and either local TLS or an explicitly trusted TLS-terminating proxy.
+Catalog listing and counts use core's pinned `require_artifact` filter so every
+serialized OPDS Publication has an acquisition link.
+
+All feed, publication, pagination, and acquisition links carry their selected
+revision. Resolve an omitted revision to the current snapshot and an explicit
+revision through core's public revision-history lookup. Map a missing revision
+to an explicit 404, and pass the resolved `CatalogRevision` into every list,
+publication, and artifact read. Never fall back from a missing requested
+revision to current data or mix snapshots across pagination.
+
+## Development
+
+This is an independent repository and not part of a uv workspace. `uv.lock` is
+ignored and must not be used by build, test, or runtime workflows. Always run
+Python through `uv run --no-sync` after installing the editable environment.
+
+```bash
+uv venv --python 3.14
+uv pip install -e ".[dev]"
+uv run --no-sync ruff check .
+uv run --no-sync black --check .
+uv run --no-sync mypy src tests
+uv run --no-sync pytest
+uv run --no-sync python -m build
+```
+
+Use `scripts/rebuild-env.sh` to recreate a damaged environment.
+
+## Shared Finalization
+
+Provider-neutral hooks live in `scripts/hooks/` and are shared by humans and
+all coding agents.
+
+- After Python changes, run `bash scripts/hooks/finalize-python.sh`.
+- After Markdown changes, run `bash scripts/hooks/finalize-markdown.sh`.
+
+Do not duplicate their implementation under an agent-specific directory.
+
+## Design
+
+This project is pre-1.0. Prefer the cleanest architecture over compatibility
+shims and deprecated aliases. Follow SOLID principles. Keep authentication,
+file I/O, and response streaming separate from catalog query construction, and
+never perform schema mutation during service startup.
+
+Keep this document synchronized with `AGENTS.md` whenever ownership, workflow,
+testing, or tooling conventions change.