envoyproxy / envoyproxy/examples
Split verification harness into a reusable module so standalone examples (e.g. wasm-cc) work outside the monorepo
- Lingua principale
- Shell
- Stelle
- 74
- Fork
- 38
- Merge medio
- 2g 17h
- PR unite (30g)
- 16
Descrizione
## Problem
Standalone example modules (starting with `wasm-cc`) only half-work as Bazel modules today:
- `wasm-cc/verify.sh` hard-codes the parent repo layout:
```bash
# shellcheck source=verify-common.sh
. "$(dirname "${BASH_SOURCE[0]}")/../verify-common.sh"
```
so it can only run from a sibling checkout of the root examples repo.
- `wasm-cc/BUILD` exposes `:configs`, `:files`, `:includes` and `:example.rst` (docs-facing targets) but nothing runnable.
- Everything a published example actually needs to *verify itself* — `verify-common.sh`, `verify_example.sh`, `verify_examples.sh`, `examples.bzl` (the `envoy_example` macro) and `shared/**` (python/node/golang/envoy Dockerfiles) — lives only in the root repo.
This is a follow-up, not a blocker for the initial `wasm-cc` module publication.
## Proposed split
### 1. `envoy_examples_common` module
A small module (e.g. `common/` in this repo with its own `MODULE.bazel`, published to the registry alongside the examples — or folded into `envoy_toolshed`, which is already a dep) containing:
- `verify-common.sh`, `verify_example.sh`, `verify_examples.sh`
- `shared/**`
- `examples.bzl` with the `envoy_example` macro
`envoy_example` grows a runnable target:
```starlark
def envoy_example(name, srcs = None, shared = "@envoy_examples_common//shared", **kwargs):
native.filegroup(name = "%s_files" % name, srcs = srcs or native.glob(["**/*"], exclude = [...]))
# tarball of example + shared/, same as today
native.genrule(name = "%s_dir" % name, ...)
sh_binary(
name = "verify",
srcs = ["@envoy_examples_common//:verify_example.sh"],
args = [name, "$(location :%s_dir)" % name],
data = [":%s_dir" % name],
tags = ["no-remote-exec", "no-sandbox"],
)
```
### 2. Example modules just declare themselves
```starlark
load("@envoy_examples_common//:examples.bzl", "envoy_example")
envoy_example(name = "wasm-cc")
```
and `verify.sh` sources the common lib via runfiles rather than `..`:
```bash
. "${VERIFY_COMMON:-$(dirname "${BASH_SOURCE[0]}")/../verify-common.sh}"
```
with `verify_example.sh` exporting `VERIFY_COMMON=$(rlocation envoy_examples_common/verify-common.sh)` before invoking `./verify.sh`. This keeps the in-tree path working while making `bazel run @envoy-example-wasm-cc//:verify` work from anywhere (envoy repo, user checkout, etc.).
### 3. Root examples repo becomes a consumer
`EXAMPLE_TESTS` calls the same macro for in-tree examples, and `verify_examples` aggregates `":%s_result"` targets plus externals like `@envoy-example-wasm-cc//:verify`. This also lets us remove the `"external"` path hacks in `examples.bzl` / `verify_example.sh`, since the tarball layout is owned by the macro.
## Open decisions (affect the module boundary)
- **`shared/` bloat** — the tarball currently includes all of `shared/` for every example. For standalone modules we probably want per-example selection, e.g. `envoy_example(shared = ["@envoy_examples_common//shared/python", ...])`, so `wasm-cc` doesn't drag in postgres/node Dockerfiles.
- **`example.rst` + `:configs`/`:includes`** — these are envoy-docs-facing and should stay in the example module, but the macro should ideally emit them too so a new example is literally one `envoy_example(...)` call.
## Immediate low-cost step
Land the `VERIFY_COMMON` indirection in `wasm-cc/verify.sh` now — it's a one-liner and removes the hard `../` coupling before the module gets published. The rest can follow.
## Tasks
- [ ] Add `VERIFY_COMMON` indirection to `wasm-cc/verify.sh`
- [ ] Create `envoy_examples_common` module (or fold into `envoy_toolshed`) with verify scripts, `shared/`, and `examples.bzl`
- [ ] Extend `envoy_example` macro with a runnable `:verify` target and optional per-example `shared` selection
- [ ] Switch `wasm-cc` to consume `@envoy_examples_common`
- [ ] Convert root repo to consume the macro and aggregate external example verify targets
- [ ] Remove `"external"` path hacks from `examples.bzl` / `verify_example.sh`
Guida per i contributori
Nessuna guida per i contributori indicizzata per questo repository
Valutazione
Questa issue non è ancora stata valutata.