Skip to content

Add four marquee examples + e2e CI against goja-enabled OSS gateway#1

Merged
sedkis merged 5 commits into
mainfrom
feat/multi-hook-examples-and-e2e
May 28, 2026
Merged

Add four marquee examples + e2e CI against goja-enabled OSS gateway#1
sedkis merged 5 commits into
mainfrom
feat/multi-hook-examples-and-e2e

Conversation

@sedkis

@sedkis sedkis commented May 4, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • Adds one marquee example for each remaining hook type (auth_check, post_key_auth, post, response); the previous repo had only pre. Four of five examples were AI-authored from the public docs (AGENTS.md + types.d.ts + JWS) — the fifth was promoted from the live AI-generation experiment.
  • Adds an end-to-end CI scaffold at `e2e/` that runs every example against a real Tyk gateway in Docker. Five `tests/*.sh` scripts exercise the gateway with curl + assert plugin behaviour on the wire (signature presence, 401/200 dispatch, redaction, header propagation, key-driven session metadata).
  • Closes type and doc gaps the AI generation loop surfaced: `ReturnAuthData` accepts `Partial` (no more `as any`), AGENTS.md hook table now lists the right return helper / manifest shape / `require_session` per hook, and a Web Crypto shim section documents the `crypto.getRandomValues` workaround for libs like `uuid`.

Test plan

  • Local `npm test` for each of the five examples (3+5+5+6+6+6 tests, all green)
  • Local `npx tsc --noEmit` clean across starter + every example
  • Local `npm run build:bundle` produces a valid checksummed `bundle.zip` for each example
  • Local `bash e2e/run.sh` — 5/5 plugins load via `prefix=jsvm-goja` and pass their assertions (target: ~5–10 min on first run because the gateway image is built; ~30 s on warm runs)
  • GitHub Actions `test.yml` — matrix runs unit + bundle-build for all five examples
  • GitHub Actions `e2e.yml` — clones the goja branch (`TT-16948-...goja`) on `TykTechnologies/tyk`, builds the gateway image, runs the e2e suite. May need a `TYK_GW_TOKEN` repo secret if the goja branch is in a private repo and the default `GITHUB_TOKEN` can't read it.

Notes for reviewers

  • The published Tyk OSS image (v5.7) ships otto, not goja, so it can't run plugins that use `globalThis` or un-down-transpiled ES2015+ from npm deps. The e2e overlay (`e2e/gateway.Dockerfile` + `build-gateway-image.sh`) cross-compiles the goja branch and lays it on top of v5.7. Once goja merges to main and a public image with `driver: "javascript"` ships, delete the overlay and switch `docker-compose.yml` to use the public tag directly.
  • Two non-obvious gateway behaviours documented while wiring this: (1) `auth_check` requires `enable_coprocess_auth: true` on the API def, otherwise built-in AuthKey rejects pre-plugin; (2) `auth_check` is a singular manifest object, not an array — every other hook is an array.

🤖 Generated with Claude Code

sedkis and others added 5 commits May 4, 2026 15:24
The starter previously had one marquee example covering the `pre` hook
(jws-request-signing). Add an example for each of the other four hook
types and an end-to-end CI scaffold that runs all five against a real
Tyk gateway in Docker.

Examples (each: TS plugin, vitest unit tests, webpack ES5 bundle):
- auth-check-hmac (auth_check) — replace built-in auth with HMAC-SHA256
  signature validation; uses ReturnAuthData with a constructed session
- post-key-auth-tenant-context (post_key_auth) — read session.meta_data
  to inject X-Tenant-Id; demonstrates require_session: true
- post-correlation-id (post) — preserve inbound or generate UUID v4;
  ships a Web Crypto shim because goja lacks crypto.getRandomValues
- response-pii-redaction (response) — mask SSN-shaped patterns in
  response bodies; AI-authored from public docs as the original
  generation-loop validation

E2E (`e2e/`):
- docker-compose: redis + python http.server (bundle host) + tyk
- gateway.Dockerfile + build-gateway-image.sh: cross-compiles the
  goja branch and overlays it onto tykio/tyk-gateway:v5.7. Reason:
  the published image still ships otto, which doesn't support
  globalThis or un-down-transpiled ES2015+ from npm deps. When goja
  merges to main, delete the overlay and switch to the public tag.
- stage-bundles.mjs: discovers each example's dist/bundle.zip,
  recomputes checksum, stages into bundles/<slug>.zip
- apps/<slug>.json + tests/<slug>.sh: per-example API def + curl-
  based assertion. tenant.sh creates a real session via
  /tyk/keys/create REST API to drive the post_key_auth path.
- run.sh: builds the gateway image if missing, brings up the stack,
  polls /hello, runs every tests/*.sh, tears down.

CI:
- .github/workflows/test.yml — matrix expanded from 1 to 5 examples
- .github/workflows/e2e.yml — clones the goja branch via configurable
  TYK_GW_REF, builds the image, runs the e2e suite, uploads per-
  example bundles AND a combined bundles-${SHA}.zip aggregate; gateway
  logs uploaded on failure; step summary table by hook

Types + AGENTS.md (gaps surfaced by the AI generation loop):
- ReturnAuthData second arg widened to Partial<TykSession> so
  auth_check plugins constructing a minimal session no longer need
  `as any` casts (auth-check-hmac cleaned up accordingly)
- AGENTS.md hook table now lists the right return helper, manifest
  shape (array vs singular), and require_session expectation for each
  hook. Two gotchas called out explicitly: auth_check is a singular
  manifest object (not an array), and require_session must be true
  for hooks reading session.* data.
- New Web Crypto shim section documents the crypto.getRandomValues
  pattern with a copy-pasteable implementation; post-correlation-id
  is the canonical worked example.

Validation status:
- All 5 examples: tsc clean, vitest green, webpack builds, valid bundle
- Local e2e: 5/5 pass against goja-enabled gateway in Docker

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Types now ship as a published package
(https://www.npmjs.com/package/@tyk-technologies/tyk-plugin-types)
rather than a bundled src/types.d.ts. Each plugin entry references
the package via `/// <reference types="..." />`, and every
package.json depends on `^0.1.0` so the same audited type surface
(handler shape, request/session/response, globals like
TykMakeHttpRequest, manifest constants) is shared across the
starter, all examples, and any consumer's project.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
pre-trace-id is the minimal pre-hook example: stamp X-Trace-Id on every
request. Useful as a baseline tracing header and as the second bundle
in the multi-bundle composition demo.

multi-bundle.json + multi-bundle.sh exercise custom_middleware_bundles
end-to-end: two pre-hook bundles (pre-trace-id and jws-request-signing)
on the same API, asserted by upstream headers. Both bundles export a
global named `handler`; the gateway aliases each export under a
per-(file, name) IIFE so they coexist without colliding.

Docs sweep: README, examples/README, e2e/README updated to document
the composition pattern and drop stale "coming soon" framing.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Tyk collapsed the multi-bundle array field back into the existing
custom_middleware_bundle string (commit 637e337a7), which now accepts
"a.zip,b.zip" syntax. Update the e2e API def, all example/README/test
prose, and the multi-bundle test comment to match. No behaviour change
to the underlying composition flow.

Also marks e2e/run.sh executable.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@sedkis
sedkis merged commit a70f291 into main May 28, 2026
7 checks passed
@sedkis
sedkis deleted the feat/multi-hook-examples-and-e2e branch May 28, 2026 18:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant