README
¶
Vinculum
"The [vinculum is the] processing device at the core of every Borg vessel. It interconnects the minds of all the drones." -- Seven of Nine (In Voyager episode "Infinite Regress")
Vinculum is a no-code/low-code system for gluing together different systems and bridging multiple protocols. Think of it as a Swiss Army Knife for communications: while not the best tool for demanding tasks where you'd want a purpose-built solution, it handles a large variety of integration tasks adequately — letting you quickly MacGyver together a solution with a few lines of configuration.
Key Features
- HCL Configuration — Declarative configuration in HashiCorp Config Language (similar to Terraform), with constants, expressions, and assertions
- Git-Sourced Configuration — Pull configuration (and static assets, MCP resource files, etc.) from a pinned revision of a git repository at startup, instead of baking it into the image — pure-Go, so it works even in the scratch-based minimal image
- Publish/Subscribe Messaging — One or more event buses with MQTT-style topic routing, wildcards, and parameter extraction
- Server Protocols — HTTP(S), Vinculum WebSocket (VWS), plain WebSocket, Model Context Protocol (MCP), and Prometheus/OpenMetrics, with pluggable authentication (basic, OIDC, OAuth2)
- Client Protocols — HTTP(S), Kafka, MQTT, RabbitMQ (AMQP 0-9-1), Redis/Valkey (pub/sub, streams, key-value), AWS SQS, AWS SNS, VWS (to other Vinculum instances), OpenAI / LLM, and OpenTelemetry (OTLP) export
- SQL Databases — Query PostgreSQL, MySQL, and SQLite from config via the polymorphic
get()/call()functions, with named queries, positional and named parameters, and structured result objects; Postgres and MySQL are pure-Go (no cgo) - Triggers — A range of trigger types for time-, event-, and lifecycle-driven actions: cron, dynamic intervals with optional jitter, absolute / dynamic times, file-system events, OS signals, startup/shutdown, watchdogs, and watches over reactive values
- Conditions — Named boolean primitives with temporal rules (activate/deactivate delays, hysteresis, retentive timing, latches, cooldown, inhibit), covering IEC 61131-3 timer and counter function-block behaviors and composable into pipelines
- State Machines — Finite state machines with guarded transitions, reactive events, key-value storage, MQTT topic matching, and OpenTelemetry tracing; composable with conditions and watchable for reactive integration
- Transformations and Procedures — JQ-based message transforms, structured-text
editorblocks, andprocedureblocks for small imperative helpers - Built-in Functions — A large standard library covering HTTP, files, templates, time, randomness, IDs, LLMs, sunrise/sunset, geographic calculations, and more.
- Plugins — Load Go shared-object plugins (
.so) at startup to extend Vinculum with custom functions, transforms, server/client/trigger types, and more — using the same registration points as in-tree subsystems - Observability — Context propagation, OpenTelemetry tracing and metrics, and Prometheus exposition throughout
- Interactive REPL —
serve -idrops into a prompt that evaluates VCL expressions against the live, running configuration — read state, call functions, and send messages to real buses, with result history and tab completion
Documentation
See doc/overview.md for full documentation including:
- Core concepts (buses, topics, subscribers, transformations)
- Configuration language reference
- Protocol details
- Examples
Examples
The examples/ directory contains complete working configurations. See examples/README.md for the index, including a dynamic DNS zone updater that combines an HTTP server, basic authentication, a procedure, and a line-editor block to safely rewrite BIND zone files.
Related Projects
Vinculum is built on top of several standalone Go libraries that can be used independently:
| Project | Description |
|---|---|
| vinculum-bus | High-performance in-process EventBus with MQTT-style topic patterns and optional OpenTelemetry observability |
| vinculum-fsm | cty-native finite state machine library with guarded transitions, storage, topic matching, and tracing |
| vinculum-kafka | Kafka producer/consumer adapters that plug into a vinculum-bus EventBus |
| vinculum-mqtt | MQTT publisher/subscriber adapters that plug into a vinculum-bus EventBus |
| vinculum-rabbitmq | RabbitMQ (AMQP 0-9-1) sender/receiver adapters that plug into a vinculum-bus EventBus |
| vinculum-redis | Redis/Valkey pub/sub and streams adapters that plug into a vinculum-bus EventBus |
| vinculum-sns | AWS SNS sender adapter that plugs into a vinculum-bus EventBus |
| vinculum-sqs | AWS SQS sender/receiver adapters that plug into a vinculum-bus EventBus |
| vinculum-vws | Vinculum WebSocket Protocol — client and server for exposing an EventBus over WebSockets |
Vinculum also relies on several smaller standalone HCL/cty helper libraries: go2cty2go, hcl-jqfunc, go-structdiff, time-cty-funcs, rand-cty-funcs, and sqid-cty-funcs.
License
MIT License - see LICENSE file for details.
Vinculum (Latin: "bond" or "link") — connecting your systems with reliable, configurable messaging.
Documentation
¶
There is no documentation for this package.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
clients
|
|
|
http
Package http implements the `client "http"` block: a reusable HTTP client configuration that the http_* verb functions in package functions use to make outbound HTTP requests from action expressions.
|
Package http implements the `client "http"` block: a reusable HTTP client configuration that the http_* verb functions in package functions use to make outbound HTTP requests from action expressions. |
|
llm
Package llm provides shared types and helpers for LLM provider client implementations.
|
Package llm provides shared types and helpers for LLM provider client implementations. |
|
otlp
Package otlp provides the client "otlp" implementation, which configures the OpenTelemetry SDK with an OTLP/HTTP trace exporter.
|
Package otlp provides the client "otlp" implementation, which configures the OpenTelemetry SDK with an OTLP/HTTP trace exporter. |
|
rabbitmq
Package rabbitmq implements the `client "rabbitmq"` VCL block, wiring vinculum-rabbitmq senders and receivers into the vinculum config pipeline.
|
Package rabbitmq implements the `client "rabbitmq"` VCL block, wiring vinculum-rabbitmq senders and receivers into the vinculum config pipeline. |
|
redisstream
Package redisstream implements the `client "redis_stream"` block — a child of `client "redis"` that produces to and consumes from Redis Streams.
|
Package redisstream implements the `client "redis_stream"` block — a child of `client "redis"` that produces to and consumes from Redis Streams. |
|
sns
Package sns implements the `client "sns_sender"` block for vinculum's SNS integration.
|
Package sns implements the `client "sns_sender"` block for vinculum's SNS integration. |
|
sql
Package sql provides the dialect-agnostic engine shared by all SQL client blocks (`client "postgres"`, `client "mysql"`, `client "sqlite"`).
|
Package sql provides the dialect-agnostic engine shared by all SQL client blocks (`client "postgres"`, `client "mysql"`, `client "sqlite"`). |
|
sql/mysql
Package mysql registers the `client "mysql"` block.
|
Package mysql registers the `client "mysql"` block. |
|
sql/postgres
Package postgres registers the `client "postgres"` block.
|
Package postgres registers the `client "postgres"` block. |
|
sql/sqlite
Package sqlite registers the `client "sqlite"` block.
|
Package sqlite registers the `client "sqlite"` block. |
|
sqs
Package sqs implements the `client "sqs_sender"` and `client "sqs_receiver"` blocks for vinculum's SQS integration.
|
Package sqs implements the `client "sqs_sender"` and `client "sqs_receiver"` blocks for vinculum's SQS integration. |
|
Package conditions implements the condition "timer"/"threshold"/"counter" block family.
|
Package conditions implements the condition "timer"/"threshold"/"counter" block family. |
|
editors
|
|
|
Package repl implements Vinculum's interactive read-eval-print loop, reached via "vinculum serve -i".
|
Package repl implements Vinculum's interactive read-eval-print loop, reached via "vinculum serve -i". |
|
servers
|
|
|
auth
Package auth provides authentication middleware for vinculum servers.
|
Package auth provides authentication middleware for vinculum servers. |
|
triggers
|
|
|
Package version exposes build-time identity information about the vinculum binary.
|
Package version exposes build-time identity information about the vinculum binary. |
Click to show internal directories.
Click to hide internal directories.