membrane-config

# Membrane configuration generator Membrane is configured declaratively. The modern format is `apis.yaml`; a legacy Spring `proxies.xml` format also exists. This skill produces correct, idiomatic config by doing what a careful engineer does: copy the shape from a real working example, confirm exact attribute names against the schema, and validate before handing it over. Two sources of truth, and they play different roles: - **`distribution/tutorials/**/*.yaml`** — idiom and style. Heavily commented, curated, and the best examples in the repo. Treat these as gold. `distribution/examples/**` adds more (including `proxies.xml`). - **`membrane.schema.json`** — what's actually allowed: every element, its exact attribute names, enum values, and nesting. The model's main failure mode is inventing plausible-but-wrong attribute names; the schema is how you avoid that. Don't generate config from memory alone. The element set is large (~255 elements) and evolves; ground every snippet. ## Workflow 1. **Clarify intent only if needed.** What should the gateway do? Default to one `api` on port `2000` forwarding to a `target.url` unless the request implies otherwise. Don't over-ask — most requests map cleanly onto a known pattern. 2. **Find a close example.** Skim [references/cheatsheet.md](references/cheatsheet.md) for the matching pattern, then look at the real tutorial for the live version: ```bash grep -rl "rateLimiter:" distribution/tutorials distribution/examples ``` Reading the closest tutorial is the single highest-leverage step — it carries ordering, nesting, and conventions you'd otherwise guess at. 3. **Confirm exact attributes against the schema** for every non-trivial element. Guessing attribute names is the main way these configs go wrong: ```bash python3 scripts/describe_element.py rateLimiter # attributes + enums + children python3 scripts/describe_element.py --grep auth # discover element names python3 scripts/describe_element.py --list # all element ids ``` 4. **For any expression, template, or built-in function**, read [references/expressions.md](references/expressions.md) before writing it. The schema does **not** cover this, and it's the easiest place to be confidently wrong: which engine evaluates a string (`template` is Groovy, `setBody`/`if` default to SpEL), how you call a function (`${user()}` in SpEL vs. `${fn.user()}` in a Groovy template), which variables are in scope, and the full built-in catalog (`user()`, `base64Encode`, `hasScope`, `env`, …). These bugs surface as a runtime 500, not a schema error — `validate_config.py` won't catch them. 5. **Write the config** following the conventions below. 6. **Validate** (YAML only) — always, before presenting: ```bash python3 scripts/validate_config.py path/to/apis.yaml ``` Fix every reported problem and re-run until it passes. If you only produced a snippet, drop it into a minimal `api:` skeleton in a temp file and validate that, so you're confident the snippet is structurally sound. The scripts find the schema automatically: they prefer the locally built `core/target/classes/com/predic8/membrane/core/config/json/membrane.schema.json` and fall back to downloading the published `v7.4.0.json` (cached). They bootstrap their own dependencies on first run, so just call them. ## Conventions Match the tutorials so generated config looks native: - **Schema header.** Start full files with `# yaml-language-server: $schema=https://www.membrane-api.io/<version>.json` — it gives editors autocompletion and validation. Pin `<version>` to whatever the tutorials currently use (grep one: `grep -m1 schema= distribution/tutorials/*/*.yaml`), not a hardcoded number here — it tracks the current release and goes stale otherwise. - **One top-level key per document.** Each YAML document has exactly one root key (`api`, `global`, `configuration`, `soapProxy`, `sslProxy`). Separate multiple definitions with a `---` line. - **Default port 2000** (8443 for TLS), matching the tutorials. - **Comment with purpose.** Tutorials briefly say what a block does and, where useful, a `curl` line to try it. Add short comments in that spirit — explain intent, don't narrate syntax. - **Snippet vs. full file.** If the user asked for a snippet to drop into an existing config, return just the relevant `flow`/plugin block at the right indentation. If they asked for an example or a runnable config, return a complete file with the header and a `target` or `return`. ## Output Present the config in a fenced code block with `yaml` or `xml` as its info string. Below it, add a line or two on what it does and, when it makes the example concrete, how to run and test it (e.g. `./membrane.sh -c apis.yaml` then a `curl`). State that you validated it against the schema. If a requested feature isn't in the schema (the local build can lag the newest features — e.g. some AI plugins), say so and point to the tutorial you based it on instead of forcing it through validation. ## XML (proxies.xml) Only when the user explicitly asks for XML / proxies.xml / the Spring format. Same elements, camelCase tags, attributes instead of nested keys, wrapped in `<spring:beans>...<router>`. Ground it in a real `distribution/examples/**/proxies.xml`; see the XML section of [references/cheatsheet.md](references/cheatsheet.md). `validate_config.py` does not check XML, so lean harder on matching an existing example.