envoyproxy / envoyproxy/examples

Split verification harness into a reusable module so standalone examples (e.g. wasm-cc) work outside the monorepo

Open
#1,399 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
Shell
Stars
74
Forks
38
Avg merge
2d 17h
Merged PRs (30d)
16

Description

## 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`

Contributor guide

No contributing guide indexed for this repository

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.