HTTP server that exposes stores, arrays, groups

.github/workflows/check_changelogs.yml

@@ -32,3 +32,6 @@ jobs:
 
       - name: Check zarr-indexing changelog entries
         run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-indexing/changes
+
+      - name: Check zarr-http-server changelog entries
+        run: uv run --no-sync python ci/check_changelog_entries.py packages/zarr-http-server/changes

.github/workflows/zarr-http-server-release.yml

@@ -0,0 +1,117 @@
+name: zarr-http-server release
+
+on:
+  workflow_dispatch:
+  push:
+    tags:
+      - 'zarr_http_server-v*'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build wheel and sdist
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-http-server
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+          fetch-depth: 0          # hatch-vcs needs full history + tags
+
+      - name: Install Hatch
+        uses: pypa/hatch@257e27e51a6a5616ed08a39a408a21c35c9931bc
+        with:
+          version: '1.16.5'
+
+      - name: Build
+        run: hatch build
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: zarr-http-server-dist
+          path: packages/zarr-http-server/dist
+
+  test_artifacts:
+    name: Test built artifacts
+    needs: [build]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: zarr-http-server-dist
+          path: dist
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: false
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Install built wheel and run import smoke test
+        run: |
+          wheel=$(ls dist/*.whl)
+          uv run --with "${wheel}" --python 3.12 --no-project \
+            python -c "import zarr_http_server; print('zarr_http_server', zarr_http_server.__version__)"
+
+  upload_pypi:
+    name: Upload to PyPI
+    needs: [build, test_artifacts]
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/zarr_http_server-v')
+    runs-on: ubuntu-latest
+    environment:
+      name: zarr-http-server-releases
+      url: https://pypi.org/p/zarr-http-server
+    permissions:
+      id-token: write          # required for OIDC trusted publishing
+      attestations: write      # required for artifact attestations
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: zarr-http-server-dist
+          path: dist
+
+      - name: Generate artifact attestation
+        uses: actions/attest@508db95dd578ae2727ebd6217d5ba78e4fbda05d # v4.2.1
+        with:
+          subject-path: dist/*
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+
+  upload_testpypi:
+    name: Upload to TestPyPI
+    needs: [build, test_artifacts]
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment:
+      name: zarr-http-server-releases-test
+      url: https://test.pypi.org/p/zarr-http-server
+    permissions:
+      id-token: write
+      attestations: write
+    steps:
+      - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: zarr-http-server-dist
+          path: dist
+
+      - name: Generate artifact attestation
+        uses: actions/attest@508db95dd578ae2727ebd6217d5ba78e4fbda05d # v4.2.1
+        with:
+          subject-path: dist/*
+
+      - name: Publish package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # v1.14.2
+        with:
+          repository-url: https://test.pypi.org/legacy/

.github/workflows/zarr-http-server.yml

@@ -0,0 +1,139 @@
+name: zarr-http-server
+
+# Job steps delegate to packages/zarr-http-server/justfile, the single source
+# of truth for this package's verbs; CI owns only the python matrix and
+# caching. Keeping the commands in one place is what makes `just check`
+# locally mean the same thing as a green run here.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'packages/zarr-http-server/**'
+      - '.github/workflows/zarr-http-server.yml'
+      # The package resolves zarr from the repo root for its own tests, so a
+      # core change can break it. Run this suite when core changes too.
+      - 'src/zarr/**'
+  pull_request:
+    paths:
+      - 'packages/zarr-http-server/**'
+      - '.github/workflows/zarr-http-server.yml'
+      # The package resolves zarr from the repo root for its own tests, so a
+      # core change can break it. Run this suite when core changes too.
+      - 'src/zarr/**'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: pytest py=${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-http-server
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ['3.12', '3.13', '3.14']
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+      - name: Sync test dependency groups
+        # The examples group carries the deps the README examples need, so the
+        # test that reads a served array back with a zarr client runs here
+        # instead of silently skipping.
+        run: uv sync --group test --group examples --python ${{ matrix.python-version }}
+      - name: Run pytest
+        run: just test
+
+  ruff:
+    name: ruff
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-http-server
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+      - name: Install just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+      - name: Run ruff
+        run: just lint
+
+  mypy:
+    name: mypy
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-http-server
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+      - name: Sync test dependency group
+        run: uv sync --group test --python 3.12
+      - name: Run mypy
+        run: just typecheck
+
+  docs:
+    name: docs
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash
+        working-directory: packages/zarr-http-server
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - name: Install uv
+        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        with:
+          enable-cache: true
+      - name: Install just
+        uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
+      - name: Build docs
+        run: just docs-check
+
+  zarr-http-server-complete:
+    name: zarr-http-server complete
+    needs: [test, ruff, mypy, docs]
+    if: always()
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check failure
+        if: |
+          contains(needs.*.result, 'failure') ||
+          contains(needs.*.result, 'cancelled')
+        run: exit 1
+      - name: Success
+        run: echo Success!

.pre-commit-config.yaml

@@ -2,11 +2,13 @@ ci:
   autoupdate_commit_msg: "chore: update pre-commit hooks"
   autoupdate_schedule: "monthly"
   autofix_prs: false
-  # mypy runs as a `language: system` hook via `uv run mypy`, which needs `uv`
-  # and the repo checkout to resolve the dev environment from `uv.lock` —
-  # unavailable on pre-commit.ci's runners. It is covered instead by the Lint
-  # GitHub Actions workflow and by local prek runs.
-  skip: [mypy]
+  # Both of these are `language: system` hooks that shell out to the local
+  # toolchain — `uv` for mypy, `uv` and `just` for the docs build — and need
+  # the repo checkout to resolve their environments from `uv.lock`. Neither is
+  # available on pre-commit.ci's runners. Each is covered instead by a GitHub
+  # Actions job (Lint for mypy, zarr-http-server for the docs build) and by
+  # local prek runs.
+  skip: [mypy, zarr-http-server-docs]
 
 default_stages: [pre-commit, pre-push]
 
@@ -50,6 +52,25 @@ repos:
         pass_filenames: false
         always_run: true
         types_or: [python, pyi]
+      # Builds the zarr-http-server docs site with warnings as errors, which
+      # catches a dead cross-reference or a nav entry pointing at a file that
+      # no longer exists before it reaches CI.
+      #
+      # `stages: [pre-push]` overrides the default of running on every commit:
+      # this is a whole-site build, too slow to pay per commit and only
+      # actionable before the code leaves the machine. `files:` limits it to
+      # changes that touch the package, and `pass_filenames: false` because
+      # mkdocs builds the site, not a list of files. Delegating to the
+      # justfile keeps one definition of the build shared with CI.
+      - id: zarr-http-server-docs
+        name: zarr-http-server docs build
+        language: system
+        entry: >-
+          just --justfile packages/zarr-http-server/justfile
+          --working-directory packages/zarr-http-server docs-check
+        pass_filenames: false
+        files: ^packages/zarr-http-server/
+        stages: [pre-push]
   - repo: https://github.com/scientific-python/cookie
     rev: 2026.06.18
     hooks:

packages/zarr-http-server/.readthedocs.yaml

@@ -0,0 +1,30 @@
+# Read the Docs configuration for the zarr-http-server docs site, separate from
+# the zarr-python site configured by the repo-root .readthedocs.yaml. The RTD
+# project for zarr-http-server must set its configuration-file path to
+# packages/zarr-http-server/.readthedocs.yaml.
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+  jobs:
+    post_checkout:
+      # Cancel pull request builds that do not touch this package. Exit code
+      # 183 cancels the build and reports success to the Git provider. Scoped
+      # to PR builds ("external" versions) because origin/main is only a
+      # meaningful diff base there.
+      - |
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- packages/zarr-http-server;
+        then
+          exit 183;
+        fi
+    install:
+      - pip install --upgrade pip
+      - pip install ./packages/zarr-http-server --group packages/zarr-http-server/pyproject.toml:docs
+    build:
+      html:
+        - mkdocs build --strict -f packages/zarr-http-server/mkdocs.yml --site-dir $READTHEDOCS_OUTPUT/html
+
+mkdocs:
+  configuration: packages/zarr-http-server/mkdocs.yml

packages/zarr-http-server/CHANGELOG.md

@@ -0,0 +1,3 @@
+# Release notes
+
+<!-- towncrier release notes start -->

packages/zarr-http-server/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-2025 Zarr Developers <https://github.com/zarr-developers>
+
+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.