Convert to an examples repo: curate to 4 teaching modules, strip distribution apparatus - #7
Merged
Merged
Conversation
…ribution apparatus
The official native-middleware modules are now compiled into the ePHPm binary,
so this repo becomes reference/teaching material for writing CUSTOM middleware
rather than a distribution registry.
- Curate to four self-contained examples covering the range:
- api-key request-phase auth gate (constant-time compare, KV lookup,
identity forwarding to PHP)
- redirect simplest early-return (canonical URL 301/308; no deps/KV)
- ratelimit KV-backed fixed-window limiter (kv_incr_ttl; fail-open),
keeps the fail-open integration test
- header-transform response phase (declare!(Type, response))
Each module's implementation is now inlined into its own crate's lib.rs
(impl + tests + declare! in one readable file); the shared
ephpm-middleware-modules impl crate and the impl/shell split (a
vendor-into-one-binary distribution concern) are removed.
- Remove the other modules (jwt, cors, security-headers, maintenance-mode,
ip-allowlist, request-id) — they ship inside ePHPm now.
- Strip the distribution apparatus: delete the per-platform build/publish
release.yml (SHA256SUMS + manifest.json generation) and drop the workspace
deps only those modules used (hmac, sha2, base64ct, ipnetwork).
- Keep a light ci.yml (fmt/clippy/test/release-build on PR + push) so the
examples don't rot; simplify its comments.
- Rewrite the README as a "how to write ePHPm native middleware" guide: the
versioned ABI, the declare! macro, request vs response phase (#408), KV
access, building a cdylib, and mounting it by explicit path or bare name via
the loader search path. Remove the removed `ephpm middleware get`/registry
content, and note the official modules are built into ePHPm.
fmt/clippy(-D warnings)/test/release-build all clean; all four cdylibs link.
ePHPm already ships built-in rate limiting (`[server.limits]`: per-IP/per-site, 429 + Retry-After), so a ratelimit middleware example would wrongly imply users should write their own instead of using the built-in. Curate to three examples: api-key, redirect, header-transform. - Remove the `ephpm-middleware-ratelimit` crate (impl, unit tests, and the fail-open integration test). `members = ["crates/*"]` drops the member automatically; no workspace dep was unique to it (subtle + ephpm-kv are still used by api-key). - README: remove the ratelimit table row, layout line, and testing/verdict mentions; the KV-access section now points at api-key (kv_get) as the KV example — the KV-usage teaching is preserved there. fmt/clippy(-D warnings)/test/release-build all clean; the three cdylibs link.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Convert
middleware→middleware-examplesThe official native-middleware modules are now compiled into the ePHPm binary (PR #410), so this repo is no longer a distribution registry. It becomes reference/teaching material: a small set of self-contained templates showing how to write your own custom ePHPm middleware.
Repo-level changes already applied (outside this PR): renamed
middleware→middleware-examples(GitHub auto-redirects the old name), updated description + topics, and deleted thev0.1.0-rc.1distribution pre-release.Curated to four teaching examples
Chosen to cover the range, not every use case. Each module's implementation is now inlined into its own crate's
lib.rs(impl + module docs + unit tests + the singledeclare!line), so a learner reads one file end to end. The sharedephpm-middleware-modulesimpl crate and the impl/shell split — which existed only to vendor every module into one binary, a distribution concern — are removed.api-key401redirect301/308; no deps, no KVratelimitkv_incr_ttl,429 + Retry-After, fail-open (keeps its fail-open integration test)header-transformdeclare!(Type, response), set request headers PHP sees + set/remove response headers outRemoved:
jwt,cors,security-headers,maintenance-mode,ip-allowlist,request-id— they ship inside ePHPm now.Stripped distribution apparatus
.github/workflows/release.yml(per-platform build/publish,SHA256SUMS+manifest.jsongeneration).hmac,sha2,base64ct,ipnetwork).ephpm middleware get/ fetch / registry / manifest content (that CLI is gone).Kept light so examples don't rot
ci.ymlretained: fmt / clippy (-D warnings) / test / release-build on every PR + push to main. Comments simplified (no longer references the deleted release workflow).Rewrote the README
Now a "how to write ePHPm native middleware" guide: what native middleware is, the versioned C ABI + the
declare!macro, request vs response phase (references ePHPm #408), KV access viareq.host(), building a cdylib, and mounting it by explicit path or bare name through the loader search path — with a clear note that the official modules are built into ePHPm and these are templates for custom modules.Verification (local, Windows)
cargo +nightly fmt --all -- --checkcleancargo clippy --workspace --all-targets -- -D warningscleancargo test --workspacegreen (incl. the ratelimitfail_openintegration test)cargo build --workspace --releaselinks all four cdylibsDo not merge yet — opened for review.