HAProxy Language Support

Schema-driven language support for HAProxy configuration files in Visual Studio Code and compatible editors.

Open any .cfg file and get syntax highlighting, context-aware completion, inline documentation, log-format intelligence, schema-based diagnostics, rename symbol, symbol hover on references, go to definition and find all references (including cross-file navigation and rename when the workspace graph is active), document formatting, and section outline — all tuned to the HAProxy release you run in production. Community LTS 2.6, 2.8, 3.0, 3.2, and 3.4 are supported, plus HAProxy Enterprise (HAPEE) LTS 2.6r1, 2.8r1, 3.0r1, and 3.2r1.

Features

Syntax highlighting

Colorization is generated from HAProxy's own keyword inventory (haproxy -dKall), not hand-maintained lists. Sections, directives, ACLs, sample expressions, and related constructs are scoped consistently across large configs.

Intelligent completion

Suggestions follow where you are in the file:

• Global and section headers (global, defaults, frontend, backend, listen, …), including partial matches on new top-level lines (fron → frontend)
• Directives and keywords valid for the current section
• option / default-server values, HTTP/TCP rule actions, ACL criteria
• bind and server parameters, stick-table keys, filter/trace arguments
• Sample fetches and converters inside expressions
• Runtime variables — names previously set with set-var / set-var-fmt (and standard scopes proc., sess., txn., req., res., check.) inside set-var(, unset-var(, var(, and %[var(
• Log-format aliases and flags inside format strings (see Log-format support below)
• Enum argument values where the schema defines allowed choices (e.g. mode tcp|http)

Completion reloads immediately when you change the configured HAProxy version or edition.

Inline documentation

Hover any supported keyword to read summaries sourced from HAProxy's official configuration.txt. Many entries include a link to the upstream HAProxy documentation for the full reference. Conditional block directives (.if, .elif, .else, .endif) and status directives (.diag, .notice, .warning, .alert) are documented as well, and hovers distinguish section scope such as Valid in sections: defaults, frontend, listen, backend from mode scope such as Valid in modes: tcp, http, log when available.

• bind / server line options — nested sub-options (e.g. source … interface), manual ASCII tables rendered as markdown
• Rule actions — parenthesized actions (set-var(...)) and sample fetches (req.hdr(...)) show distinct documentation
• Examples from the manual where available
• Symbol references — hover a backend name, ACL, server, defaults profile, runtime variable (var(txn.foo) / %[var(txn.foo)]), or other indexed reference to preview the defining line or full section body in a code block, with a Peek Definition link

Log-format support

Format strings in directives such as log-format, error-log-format, unique-id-format, set-var-fmt, and log-format-sd get dedicated language support:

• Completion of log-format aliases and {+flag} modifiers inside format strings
• Hover on aliases and flags (including combined modifiers like {+Q+E})
• Diagnostics for unknown aliases or flags

Real-time diagnostics

Catch common mistakes while you type:

Diagnostics are schema-based — they help you write valid-looking config faster, but they do not replace haproxy -c for a full syntax check. Context checks use the effective runtime mode inferred from your section/config flow, but you should still validate with your real binary before deploying.

Suppress a specific same-line diagnostic with # haproxy: ignore=<code>, for example # haproxy: ignore=unknown-action or # haproxy: ignore=unknown-action,unknown-keyword. This is useful for third-party or runtime module keywords that the selected community or HAPEE schema does not include, and diagnostics offer a Quick Fix to add or extend the ignore comment automatically.

Missing-reference warnings (on by default via haproxy.diagnostics.missingReferences) flag named references with no matching definition — ACLs, backends, cache, userlist, resolvers, peers, named defaults profiles, and runtime variables (var(...) / unset-var(...)). When the workspace symbol graph is active, definitions in other indexed .cfg files satisfy the reference; environment variables are never flagged (external $VAR names without a setenv in the graph simply have no jump target).

Unused symbol hints (on by default via haproxy.diagnostics.unusedSymbols) fade unused ACL lines (full-line), unused set-var / set-var-fmt lines, and unreferenced section blocks (backends, named defaults, cache, userlist, resolvers, peers) — similar to unused-code hints in Ty or Pylance. Server lines are not flagged; use-server is optional and pool members are valid without it. Frontends and listens without a bind or bind-process directive (including inherited defaults in the same file) are reported as warnings because they cannot accept connections. When the workspace symbol graph is active, a backend referenced from another file is not reported as unused. With the graph disabled or over configured limits, analysis falls back to the current file only. The graph indexes workspace files by glob — it does not follow HAProxy include directives or detect runtime-only references (including variables set or read from Lua).

Document formatting

Run Format Document (or enable format-on-save) to normalize layout according to HAProxy's configuration file rules:

• Section headers (global, frontend, …) stay left-aligned; directives inside a section are indented consistently.
• Comments and quoted strings are preserved; inline # comments stay on the same line.
• Optional blank lines are inserted before each new section header.
• Multiple blank lines between sections collapse to one; trailing blank lines at end of file are removed.
• Format Selection preserves intra-line spacing in the selected range for minimal diffs while still normalizing section indent.

Indent style (4 spaces, 2 spaces, or tab) and blank-line behavior are configurable — see Settings below.

Outline and folding

Navigate large configs with built-in structure support:

• Outline — lists every top-level section (frontend www, backend api, …) so you can jump quickly.
• Folding — collapse a section's body while keeping its header visible.

Workspace symbol graph

Split HAProxy layouts — separate files for frontends, backends, ACLs, or shared defaults — are indexed into a workspace symbol graph (on by default via haproxy.workspaceSymbols.enabled):

• Discovery — matches workspace .cfg files using haproxy.workspaceSymbols.include (default **/*.cfg), excluding common build/vendor paths. In a multi-root workspace, each VS Code folder is a separate graph with its own file/line/byte limits
• Cross-file Go to Definition and Find References — jump from use_backend api in one file to backend api in another, or from $FOO to setenv FOO; reference lists include usages across indexed files
• Cross-file symbol diagnostics — missing-reference and unused-section checks consult workspace definitions, so a backend, named section, or setenv used only from another file is not flagged
• Duplicate section warnings — warns when the same named frontend, backend, listen, defaults profile, cache, userlist, resolvers, or peers block is defined in more than one indexed file
• Limits and fallback — when disabled or when configured opt-in file, line, or byte limits are exceeded for a VS Code workspace folder, navigation, rename, and symbol diagnostics in that folder fall back to single-file behavior

The graph rebuilds after workspace file changes (debounced via haproxy.workspaceSymbols.debounceMs). It indexes files on disk in the workspace — not HAProxy include paths.

Glob discovery vs HAProxy -f load order

The workspace symbol graph is built from VS Code glob patterns (haproxy.workspaceSymbols.include, optional haproxy.workspaceSymbols.roots, and exclude). This is not the same as the file list HAProxy loads with haproxy -f file or haproxy -f /etc/haproxy.d/:

Use haproxy.workspaceSymbols.roots to narrow discovery inside a workspace folder to known config trees (for example haproxy.d or etc/haproxy). It does not create a separate graph per subdirectory; put independent configs in separate VS Code workspace folders. Narrow include when unrelated .cfg files share names and would collide on cross-file rename.

Go to definition, find references, and rename

Jump across related config with standard editor navigation (Go to Definition, Go to References, Rename Symbol, peek view):

• Frontends / backends / listen — use_backend, default_backend, and section headers link to the matching proxy section; Go to Definition on a section highlights the full section body, not just the header line
• ACLs — definitions and uses in if / unless conditions within the same section (including negated forms like !is_api), chained implicit-AND references (if is_static !is_image), inline { … } conditions, and compound && / || expressions
• Servers — server lines and use-server references inside a backend or listen
• Defaults profiles — defaults … from <profile> links to the named profile
• Filters, cache, userlist, resolvers, peers — section and statement definitions indexed from the schema
• Environment variables — setenv / presetenv definitions and references from unsetenv / resetenv, double-quoted $VAR / ${VAR} / ${VAR-default} / ${VAR-sub}, and env(VAR) sample fetches. With the workspace graph active, Go to Definition, Find References, and Rename follow those names across indexed .cfg files
• Runtime variables — set-var / set-var-fmt definitions and var(...) / %[var(...)] / unset-var(...) references (file-wide and across the workspace graph). Hover on the name peeks the defining set-var line; hover on set-var / var still shows action and fetch docs
• Rename Symbol (F2) — with the workspace graph active, rename updates matching definitions and references across indexed .cfg files for backends, ACLs, defaults profiles, servers, filters, environment variables, runtime variables, and related named sections. Invalid names and same-scope collisions (including an existing name in another indexed file) are rejected

Reference resolution is schema-driven via reference patterns in the bundled language data, not hardcoded heuristics. With the workspace graph active, definitions, references, and rename can span multiple .cfg files. Narrow scope with haproxy.workspaceSymbols.include or disable workspace symbols when independent configs share names — duplicate section names across unrelated files can make cross-file rename affect more than you intend. When the graph is disabled or over configured limits, rename falls back to the current file

Getting started

1. Install the extension from the Marketplace (or load a .vsix locally).
2. Open a HAProxy config (.cfg extension is recognized automatically; # line comments, bracket matching, and auto-closing pairs are enabled). For cross-file navigation and workspace symbol diagnostics, open a workspace folder containing your .cfg files.
3. Choose your HAProxy version and edition so completion, hover, diagnostics, formatting, and highlighting match your deployment (see below).

No extra runtime is required for day-to-day editing — schemas and grammars ship with the extension. If bundled schema or language data fails to load, the extension shows a one-time error notification.

HAProxy version and edition

Pick the community or Enterprise release that matches the binaries you operate:

HAPEE (HAProxy Enterprise) is a separate edition of the matching LTS: pick 3.2 HAPEE (or 2.6 / 2.8 / 3.0 HAPEE) in the version picker, or set haproxy.edition to hapee. That loads the haproxy-X.Yr1 schema, language data, and TextMate grammar, including core Enterprise syntax and release-gated modules (WAF, response-body injection, UDP, SAML, Captcha, Bot Management, OIDC, and RHI). Community OSS 3.4 has no HAPEE artifacts yet.

Schemas for 2.6 and 2.8 are generated from the legacy configuration.txt layout (actions listed under each ruleset in §4.2 rather than §4.3/§4.4). Completion, diagnostics, and hover reflect keywords available in that release.

Ways to change version and edition:

• Status bar — click HAProxy while a .cfg file is active.
• Command Palette — run HAProxy: Select HAProxy Version and Edition.
• Settings — set HAProxy: Version (haproxy.version) and HAProxy: Edition (haproxy.edition).

Completion, diagnostics, hover, and highlighting update as soon as the setting changes. Syntax highlighting switches the active TextMate grammar (haproxy-3.2 vs haproxy-3.2r1); if colors do not refresh, use Developer: Reload Window when prompted.

Settings

The extension also raises editor.maxTokenizationLineLength for HAProxy files so long server / bind lines tokenize correctly.

Pre-0.12 settings haproxy.format.indentStyle and haproxy.format.indentSize are still honored as a fallback when haproxy.format.indent is unset.

Commands

How it works

Language data is built offline from upstream sources:

1. configuration.txt — descriptions and documentation structure per community HAProxy release.
2. haproxy -dKall — the complete keyword list emitted by the matching OSS binary.
3. HAPEE configuration manuals — Enterprise HTML for 2.6r1–3.2r1, merged on top of the OSS base.

Those inputs are merged into JSON schemas, completion/hover payloads, and TextMate grammars (see the companion haproxy-schema repository). The VS Code extension loads the bundled artifacts for the version and edition you select — no Python or local HAProxy install needed to use the extension.

Performance

The extension is built for interactive editing. The table below shows median timings from our automated micro-benchmarks (npm run bench) on Node.js 24 - they exercise the same TypeScript code paths as the extension host, using bundled schemas and synthetic .cfg fixtures.

What this means in practice

• Everyday configs (hundreds to a few thousand lines) stay responsive: diagnostics, completion, and hover are sub-millisecond to low tens of milliseconds per operation.
• Incremental diagnostics are now the fast path during editing. On the 24k-line stress fixtures, a single-line edit revalidates in about 20 ms without unused-symbol hints and 25 ms with them enabled. The same edits take about 236 ms and 361 ms respectively when forced through a full recompute baseline.
• Diagnostics still dominate full-pass cost on very large files - the main reason haproxy.diagnostics.maxLines defaults to 4000 and very large files skip validation unless you raise that limit. CI guards the incremental stress-edit path at p99.5 under 45 ms without unused-symbol hints and 40 ms with them (robust thresholds from 21 CI runs), while full-pass stress benchmarks remain guarded separately.
• Highlighting scales with file size; the editor tokenizes incrementally, so the stress numbers above are a full-file worst case, not what you pay on every keystroke. Grammars are line-isolated (no begin/end region may carry state past end-of-line), so tokenization cost reflects correct per-line highlighting even when earlier lines contain deliberate syntax errors.
• Stress fixtures: large-valid.cfg (mostly valid) tokenizes at ~2.2 s median; large-mixed.cfg (valid baseline plus injected invalid lines every ~5 blocks) at ~1.8 s median. The p99.5 tokenization thresholds are 2.7 s and 2.2 s respectively.
• Startup pays a one-time ~19 ms JSON parse when the extension first loads language data for your selected HAProxy version and edition; the p99.5 threshold is 30 ms.

CI runs these benchmarks on every push (npm run bench:ci) and tracks regressions against test/bench/thresholds.json. To reproduce locally:

npm run bench

[^1]: Measured with vscode-textmate against the shipped grammar - a proxy for editor highlighting cost.

[^2]: After haproxy.diagnostics.debounceMs (default 500 ms) following each edit in the real editor.

Report issues

Found a false positive, missing completion, or wrong hover text? Open an issue on GitHub.

Required information — issues without these details are hard to reproduce and may be closed:

1. Offending config — paste the exact line(s) or a minimal snippet that triggers the problem (redact secrets; keep structure intact).
2. Error or unexpected behavior — copy the full diagnostic message from the Problems panel, or describe what you expected vs. what happened (e.g. no squiggle, wrong completion list).

Helpful context (include when relevant):

• HAProxy: Version (haproxy.version) and HAProxy: Edition (haproxy.edition) — e.g. 3.2 community or 3.2 HAPEE
• Extension version and editor (VS Code version)
• Whether haproxy -c accepts or rejects the same config on your binary

Contributing

The extension repo is self-contained for CI: unit and integration tests use bundled schemas under schemas/ and config snippets under test/fixtures/. No sibling checkout is required to run npm test or npm run test:coverage.

Schema generation and upstream config corpus validation live in the companion haproxy-schema repository. Optional monorepo checkouts are only for regeneration and extended local validation:

parent/
  haproxy-vscode/     # this extension (CI runs here)
  haproxy-schema/     # schema & grammar generator (python -m haproxy_schema)
  haproxy_git/        # optional: upstream HAProxy trees for regeneration & test:upstream
    haproxy-2.6/
    haproxy-2.8/
    haproxy-3.0/
    haproxy-3.2/
    haproxy-3.4/

Extension

From haproxy-vscode/:

npm install
npm run compile

compile only builds TypeScript. HAProxy version-specific schema/language data is loaded at extension startup from haproxy.version (default 3.2) and haproxy.edition (default community), and grammar switching is handled by the extension when the version or edition changes.

Use Run HAProxy Extension in the Run and Debug view after compiling.

Lint and format (enforced in CI):

npm run lint
npm run format:check
npm run format    # auto-fix formatting

npm test

Runs Vitest unit tests and VS Code Extension Development Host integration tests. Tests load bundled schemas and fixtures from test/fixtures/ (including curated upstream snippets in test/fixtures/golden/). For coverage only:

npm run test:coverage

For extended local validation (grammar check, full upstream scans, haproxy -c comparison) when sibling repos are present:

npm run test:all

Optional upstream-only scripts (require sibling haproxy_git/):

npm run test:upstream
npm run compare:haproxy:matrix
npm run compare:haproxy:docker:matrix

compare:haproxy:matrix runs haproxy -c parity checks for all supported versions (2.6, 2.8, 3.0, 3.2, 3.4) against matching upstream tests/conf directories. compare:haproxy:docker:matrix uses Docker images haproxy:<version>-trixie as ground truth and checks both tests/conf/*.cfg and examples/*.cfg for each version.

For a single version, call the script directly:

node scripts/compare-haproxy-c.mjs --version 3.2

To run schema pytest plus extension tests from a monorepo layout:

.\haproxy-schema\scripts\test-all.ps1

Regenerating schemas

Set PYTHONPATH to the haproxy-schema repo root, then from haproxy-vscode/:

$env:PYTHONPATH = (Resolve-Path "..\haproxy-schema").Path
npm run generate:schema
npm run compile

generate:schema regenerates every supported community version (2.6, 2.8, 3.0, 3.2, 3.4), then the HAPEE schema, language, and grammar files (haproxy-X.Yr1.*). Community grammars stay in haproxy-X.Y.tmLanguage.json; HAPEE grammars are written to haproxy-X.Yr1.tmLanguage.json. You can regenerate one community version with npm run generate:schema:<version> or all HAPEE artifacts with npm run generate:schema:hapee. HAPEE source downloads are checksum-pinned; an upstream manual change stops generation until it is reviewed and deliberately pinned. To refresh keyword dumps (requires a DEBUG build of the matching HAProxy binary in haproxy_git/):

npm run generate:dkall:2.6
npm run generate:dkall:2.8
npm run generate:dkall:3.2

See haproxy-schema README for dkall generation, binary installation, pytest, and upstream golden-config validation.

Packaging

npm run package

Produces a .vsix via @vscode/vsce (vscode:prepublish compiles TypeScript automatically).

License

MIT. See NOTICE for third-party and data-source attributions.

Bundled files under schemas/ and syntaxes/ are generated from HAProxy configuration.txt and haproxy -dKall output via the companion haproxy-schema project (Apache-2.0). Community documentation excerpts in hover and completion payloads are derived from HAProxy's official configuration reference (GPL-2.0-or-later). HAPEE artifacts additionally use the Enterprise configuration manuals published at haproxy.com. Keyword-line parsing in haproxy-schema is aligned with haproxy-dconv (Apache-2.0).