Bloblang for VSCode

Syntax highlighting and full language intelligence for Bloblang — the mapping language of Bento and Warpstream (formerly Benthos) — powered by the blobl_lsp language server.

What is Bloblang?

Bloblang is the language Bento/Warpstream pipelines use to map, transform, and route structured messages. It lives either in standalone .blobl files or embedded in your pipeline's YAML config. If you write mapping:, bloblang:, or request_map: blocks, this extension is for you. See the Bloblang guide for the language itself.

Features

Works where your Bloblang lives

• Standalone .blobl files — full highlighting and language server support via a TextMate grammar derived from the blobl_sitter tree-sitter grammar.
• Embedded in YAML configs — the same highlighting and intelligence inside Bento/Warpstream YAML block scalars (bloblang, mapping, request_map, result_map, extract_tracing_map, fields_mapping, and any other |/> block), including the - key: | list-item form.

Completion

• Every builtin function and method, with inline documentation, triggered on . and ( or via Ctrl+Space.
• Argument snippets — accepting a function/method inserts placeholders for its parameters, ready to tab through.
• Construct snippets for multi-line language constructs (map, if, match, …).
• Language keywords (root, let, meta, import, …) complete too.

Hover

• Documentation for any builtin function or method.
• $variables and @metadata references show their declaration inline.
• Language keywords (root, this, match, …) come with explanations.

Go to definition

• $variable → its let declaration; @metadata → its meta assignment.
• .apply("name") → the named map declaration — even when it lives in an imported file.
• An import "./path.blobl" path → the imported file itself.

Diagnostics

• Parse errors surface as you type, with the error positioned where the parser failed — in .blobl files and in embedded YAML blocks alike.
• import statements pointing at files that don't exist are flagged (standalone files).

Formatting

• Canonical, gofmt-style formatting via Format Document or format-on-save — whole .blobl files and individual embedded YAML blocks.
• Fail-closed: code that doesn't parse is left untouched, so formatting never destroys a work-in-progress mapping.

Debugging

• Start a session from Run and Debug — the extension contributes a bloblang debug type. With no launch.json, the pre-seeded Debug mapping configuration debugs the current file (mapping: ${file}) and feeds it the first message of ${fileDirname}/${fileBasenameNoExtension}.json.
• Launch attributes:
  • mapping — a .blobl file, or a Bento/Warpstream YAML stream config (its bloblang block is debugged).
  • input — optional JSONL file of sample messages; the first message is debugged.
  • block — for YAML stream configs, which bloblang block to debug (1-based, default 1).
• Set breakpoints in .blobl files and inside embedded YAML blocks, then step through the mapping — the session is driven by the blobl-dbg debugger over the Debug Adapter Protocol.
• Unlike the language server, the debugger binary is not auto-downloaded: put blobl-dbg on your $PATH, or point bloblang.debugger.path at a binary you built from the blobl_dbg repo.

Requirements

The extension automatically downloads the matching blobl_lsp binary for your platform from the Codeberg releases on first activation, verifies its SHA-256, and stores it in the extension's global storage. No manual installation is needed.

| Setting | Default | Description | | --- | --- | --- | | bloblang.server.path | (empty) | Path to a `blobl_lsp` binary. Leave empty to use the managed download; set it to override with your own binary. | | `bloblang.trace.server` | `off` | Trace client/server communication. | | `bloblang.debugger.path` | (empty) | Path to the blobl-dbg debugger binary (serves DAP on stdio). Leave empty to use blobl-dbg from $PATH. |

Resolution precedence: an explicit bloblang.server.path → the managed downloaded binary → blobl_lsp on your $PATH (fallback if the download fails). Run Bloblang: Update Language Server from the command palette to force a re-download.

Note on activation. The extension activates on .blobl files and on all YAML files, so it can highlight and analyse Bloblang embedded in Bento/Warpstream configs. Highlighting applies to every multi-line block scalar (|/>), since the editor's YAML grammar does not let injections detect which key introduced a block. The language server self-gates on block position, so plain YAML without Bloblang blocks is left untouched.

Troubleshooting

• "Failed to download the Bloblang language server" — check your network access to codeberg.org, or set bloblang.server.path to a local binary, or put blobl_lsp on your $PATH. The extension retries on next activation; Bloblang: Update Language Server forces a fresh attempt.
• No completion/hover in a YAML file — the server only analyses recognised Bloblang block scalars; plain YAML is ignored by design.
• To see what the client and server are saying, set bloblang.trace.server to messages and check the Bloblang output channel.

Building the VSIX

npm install
npm run build
npm run package

Install the resulting .vsix with code --install-extension blobl-lsp-vscode-*.vsix.

Releasing

Publishing to the VS Code Marketplace and Open VSX is automated by the Forgejo Actions workflow in .forgejo/workflows/publish.yml, triggered when a vX.Y.Z tag is pushed. The tag must match the version in package.json.

# bump "version" in package.json + update CHANGELOG.md first, then:
git tag v0.3.0
git push origin v0.3.0

The workflow requires two repository secrets (Settings → Actions → Secrets), and Actions must be enabled for the repo with a runner labelled docker:

Development

Run the grammar snapshot tests and type-check:

npm test

Manual smoke test

The language-client wiring is verified by hand:

1. npm install && npm run build, then press F5 to launch the Extension Development Host.
2. Open a .blobl file — confirm keywords, strings, $vars, @metadata, and builtin calls are highlighted.
3. On first activation the extension downloads blobl_lsp for your platform; confirm completion (./(), hover, go-to-definition, formatting, and diagnostics work. (Set bloblang.server.path to test with a local binary instead.)
4. Open a Bento/Warpstream YAML config — confirm Bloblang inside bloblang:, mapping:, request_map:, etc. blocks is highlighted and gets diagnostics.