briskdb 0.1.0a4__tar.gz

briskdb-0.1.0a4/.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- What changed, and why? -->
+
+## Tests
+
+<!-- List the exact commands and targeted suites run. -->
+
+- [ ] Unit tests were added or updated for behavior-changing code.
+- [ ] Boundary/integration tests were added where the change crosses SQLite,
+      HTTP, protocol, filesystem, or process boundaries.
+- [ ] A regression test accompanies each bug fix.
+- [ ] No automated test is applicable; the explanation is included above.
+- [ ] `cargo fmt --check` passes.
+- [ ] `cargo test` passes.
+- [ ] `cargo clippy --all-targets --all-features -- -D warnings` passes.
+
+## Compatibility and operations
+
+- [ ] Public behavior and compatibility documentation were updated where needed.
+- [ ] Storage-format, migration, security, and recovery effects were considered.
+
+Closes #

briskdb-0.1.0a4/.github/workflows/ci.yml

@@ -0,0 +1,209 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUST_BACKTRACE: "1"
+
+jobs:
+  features:
+    name: Features (${{ matrix.surface }}, Rust ${{ matrix.rust }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    strategy:
+      fail-fast: false
+      matrix:
+        rust:
+          - "1.85.0"
+          - stable
+        surface:
+          - core
+          - embedded
+          - http
+          - postgres
+          - sqlite-import
+          - default
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install Rust ${{ matrix.rust }}
+        run: rustup toolchain install "${{ matrix.rust }}" --profile minimal
+
+      - name: Select Rust ${{ matrix.rust }}
+        run: rustup default "${{ matrix.rust }}"
+
+      - name: Restore Rust build cache
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        with:
+          shared-key: features-${{ matrix.rust }}-${{ matrix.surface }}
+
+      - name: Check feature surface
+        run: |
+          case "${{ matrix.surface }}" in
+            core) cargo check --locked --lib --no-default-features ;;
+            default) cargo check --locked --lib ;;
+            *) cargo check --locked --lib --no-default-features --features "${{ matrix.surface }}" ;;
+          esac
+
+      - name: Verify embedded dependency boundary
+        if: matrix.surface == 'embedded'
+        run: |
+          forbidden_dependencies="$(
+            cargo tree --locked --no-default-features --features embedded --edges normal --prefix none |
+              awk '$1 ~ /^(anyhow|axum|clap|hyper|hyper-util|pgwire|tokio-util|tower|tracing-subscriber)$/ { print $1 }' |
+              sort -u
+          )"
+          if [ -n "$forbidden_dependencies" ]; then
+            echo "embedded feature unexpectedly includes: $forbidden_dependencies"
+            exit 1
+          fi
+
+  quality:
+    name: Format and Clippy (stable)
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install stable Rust with quality components
+        run: rustup toolchain install stable --profile minimal --component rustfmt,clippy
+
+      - name: Select stable Rust
+        run: rustup default stable
+
+      - name: Restore Rust build cache
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        with:
+          shared-key: stable-quality
+
+      - name: Check formatting
+        run: cargo fmt --all --check
+
+      - name: Run Clippy
+        run: cargo clippy --locked --all-targets --all-features -- -D warnings
+
+      - name: Verify publishable crate package
+        run: cargo package --locked --allow-dirty
+
+      - name: Reject Git-sourced dependencies
+        run: |
+          if awk '/source = "git\+/{ found = 1 } END { exit !found }' Cargo.lock; then
+            echo "Cargo.lock contains a Git-sourced dependency"
+            exit 1
+          fi
+
+  test:
+    name: Tests (${{ matrix.rust }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        rust:
+          - "1.85.0"
+          - stable
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install Rust ${{ matrix.rust }}
+        run: rustup toolchain install "${{ matrix.rust }}" --profile minimal
+
+      - name: Select Rust ${{ matrix.rust }}
+        run: rustup default "${{ matrix.rust }}"
+
+      - name: Restore Rust build cache
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        with:
+          shared-key: tests-${{ matrix.rust }}
+
+      - name: Run target tests
+        run: cargo test --locked --all-targets --all-features
+
+      - name: Run documentation tests
+        run: cargo test --locked --doc --all-features
+
+  python:
+    name: Python source build (${{ matrix.python }})
+    runs-on: ubuntu-24.04
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        python:
+          - "3.9"
+          - "3.14"
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install Rust 1.85
+        run: rustup toolchain install 1.85.0 --profile minimal --component clippy
+
+      - name: Select Rust 1.85
+        run: rustup default 1.85.0
+
+      - name: Install Python ${{ matrix.python }}
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: ${{ matrix.python }}
+          cache: pip
+          cache-dependency-path: python/pyproject.toml
+
+      - name: Restore Rust build cache
+        uses: Swatinem/rust-cache@6323deb102c322ba6fcbdcafc7e3dddab59af2b6 # v2.9.2
+        with:
+          shared-key: python-${{ matrix.python }}
+
+      - name: Install pinned build frontend
+        run: python -m pip install maturin==1.14.1
+
+      - name: Build wheel from source
+        run: maturin build --manifest-path python/Cargo.toml --locked --out dist
+
+      - name: Install wheel and run Python tests
+        run: |
+          python -m pip install --force-reinstall dist/*.whl
+          python -m unittest discover -s python/tests -v
+
+      - name: Test and lint the native extension
+        run: |
+          cargo test --locked -p briskdb-python
+          cargo clippy --locked -p briskdb-python --all-targets --no-deps -- -D warnings
+
+      - name: Verify Python dependency boundary
+        run: |
+          forbidden_dependencies="$(
+            cargo tree --locked -p briskdb-python --edges normal --prefix none |
+              awk '$1 ~ /^(anyhow|axum|clap|hyper|hyper-util|pgwire|tokio-util|tower|tracing-subscriber)$/ { print $1 }' |
+              sort -u
+          )"
+          if [ -n "$forbidden_dependencies" ]; then
+            echo "Python extension unexpectedly includes: $forbidden_dependencies"
+            exit 1
+          fi

briskdb-0.1.0a4/.github/workflows/python-wheels.yml

@@ -0,0 +1,207 @@
+name: Python distributions
+
+on:
+  pull_request:
+    paths:
+      - ".github/workflows/python-wheels.yml"
+      - ".github/workflows/release.yml"
+      - "Cargo.lock"
+      - "Cargo.toml"
+      - "LICENSE"
+      - "python/**"
+      - "src/**"
+  workflow_call:
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+  MACOSX_DEPLOYMENT_TARGET: "11.0"
+
+jobs:
+  sdist:
+    name: Python sdist, metadata, and typing
+    runs-on: ubuntu-24.04
+    timeout-minutes: 25
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install Rust 1.85
+        run: rustup toolchain install 1.85.0 --profile minimal
+
+      - name: Select Rust 1.85
+        run: rustup default 1.85.0
+
+      - name: Install Python 3.14
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.14"
+          cache: pip
+          cache-dependency-path: python/pyproject.toml
+
+      - name: Install pinned packaging tools
+        run: >-
+          python -m pip install
+          maturin==1.14.1
+          mypy==1.19.1
+          packaging==26.3
+          twine==7.0.0
+
+      - name: Check Rust, extension, and build metadata parity
+        run: python python/scripts/check_versions.py
+
+      - name: Type-check the public API at the minimum Python version
+        env:
+          MYPYPATH: python/python
+        run: python -m mypy --strict --python-version 3.9 python/tests/typing_contract.py
+
+      - name: Build and inspect the source distribution
+        shell: bash
+        run: |
+          set -euo pipefail
+          maturin sdist --manifest-path python/Cargo.toml --out dist
+          sdists=(dist/*.tar.gz)
+          if [[ ${#sdists[@]} -ne 1 || ! -f "${sdists[0]}" ]]; then
+            echo "expected exactly one source distribution" >&2
+            exit 1
+          fi
+          python python/scripts/check_dist.py --sdist "${sdists[0]}"
+          python -m twine check "${sdists[0]}"
+
+      - name: Install the sdist and run the Python suite
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m venv "$RUNNER_TEMP/briskdb-sdist"
+          "$RUNNER_TEMP/briskdb-sdist/bin/python" -m pip install dist/*.tar.gz
+          "$RUNNER_TEMP/briskdb-sdist/bin/python" -m unittest discover -s python/tests -v
+
+      - name: Upload source distribution
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: briskdb-python-sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+
+  wheels:
+    name: Python wheel (${{ matrix.platform }})
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            target: x86_64-unknown-linux-gnu
+            platform: manylinux_2_28_x86_64
+            manylinux: "2_28"
+          - runner: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            platform: manylinux_2_28_aarch64
+            manylinux: "2_28"
+          - runner: macos-15-intel
+            target: x86_64-apple-darwin
+            platform: macosx_11_0_x86_64
+            manylinux: auto
+          - runner: macos-15
+            target: aarch64-apple-darwin
+            platform: macosx_11_0_arm64
+            manylinux: auto
+    steps:
+      - name: Check out source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install Python 3.14 for build inspection
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.14"
+
+      - name: Build the abi3 wheel under the fixed platform policy
+        uses: PyO3/maturin-action@e83996d129638aa358a18fbd1dfb82f0b0fb5d3b # v1.51.0
+        with:
+          maturin-version: v1.14.1
+          rust-toolchain: 1.85.0
+          target: ${{ matrix.target }}
+          manylinux: ${{ matrix.manylinux }}
+          args: >-
+            --release
+            --locked
+            --compatibility pypi
+            --manifest-path python/Cargo.toml
+            --out dist
+
+      - name: Check wheel contents, metadata, and exact tag
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install check-wheel-contents==0.6.3 packaging==26.3
+          wheels=(dist/*.whl)
+          if [[ ${#wheels[@]} -ne 1 || ! -f "${wheels[0]}" ]]; then
+            echo "expected exactly one wheel" >&2
+            exit 1
+          fi
+          check-wheel-contents "${wheels[0]}"
+          python python/scripts/check_dist.py \
+            --wheel "${wheels[0]}" \
+            --platform "${{ matrix.platform }}"
+
+      - name: Audit manylinux dependencies and symbols
+        if: runner.os == 'Linux'
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install auditwheel==6.8.0
+          auditwheel show dist/*.whl | tee "dist/${{ matrix.platform }}-AUDIT.txt"
+
+      - name: Inspect macOS dynamic-library dependencies
+        if: runner.os == 'macOS'
+        shell: bash
+        run: |
+          set -euo pipefail
+          python -m pip install delocate==0.13.0
+          delocate-listdeps --all dist/*.whl | tee "dist/${{ matrix.platform }}-AUDIT.txt"
+
+      - name: Install and test wheel on CPython 3.9
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.9"
+
+      - name: Run minimum-version wheel tests without a source build
+        run: |
+          python -m pip install --no-index --only-binary=:all: --force-reinstall dist/*.whl
+          python -m unittest discover -s python/tests -v
+
+      - name: Install and test wheel on CPython 3.14
+        uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0
+        with:
+          python-version: "3.14"
+
+      - name: Run maximum-version wheel tests without a source build
+        run: |
+          python -m pip install --no-index --only-binary=:all: --force-reinstall dist/*.whl
+          python -m unittest discover -s python/tests -v
+          python -m pip install mypy==1.19.1
+          python -m mypy --strict --python-version 3.9 python/tests/typing_contract.py
+
+      - name: Upload wheel
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: briskdb-python-wheel-${{ matrix.platform }}
+          path: dist/*.whl
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Upload native dependency audit
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: briskdb-python-audit-${{ matrix.platform }}
+          path: dist/*-AUDIT.txt
+          if-no-files-found: error
+          retention-days: 7

briskdb-0.1.0a4/.github/workflows/release.yml

@@ -0,0 +1,231 @@
+name: Release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  python-wheels:
+    name: Build and verify Python distributions
+    uses: ./.github/workflows/python-wheels.yml
+
+  build:
+    name: Build ${{ matrix.platform }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - runner: ubuntu-24.04
+            target: x86_64-unknown-linux-gnu
+            platform: linux-x86_64
+            deb_architecture: amd64
+          - runner: ubuntu-24.04-arm
+            target: aarch64-unknown-linux-gnu
+            platform: linux-aarch64
+            deb_architecture: arm64
+          - runner: macos-15-intel
+            target: x86_64-apple-darwin
+            platform: macos-x86_64
+            deb_architecture: none
+          - runner: macos-15
+            target: aarch64-apple-darwin
+            platform: macos-aarch64
+            deb_architecture: none
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Install stable Rust
+        run: rustup toolchain install stable --profile minimal --target "${{ matrix.target }}"
+
+      - name: Select stable Rust
+        run: rustup default stable
+
+      - name: Verify release version
+        shell: bash
+        run: |
+          set -euo pipefail
+          version="$(cargo metadata --locked --no-deps --format-version 1 | python3 -c 'import json,sys; print(next(p["version"] for p in json.load(sys.stdin)["packages"] if p["name"] == "briskdb"))')"
+          if [[ "$GITHUB_REF_TYPE" == "tag" && "$GITHUB_REF_NAME" != "v$version" ]]; then
+            echo "tag $GITHUB_REF_NAME does not match package version $version" >&2
+            exit 1
+          fi
+          echo "VERSION=$version" >> "$GITHUB_ENV"
+
+      - name: Build locked release binaries
+        run: cargo build --release --locked --bins --target "${{ matrix.target }}"
+
+      - name: Smoke-test native server
+        shell: bash
+        run: |
+          set -euo pipefail
+          binary="target/${{ matrix.target }}/release/briskdb"
+          "$binary" --version | grep -F "briskdb $VERSION"
+          data_dir="$(mktemp -d)"
+          "$binary" \
+            --listen 127.0.0.1:17654 \
+            --postgres-listen disabled \
+            --data-dir "$data_dir/database" \
+            --shards 2 &
+          server_pid=$!
+          cleanup() {
+            kill -TERM "$server_pid" 2>/dev/null || true
+            wait "$server_pid" 2>/dev/null || true
+            rm -rf "$data_dir"
+          }
+          trap cleanup EXIT
+          for attempt in {1..30}; do
+            if curl --fail --silent --show-error http://127.0.0.1:17654/admin >/dev/null; then
+              kill -TERM "$server_pid"
+              wait "$server_pid"
+              trap - EXIT
+              rm -rf "$data_dir"
+              exit 0
+            fi
+            sleep 1
+          done
+          echo "server did not become ready" >&2
+          exit 1
+
+      - name: Package release archive
+        shell: bash
+        run: |
+          set -euo pipefail
+          archive="briskdb-v${VERSION}-${{ matrix.platform }}"
+          mkdir -p "dist/$archive"
+          cp "target/${{ matrix.target }}/release/briskdb" "dist/$archive/"
+          cp "target/${{ matrix.target }}/release/briskdb-import" "dist/$archive/"
+          cp README.md RELEASE_NOTES.md LICENSE ROADMAP.md CONTRIBUTING.md "dist/$archive/"
+          cp -R docs "dist/$archive/docs"
+          tar -C dist -czf "dist/$archive.tar.gz" "$archive"
+          tar -tzf "dist/$archive.tar.gz" | grep -F "$archive/docs/OFFLINE_BACKUP.md"
+
+      - name: Build Debian package
+        if: matrix.deb_architecture != 'none'
+        shell: bash
+        run: |
+          packaging/debian/build-deb.sh \
+            "target/${{ matrix.target }}/release" \
+            "${{ matrix.deb_architecture }}" \
+            "$VERSION" \
+            dist
+
+      - name: Install and smoke-test Debian service
+        if: matrix.deb_architecture != 'none'
+        shell: bash
+        run: |
+          set -euo pipefail
+          packages=(dist/*.deb)
+          if [[ ${#packages[@]} -ne 1 || ! -f "${packages[0]}" ]]; then
+            echo "expected exactly one Debian package" >&2
+            exit 1
+          fi
+          packaging/debian/test-deb-service.sh "${packages[0]}"
+
+      - name: Upload release archive
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: briskdb-${{ matrix.platform }}
+          path: dist/*.tar.gz
+          if-no-files-found: error
+          retention-days: 7
+
+      - name: Upload Debian package
+        if: matrix.deb_architecture != 'none'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: briskdb-deb-${{ matrix.deb_architecture }}
+          path: dist/*.deb
+          if-no-files-found: error
+          retention-days: 7
+
+  release:
+    name: Publish GitHub prerelease
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: [build, python-wheels]
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      attestations: write
+      contents: write
+      id-token: write
+    steps:
+      - name: Check out tagged source
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+
+      - name: Download release archives
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: dist
+          pattern: briskdb-*
+          merge-multiple: true
+
+      - name: Create checksums
+        working-directory: dist
+        shell: bash
+        run: |
+          set -euo pipefail
+          artifacts=(*.tar.gz *.deb *.whl *-AUDIT.txt)
+          sha256sum "${artifacts[@]}" > SHA256SUMS
+
+      - name: Sign artifact provenance
+        uses: actions/attest-build-provenance@4d101475d8b20a2381f78447822ac1eab6504dd8 # v4.2.2
+        with:
+          subject-checksums: dist/SHA256SUMS
+
+      - name: Publish prerelease
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --verify-tag \
+            --prerelease \
+            --title "BriskDB $GITHUB_REF_NAME" \
+            --notes-file RELEASE_NOTES.md
+
+  publish-python:
+    name: Publish Python distributions to PyPI
+    if: startsWith(github.ref, 'refs/tags/v')
+    needs: release
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+      url: https://pypi.org/p/briskdb
+    steps:
+      - name: Download verified wheels
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: dist
+          pattern: briskdb-python-wheel-*
+          merge-multiple: true
+
+      - name: Download verified source distribution
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          path: dist
+          pattern: briskdb-python-sdist
+          merge-multiple: true
+
+      - name: Publish to PyPI with the repository API token
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          packages-dir: dist
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          # PEP 740 attestations require OIDC trusted publishing. GitHub build
+          # provenance for the same files is generated by the release job.
+          attestations: false

briskdb-0.1.0a4/.gitignore

@@ -0,0 +1,7 @@
+/target
+/dist
+/.venv
+/python/python/briskdb/_briskdb*.so
+/python/python/briskdb/_briskdb*.pyd
+__pycache__/
+*.pyc