ngh2 0.1.0__tar.gz

ngh2-0.1.0/.agents/skills/ngh2-audit/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: ngh2-audit
+description: Review ngh2 code, diffs, APIs, architecture, tests, Cython/libnghttp2 boundaries, packaging, documentation, or release surfaces for evidence-backed defects and unnecessary complexity. Use for read-only audits and after implementation; never modify files.
+---
+
+# ngh2 Audit
+
+Review the current artifact independently and remain read-only.
+
+## Workflow
+
+1. Read `AGENTS.md`, the requested scope, affected files, applicable tests, and
+   the public contract under review.
+2. Inspect current checkout facts instead of trusting historical reports or the
+   implementation author's conclusion.
+3. Select only relevant lenses: protocol behavior, state/data ownership,
+   Python/native boundaries, public API usability, resource and callback
+   safety, tests, packaging, naming, or maintenance cost.
+4. Use `ngh2-knowledge` when a finding depends on an external fact. Treat
+   protocol sources, official guidance, pinned implementation observations, and
+   engineering judgment as different evidence classes.
+5. Challenge new surface and machinery:
+   - identify the current caller, contract, failure, or source that requires it;
+   - identify which layer owns its state, validation, errors, and lifecycle;
+   - check whether an existing direct path provides the same behavior;
+   - require evidence that matches correctness, interoperability, safety, or
+     performance claims.
+6. For a public API difference from a mature reference, state the observable
+   reference boundary and the caller action enabled by the difference. Report a
+   defect when consumers must reconstruct hidden protocol state or no consumer
+   action depends on the added surface.
+7. Report findings first, ordered by demonstrated consequence. Then list only
+   genuine open questions or evidence gaps.
+
+## Finding Standard
+
+Report a finding only when all four are present:
+
+1. a precise current artifact fact;
+2. a governing source, explicit contract, reproduction, or clearly labelled
+   engineering judgment;
+3. a concrete correctness, interoperability, usability, safety, performance, or
+   maintenance consequence;
+4. the smallest credible resolution direction.
+
+Set severity from consequence and likelihood. Reserve high severity for
+plausible contract failures, interoperability breaks, state/data loss,
+exploitable boundaries, or release blockers.
+
+Do not report style preferences without a consequence, hypothetical risks
+without a present boundary, unmeasured performance concerns, missing
+abstractions where direct code is clear, or compatibility concerns for an
+unreleased surface unless compatibility is required.
+
+If no finding meets the standard, say so clearly and identify only residual
+verification gaps.

ngh2-0.1.0/.agents/skills/ngh2-audit/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ngh2 Audit"
+  short_description: "Review ngh2 for evidence-backed defects"
+  default_prompt: "Use $ngh2-audit to review the current ngh2 changes for defects and unnecessary complexity."

ngh2-0.1.0/.agents/skills/ngh2-implementation/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: ngh2-implementation
+description: Implement requested changes in the ngh2 Python package, Cython/libnghttp2 binding, tests, packaging, CI, or project documentation. Use when creating, modifying, fixing, refactoring, replacing, or migrating ngh2 behavior or repository files. Do not use for read-only audits or factual research.
+---
+
+# ngh2 Implementation
+
+Deliver the smallest complete change that satisfies the request and preserves
+the repository boundaries in `AGENTS.md`.
+
+## Workflow
+
+1. Read `AGENTS.md` and every affected file before editing. Inspect callers,
+   tests, public exports, type information, and configuration that share the
+   changed contract.
+2. Establish the requested outcome and explicit non-goals. Do not add adjacent
+   features, compatibility layers, reports, or tooling without a current need.
+3. Trace the owning layer before choosing the fix. Keep HTTP/2 protocol state
+   in libnghttp2, transport/runtime ownership outside the package, and
+   Python-facing vocabulary natural for Python.
+4. Use `ngh2-knowledge` when a decision depends on protocol requirements,
+   libnghttp2 behavior, established tooling behavior, packaging rules, native
+   extension practice, or licenses. Separate source facts from project choices.
+5. Implement the smallest coherent design. Update all affected layers required
+   for correctness, including Python exports, type information, and tests when
+   their contract changes.
+6. Add the smallest check that would fail for a changed behavior. Match evidence
+   to the claim: focused tests for behavior, interoperability for real peers,
+   fuzzing for hostile input/state exploration, and benchmarks for performance.
+7. Run focused checks first, then the broader gate required by `AGENTS.md`.
+   Read fresh output before claiming success.
+8. Review the final changes with `ngh2-audit`. Address blocking findings through
+   this workflow and rerun the affected checks.
+
+## Implementation Boundaries
+
+- Keep socket, TLS, async runtime, client, server, and connection-pool ownership
+  outside the Sans-I/O binding.
+- Do not reimplement behavior already owned by libnghttp2 without demonstrated
+  need.
+- Prefer existing language features and mature dependencies over local
+  machinery.
+- Replace incorrect pre-release APIs directly. Do not retain aliases, shims, or
+  duplicate implementations unless compatibility is explicitly required.
+- Do not invent protocol behavior, resource limits, safety claims, or
+  performance claims without evidence.
+- Do not add tests that only restate constants, types, or implementation
+  spelling without protecting observable behavior.
+
+Stop and report the conflict instead of patching around missing authority,
+unclear ownership, or an environment that cannot verify the requested result.

ngh2-0.1.0/.agents/skills/ngh2-implementation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ngh2 Implementation"
+  short_description: "Implement focused ngh2 changes safely"
+  default_prompt: "Use $ngh2-implementation to implement this ngh2 change and verify it."

ngh2-0.1.0/.agents/skills/ngh2-knowledge/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: ngh2-knowledge
+description: Research, verify, and, when explicitly requested, maintain source-based knowledge in docs/knowledge. Use for factual questions about HTTP/2, libnghttp2, Sans-I/O architecture, Python/native boundaries, C extension tooling, packaging, dependencies, licenses, performance, or established practice, including stale or conflicting claims. Keep project decisions and code-specific audit conclusions out of the collection.
+---
+
+# ngh2 Knowledge
+
+Use `docs/knowledge/` as a factual reference layer. It supplies evidence and
+source maps; it does not decide what ngh2 should implement.
+
+## Retrieve And Verify
+
+1. Resolve the repository root and read `docs/knowledge/README.md` for evidence
+   labels and freshness semantics.
+2. Search document metadata before loading topic files:
+
+   ```console
+   rg -n '^(title|description|topics|checked_at):' docs/knowledge --glob '*.md'
+   ```
+
+3. Read only documents matching the protocol term, tool, claim, or evidence
+   class. Follow direct citations when exact current wording or provenance
+   matters.
+4. Keep these evidence classes distinct:
+   - normative source: an applicable RFC or BCP;
+   - authoritative registry: current IANA data;
+   - official guidance: documentation from the tool or language owner;
+   - observed practice: behavior or structure in a named, pinned implementation;
+   - methodological synthesis: a conclusion across sources.
+5. Verify live primary sources when the answer depends on mutable protocol
+   status, library behavior, tool behavior, package metadata, or current
+   practice.
+6. Report unavailable, superseded, materially changed, or conflicting sources.
+   Do not silently resolve uncertainty or rewrite the collection during a
+   read-only task.
+
+## Maintain The Collection
+
+Modify `docs/knowledge/` only when knowledge maintenance is explicitly
+requested.
+
+1. Update the existing owner document; add a topic only for a distinct reusable
+   domain.
+2. Keep documents factual and independent of ngh2 code, audits, plans,
+   benchmark results, release decisions, and temporary recommendations.
+3. Use `title`, `description`, `topics`, and `checked_at` frontmatter on topic
+   documents. Change `checked_at` only after reviewing every external claim in
+   that document.
+4. Cite primary sources beside the supported claims. Pin implementation
+   observations to a version or commit.
+5. Replace stale claims instead of appending a contradictory account. Do not
+   copy remote source archives without an offline or reproducibility need.
+6. Update `docs/knowledge/README.md` only when the document set or domain layout
+   changes.
+7. Verify frontmatter, relative links, absence of personal paths, and the
+   separation between source facts, synthesis, and project choices.
+
+Do not create reports, decision logs, generated indexes, or monitoring
+machinery for ordinary knowledge work.

ngh2-0.1.0/.agents/skills/ngh2-knowledge/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ngh2 Knowledge"
+  short_description: "Verify HTTP/2 and native-binding facts"
+  default_prompt: "Use $ngh2-knowledge to verify this HTTP/2 or native-binding claim from primary sources."

ngh2-0.1.0/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: uv
+    directory: "/"
+    versioning-strategy: lockfile-only
+    schedule:
+      interval: weekly
+
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

ngh2-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,148 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event_name }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  RUFF_OUTPUT_FORMAT: github
+  TY_OUTPUT_FORMAT: github
+
+jobs:
+  lint:
+    name: Lint and static analysis
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: astral-sh/setup-uv@v8.3.2
+      - run: uv sync --locked
+      - run: uv run --locked pre-commit run --all-files
+
+  python:
+    name: Python ${{ matrix.python-version }}${{ matrix.preview && ' preview' || '' }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14", "3.14t"]
+        include:
+          # Pre-release interpreters exercise forward compatibility but are
+          # not wheel targets until CPython reaches the release candidate phase.
+          - os: ubuntu-latest
+            python-version: "3.15"
+            preview: true
+          - os: ubuntu-latest
+            python-version: "3.15t"
+            preview: true
+          - os: ubuntu-24.04-arm
+            python-version: "3.12"
+          - os: macos-15-intel
+            python-version: "3.12"
+          - os: macos-14
+            python-version: "3.12"
+          - os: windows-latest
+            python-version: "3.12"
+          - os: windows-11-arm
+            python-version: "3.12"
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --locked --no-dev --group test
+      - run: uv run --locked --no-dev --group test pytest -m "not h2spec"
+
+  h2spec:
+    name: h2spec generic conformance
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: astral-sh/setup-uv@v8.3.2
+      - run: uv sync --locked --no-dev --group test
+      - name: Install h2spec 2.6.0
+        run: |
+          curl --fail --location --silent --show-error \
+            --output "$RUNNER_TEMP/h2spec.tar.gz" \
+            https://github.com/summerwind/h2spec/releases/download/v2.6.0/h2spec_linux_amd64.tar.gz
+          echo "157ee0de702e01ad40e752dbf074b366027e550c8e7504f9450da2809e279318  $RUNNER_TEMP/h2spec.tar.gz" \
+            | sha256sum --check
+          mkdir "$RUNNER_TEMP/h2spec"
+          tar -xzf "$RUNNER_TEMP/h2spec.tar.gz" -C "$RUNNER_TEMP/h2spec"
+          echo "$RUNNER_TEMP/h2spec" >> "$GITHUB_PATH"
+      - run: uv run --locked --no-dev --group test pytest -m h2spec
+
+  package:
+    name: Source distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: astral-sh/setup-uv@v8.3.2
+      - name: Build sdist and rebuild its wheel
+        run: |
+          uv build --sdist
+          uv build --wheel dist/*.tar.gz
+      - name: Test the installed wheel outside the source tree
+        run: |
+          uv venv "$RUNNER_TEMP/ngh2-wheel-test"
+          uv pip install --python "$RUNNER_TEMP/ngh2-wheel-test/bin/python" \
+            dist/*.whl pytest h2
+          cd "$RUNNER_TEMP"
+          "$RUNNER_TEMP/ngh2-wheel-test/bin/python" -m pytest \
+            "$GITHUB_WORKSPACE/tests" -m "not h2spec"
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+    # Codecov uses OIDC, so no long-lived upload token is stored.
+    permissions:
+      contents: read
+      id-token: write
+    env:
+      CMAKE_ARGS: -DNGH2_COVERAGE=ON
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: astral-sh/setup-uv@v8.3.2
+      - name: Build the traced extension
+        run: >-
+          uv --no-cache sync --locked --no-dev --group test --group coverage
+          --reinstall-package ngh2
+      - name: Expose generated C sources to the Cython coverage plugin
+        run: |
+          ln -s "$(find "$GITHUB_WORKSPACE/build" -name _core.c -print -quit)" src/ngh2/_core.c
+          ln -s "$(find "$GITHUB_WORKSPACE/build" -name events.c -print -quit)" src/ngh2/events.c
+      - run: uv run --no-sync coverage run -m pytest -m "not h2spec"
+      - run: uv run --no-sync coverage xml
+      - run: uv run --no-sync coverage report
+      - uses: codecov/codecov-action@v7
+        with:
+          disable_search: true
+          # Test and report generation already gate this job; an external
+          # upload outage should not block the project CI.
+          fail_ci_if_error: false
+          files: coverage.xml
+          use_oidc: true

ngh2-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,121 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref_name }}
+  cancel-in-progress: false
+
+jobs:
+  validate:
+    name: Validate release
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+      - name: Verify tag and package version
+        env:
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: |
+          version="$(python3 -c 'import runpy; print(runpy.run_path("src/ngh2/_version.py")["__version__"])')"
+          test "$RELEASE_TAG" = "v$version"
+          grep -Fq "## [$version] - " CHANGELOG.md
+
+  wheels:
+    name: Wheels on ${{ matrix.platform }}
+    needs: validate
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: manylinux-x86_64
+            os: ubuntu-latest
+          - platform: manylinux-aarch64
+            os: ubuntu-24.04-arm
+          - platform: macos-x86_64
+            os: macos-15-intel
+          - platform: macos-aarch64
+            os: macos-14
+          - platform: windows-x86_64
+            os: windows-latest
+          - platform: windows-aarch64
+            os: windows-11-arm
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: pypa/cibuildwheel@v4.1.0
+      - uses: actions/upload-artifact@v7
+        with:
+          name: wheels-${{ matrix.platform }}
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  sdist:
+    name: Source distribution
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
+          submodules: true
+      - uses: astral-sh/setup-uv@v8.3.2
+        with:
+          enable-cache: false
+      - run: uv build --sdist
+      - name: Smoke-test source distribution
+        run: |
+          uv venv "$RUNNER_TEMP/ngh2-sdist-test"
+          uv pip install --python "$RUNNER_TEMP/ngh2-sdist-test/bin/python" dist/*.tar.gz
+          "$RUNNER_TEMP/ngh2-sdist-test/bin/python" -c "import ngh2"
+      - uses: actions/upload-artifact@v7
+        with:
+          name: sdist
+          path: dist/*.tar.gz
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: [wheels, sdist]
+    runs-on: ubuntu-latest
+    environment: release
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: "*"
+          path: dist
+          merge-multiple: true
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/
+
+  github-release:
+    name: Publish GitHub release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          pattern: "*"
+          path: dist
+          merge-multiple: true
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+          RELEASE_TAG: ${{ github.ref_name }}
+        run: gh release create "$RELEASE_TAG" dist/* --verify-tag --generate-notes

ngh2-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python bytecode and native extensions
+__pycache__/
+*.py[codz]
+*$py.class
+*.so
+*.pyd
+
+# Python environments and local configuration
+.venv/
+.env
+.env.*
+!.env.example
+.pypirc
+
+# Python and CMake build outputs
+build/
+dist/
+*.egg-info/
+*.whl
+CMakeUserPresets.json
+
+# Tests, coverage, and static analysis
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+*.lcov
+.ruff_cache/
+
+# IDE files
+.idea/
+*.iml
+.vscode/
+*.swp
+*.swo
+*~
+
+# Logs
+*.log
+
+# Operating system metadata
+.DS_Store
+._*
+Thumbs.db
+[Dd]esktop.ini
+.directory

ngh2-0.1.0/.gitmodules

@@ -0,0 +1,3 @@
+[submodule "vendor/nghttp2"]
+	path = vendor/nghttp2
+	url = https://github.com/nghttp2/nghttp2.git

ngh2-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+repos:
+  - repo: local
+    hooks:
+      - id: uv-lock
+        name: Check uv lockfile
+        entry: uv lock --check
+        language: system
+        pass_filenames: false
+
+      - id: ruff-format
+        name: Check Python formatting
+        entry: uv run --locked ruff format --check .
+        language: system
+        pass_filenames: false
+
+      - id: ruff-check
+        name: Lint Python
+        entry: uv run --locked ruff check .
+        language: system
+        pass_filenames: false
+
+      - id: cython-lint
+        name: Lint Cython
+        entry: uv run --locked cython-lint src/ngh2
+        language: system
+        pass_filenames: false
+
+      - id: ty
+        name: Check Python types
+        entry: uv run --locked ty check
+        language: system
+        pass_filenames: false

ngh2-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

ngh2-0.1.0/AGENTS.md

@@ -0,0 +1,79 @@
+# ngh2 Repository Guidance
+
+## Product Boundary
+
+- `ngh2` is a Sans-I/O HTTP/2 protocol library for Python, implemented as a
+  Cython binding over the vendored libnghttp2 source.
+- libnghttp2 owns HTTP/2 connection and stream state, framing, HPACK, flow
+  control, scheduling, and protocol validation. Do not reimplement native
+  behavior in the binding without a demonstrated need.
+- Keep sockets, TLS, async runtimes, HTTP clients and servers, connection pools,
+  routing, retries, and application timeouts outside this package.
+- The binding owns Python-facing objects, event and error translation, buffer
+  lifetimes, configuration mapping, type information, and distribution
+  packaging.
+
+## Repository Map
+
+- `src/ngh2`: Python API, Cython implementation, C declarations, and type stubs.
+- `vendor/nghttp2`: pinned upstream Git submodule; update it as a dependency,
+  not by editing vendored source in place.
+- `tests`: behavior, lifecycle, limits, hyper-h2 interoperability, and h2spec
+  adapter coverage.
+- `benchmarks`: reproducible public-API comparison workloads and rendering.
+- `docs/knowledge`: source-based facts, not project decisions or audit reports.
+- `.agents/skills`: project workflows for implementation, audit, and knowledge
+  work.
+
+## Development
+
+Install locked development dependencies with:
+
+```console
+uv sync --locked
+```
+
+Use focused tests while iterating, then run the local gate:
+
+```console
+uv run --locked pytest tests/test_connection.py
+uv run --locked pre-commit run --all-files
+uv run --locked pytest -m "not h2spec"
+uv build
+```
+
+Run `uv run --locked pytest -m h2spec` when the external `h2spec` executable is
+installed and the changed behavior affects protocol interoperability.
+
+## Change Rules
+
+- Read affected callers, tests, exports, stubs, and configuration before
+  editing. Update runtime behavior, public exports, `.pyi` files, and tests
+  together when a Python contract changes.
+- Keep public names and docstrings natural for Python and describe HTTP/2
+  behavior rather than C binding mechanics. Comment internal ownership and
+  callback lifetimes where they are not obvious.
+- Validate protocol ranges, ownership, and C conversion boundaries. Do not add
+  defensive checks that only restate type hints unless they stabilize a public
+  error contract.
+- Treat callback pointers and borrowed native buffers as callback-scoped unless
+  the upstream API explicitly guarantees a longer lifetime.
+- Ruff and ty do not validate Cython source. Binding changes must also pass
+  `cython-lint`, compile, and execute relevant tests; the pre-commit gate runs
+  the configured static checks.
+- Back protocol and libnghttp2 claims with RFCs, official documentation, or
+  pinned source observations. Treat mature implementations as observed
+  practice, not authority.
+- Keep generated C files, build output, local environments, editor state,
+  temporary reports, and personal instructions out of version control.
+
+## Project Skills
+
+- Use `ngh2-implementation` for changes to code, tests, packaging, CI, or
+  project documentation.
+- Use `ngh2-audit` for read-only review after implementation or on request.
+- Use `ngh2-knowledge` for source-based factual research and explicitly
+  requested maintenance of `docs/knowledge`.
+
+Work is complete only after the relevant focused checks and local gate finish
+successfully, followed by a read-only audit of the final changes.

ngh2-0.1.0/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+User-visible changes to ngh2 are recorded here.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-07-20
+
+### Added
+
+- Initial Python package for Sans-I/O HTTP/2 powered by libnghttp2.
+- Client and server connections, h2c upgrade, flow control, server push,
+  priority, extension frames, and typed protocol events.
+- Support for GIL-enabled CPython 3.10 through 3.14 and free-threaded CPython
+  3.14t.