gateway: move deployment into SAR macro

[alessandrobologna]

Closes #16

Summary

This changes Khone::Gateway::Service from a config-publisher-only macro resource into the deployable gateway resource. Application stacks still bring their own Lambda Managed Instances capacity provider ARN, but the macro now owns the gateway Lambda, execution role/policy, Function URL, config publisher, and optional log group.

The bootstrap app is prepared for SAR installation: release automation builds the arm64 gateway zip, uploads it to a versioned S3 key, renders the bootstrap template with that artifact location, packages the SAR application, publishes it, and can privately share it with the AWS Organization.

Background

The previous deployment model required every consumer stack to carry the gateway source path and define a local GatewayFunction block. That made examples and benchmark stacks depend on CodeUri: ../../gateway, duplicated IAM/Function URL wiring, and made versioned gateway rollout a consumer concern.

This moves the versioned gateway package into the SAR-installed bootstrap/macro layer while keeping capacity management external and explicit.

What Changed

• Khone::Gateway::Service now expands into an AWS::Lambda::Function under the original logical ID.
• The macro generates:
  • <Gateway>KhoneConfigPublisher
  • <Gateway>KhoneExecutionRole
  • <Gateway>KhoneFunctionUrl
  • <Gateway>KhoneFunctionUrlPermission for public Function URLs
  • <Gateway>KhoneLogGroup when retention is configured
• The execution role includes CloudWatch Logs, generated-config S3 read access, and target Lambda invoke permissions derived from Spec.paths.*.*.x-target-lambda.
• The macro accepts intrinsic target ARNs, dedupes target resources, rejects invalid literal target ARNs, and preserves documented string numeric route settings.
• bootstrap/template.yaml now includes SAR metadata and gateway artifact parameters consumed by the macro Lambda environment.
• Added SAR release/version scripts and publish-release.yml.
• Updated README, deploy docs, reference docs, benchmark stack, examples, and website copy to remove local gateway source-path deployment.

Workflow Event Flow

publish-release.yml runs on push tags matching v* and on manual workflow_dispatch with release_tag and share_scope inputs.

For tag pushes, the workflow checks out GITHUB_SHA; for manual runs, it checks out refs/tags/<release_tag>. The job has permissions: { contents: read, id-token: write }, uses actions/checkout with persist-credentials: false, and assumes the configured AWS role through OIDC.

The release path validates VERSION and bootstrap/template.yaml SemanticVersion, builds the gateway zip, uploads it to khone/releases/<version>/gateway/bootstrap.zip, captures the S3 object version when available, renders bootstrap/template.release.yaml, runs sam validate, sam build, sam package, then sam publish with the exact semantic version.

For share_scope=organization, the workflow reads the existing SAR application policy, replaces only the share-org statement, and writes the merged policy back so unrelated sharing statements are preserved.

Expected rerun behavior: rerunning the same semantic version after a successful sam publish may fail because SAR versions are immutable; artifact upload uses a versioned key and object version when the bucket supports it. Partial failures before sam publish can be rerun for the same tag after fixing the failure condition.

Validation

• python3 -m unittest bootstrap/tests/test_gateway_macro.py bootstrap/tests/test_config_publisher.py
• cargo lambda build --release --arm64 --output-format zip -p khone-gateway
• sam validate --template-file bootstrap/template.yaml --lint
• sam build --template-file bootstrap/template.yaml
• actionlint .github/workflows/publish-release.yml
• workflow YAML parse
• bash -n scripts/normalize-yaml-scalar.sh scripts/set-version.sh
• shellcheck scripts/normalize-yaml-scalar.sh scripts/set-version.sh
• python3 -m py_compile scripts/render-bootstrap-release-template.py
• npm ci --prefix benchmark --ignore-scripts
• npm test --prefix benchmark
• local jq SAR policy-merge simulation
• live AWS canary deploy of khone-bootstrap and adapter-node with an existing LMI capacity provider; verified generated resources, Lambda LMI config, Function URL, and HTTP 200 responses for buffered and streaming routes

[Copilot]

Pull request overview

This PR shifts the Khone deployment model so the SAR-installed bootstrap macro owns the deployable gateway (Lambda, role/policy, Function URL, config publisher, optional log group), while application stacks only supply target Lambdas and an existing Lambda Managed Instances (LMI) capacity provider ARN. It also adds release automation to publish a versioned gateway zip and the SAR bootstrap application, and updates templates/docs/examples/benchmark tooling to match the new contract.

Changes:

• Expand Khone::Gateway::Service into a full gateway deployment surface (Lambda + IAM + URL + config publisher) instead of config-publisher-only.
• Add SAR release workflow + helper scripts to build/upload the gateway artifact and publish/share the SAR app.
• Update examples, benchmark stack/tooling, website copy, and docs to remove local CodeUri: ../../gateway usage and reference generated resources.

Reviewed changes

Copilot reviewed 29 out of 30 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
website/app/page.tsx	Updates homepage copy and YAML snippet to reflect macro-owned gateway deployment.
scripts/set-version.sh	Adds helper to bump repo VERSION and bootstrap template SemanticVersion.
scripts/render-bootstrap-release-template.py	Renders a release bootstrap template with immutable gateway artifact defaults.
scripts/normalize-yaml-scalar.sh	Normalizes YAML scalars for workflow metadata validation/parsing.
README.md	Updates deployment model and quickstart instructions for SAR/gateway artifact flow.
Makefile	Adds bootstrap deploy parameters for gateway artifact S3 coordinates.
examples/sam/templates/native-batch-node/template.yaml	Migrates example from explicit gateway Lambda to Khone::Gateway::Service properties + new outputs.
examples/sam/templates/layer-proxy-python/template.yaml	Same migration for Python layer-proxy example.
examples/sam/templates/layer-proxy-node/template.yaml	Same migration for Node layer-proxy example.
examples/sam/templates/adapter-rust/template.yaml	Same migration for Rust adapter example.
examples/sam/templates/adapter-node/template.yaml	Same migration for Node adapter example.
docs/start/quickstart.md	Updates bootstrap steps to include SAR install or artifact upload for source bootstrap deploys.
docs/reference/configuration.md	Updates KHONE_CONFIG_URI wiring description and clarifies intrinsic x-target-lambda support.
docs/reference/bootstrap-macro.md	Documents the new gateway resource contract and generated logical IDs.
docs/deploy/sam-gateway.md	Updates “SAM gateway” guide to the macro-owned gateway model and new outputs/permissions behavior.
docs/deploy/release.md	Adds release documentation for SAR + gateway artifact publishing workflow.
docs/deploy/lmi-deployment-model.md	Updates architecture/deployment model to reflect macro-owned gateway Lambda.
docs/deploy/index.md	Adds links for SAR bootstrap install and release docs; updates descriptions.
docs/deploy/examples.md	Updates example deployment prerequisites/notes for SAR artifact settings.
docs/deploy/bootstrap-sar.md	Adds SAR installation guide for the bootstrap application.
bootstrap/tests/test_gateway_macro.py	Expands macro unit tests to validate generated Lambda/IAM/URL/log group resources and validations.
bootstrap/template.yaml	Adds SAR application metadata and gateway artifact parameters wired into macro Lambda env vars.
bootstrap/README.md	Updates bootstrap README for SAR defaults vs source-deploy parameter passing.
bootstrap/gateway_macro/app.py	Implements macro expansion into Lambda gateway resources + IAM policy generation and validations.
benchmark/test/report.test.ts	Updates expected gateway logical ID from GatewayFunction to GatewayService.
benchmark/test/render.test.ts	Updates expected gateway logical ID for chart title context.
benchmark/src/charts/echarts/specs.ts	Updates gateway metadata lookup key to GatewayService.
benchmark/sam/template.yaml	Migrates benchmark stack from explicit gateway Lambda to Khone::Gateway::Service + updated outputs/targets.
.gitignore	Ignores generated release artifacts (bootstrap/template.release.yaml, /release/).
.github/workflows/publish-release.yml	Adds release workflow to build/upload gateway zip, package/publish SAR app, and optionally org-share it.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated 1 comment.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 30 changed files in this pull request and generated no new comments.