proxyfile

Commands

proxyfile render reads a proxyfile and writes the proxy's configuration, proxyfile check compares what it would write with the files on disk, proxyfile schema prints the JSON Schema of the format and proxyfile version prints the version. The README holds the usage text.

With no file, proxyfile reads Proxyfile, proxyfile.conf, proxyfile.yaml or proxyfile.yml from the working directory, and exactly one of them must exist.

Command What it does
render Reads the proxyfile, the files it includes, the origins file when it names one and the RPC methods, which come from one place: its rpc.methods, the .proto files its rpc.proto names, or, with --rpc-methods, the methods file. Writes the proxy's configuration to the -o path, and with --rpc-table the RPC table too, which needs one of the three. It writes every output only when the whole input is free of problems.
check Renders in memory and compares the bytes with the files on disk. It writes nothing. A missing output file differs.
schema Prints the JSON Schema of the proxyfile format on standard output.
version Prints proxyfile <version>.

--help, -h and help print the usage text on standard output and exit with 0.

The flags may stand before or after the file. --target names the proxy the configuration is for: envoy (the default), nginx or haproxy, and Portability has a column for each, with the keys it refuses. A proxyfile with an rpc entry (- rpc: in YAML, { rpc { ... } } in HOCON) takes its methods from exactly one of rpc.methods, rpc.proto and --rpc-methods, and methods given with no rpc entry are refused. --rpc-table needs one of the three. An output path may not name the proxyfile, a file it includes, its origins file, its methods file or a .proto file it reads, nor another output.

After render --target nginx or --target haproxy has written its files, it prints one line on standard error that counts the ways that output is less strict than the Envoy output, serving a request the Envoy output refuses or ends, or sending a service what the Envoy output would not, and names the page that lists them, with its exit code unchanged:

proxyfile render: this HAProxy configuration is less strict than the Envoy output in 11 ways; docs/haproxy.md lists them under "Where HAProxy is less strict than the Envoy output"

nginx's line names docs/nginx.md, HAProxy's docs/haproxy.md. A render for Envoy prints no such line, and neither does check.

The generated file starts with this line, and the same input always gives the same bytes:

# Generated by proxyfile. Do not edit: change the proxyfile beside it and run proxyfile render; proxyfile check fails on a hand edit.

Exit codes:

Code Meaning
0 The work is done, or the checked files match what render writes.
1 The input has problems and nothing is written, or a checked file differs (<path> differs from what proxyfile render writes), or a write fails.
2 A usage error. The message is printed with the usage text.

Each problem in the input is printed on standard error as <file>:<line>:<column>: <message>, as <file>:<line>: <message> when it has no column (a YAML syntax error names only its line, and one the YAML library places nowhere, such as an unknown anchor after the first line, names the file alone), or as <file>: <message> when it is about the file as a whole, such as a file that cannot be read. A HOCON file gives a line and column only for a syntax error, and names every other problem by its key path instead, as <file>: <key path>: <message> (see the HOCON form, which also says how a problem in an included file reads). Each problem is one line: a file whose name holds a control character is written in double quotes, and a control character in a message as its escape, such as \n. The proxyfile is read first, and a run that finds problems in it reports all the problems of the first stage that finds any: reading and syntax, then a key or a value that holds a control character, then the format of each key, then the rules that compare keys with each other. When the proxyfile is free of problems, the problems of the origins file, when origins names one, and of the methods are reported together. For example, a misspelled listen in a YAML file gives:

proxyfile.yaml:3:1: "listen" is required here
proxyfile.yaml:3:1: unknown key "liste"; known here: admin, auth, client_address, cors, dns, envoy, haproxy, limits, listen, log, nginx, origins, remove_from_clients, routes, rpc, services, timeouts, tls, tracing