Development¶

Build and test¶

make deps        # OpenResty 1.31.1.1, Test::Nginx, graphql-js, toml-test, in .deps/ (no sudo)
make             # build/libgql.so + build/gqlc
make test        # everything below except Docker and fuzzing
make docker-test # the image, two gateways, memcached, a mock backend
make fuzz        # libFuzzer, FUZZ_TIME=60 seconds per target
make bench       # wrk: naive vs @batch vs @batch + @cache

System packages (Ubuntu): build-essential libpcre2-dev libssl-dev zlib1g-dev (to build OpenResty), memcached, cpanminus, nodejs npm (graphql-js), python3 (toml-test), clang llvm libclang-rt-dev (fuzzing), wrk (bench), docker.io docker-buildx docker-compose-v2.

What the tests cover¶

flowchart LR
    subgraph c ["C"]
        tc["make test-c<br/>unit tests, ASan + UBSan"]
        tt["make test-toml<br/>toml-test 1.1.0 corpus"]
        to["make test-oracle<br/>graphql-js 17 as the reference"]
        fz["make fuzz<br/>parser, queries, TOML, config"]
    end
    subgraph cfg ["configuration"]
        tcf["make test-config<br/>error cases, golden renderings,<br/>documentation examples, openresty -t"]
    end
    subgraph rt ["runtime"]
        tn["make test-t<br/>Test::Nginx: HTTP, execution,<br/>batching, cache, limits, metrics,<br/>generated configuration"]
        dk["make docker-test<br/>the image end to end"]
    end

Continuous integration¶

.github/workflows/ci.yml runs on pull requests (and on demand), not on branch pushes:

A new push to the pull request cancels the previous run. Runs from forks wait for a maintainer's approval, and main only accepts pull requests whose four checks passed.

Releasing¶

flowchart LR
    v["bump _VERSION<br/>(lua/gqlgw/init.lua)<br/>+ CHANGELOG.md section"] --> pr["pull request, CI green, merge"]
    pr --> tag["git tag vX.Y.Z<br/>git push origin vX.Y.Z"]
    tag --> chk["release.yml: tag = _VERSION,<br/>changelog entry, make docker-test"]
    chk --> img["ghcr.io/abusi/gqlgw:X.Y.Z, X.Y, latest<br/>amd64 + arm64, provenance attestation"]
    img --> rel["GitHub release<br/>notes = the changelog section"]

The release workflow refuses a tag that does not match _VERSION, or a version without a ## [X.Y.Z] section in CHANGELOG.md.

Documentation¶

The site is built with Zensical from docs/ and zensical.toml, and published to GitHub Pages by .github/workflows/docs.yml on every push to main.

python3 -m venv .venv && .venv/bin/pip install -r requirements-docs.txt
.venv/bin/zensical serve          # http://localhost:8000, live reload
.venv/bin/zensical build --strict # site/

Diagrams are Mermaid code blocks. Configuration examples are included from examples/ with --8<-- "path", so they are tested by make test-config.

Layout¶