Connector

The Connector is the base construct embedded in every Microbus microservice. A microservice extends the connector and declares a fixed set of feature types that together define its surface area - what other services can call it for, what events it emits or consumes, what runs on a schedule, and what it contributes to agentic workflows. Each feature is declared in code and reflected into the microservice’s manifest.yaml.

The Eight Features of a Microservice

1. Functional Endpoints

Typed request/response functions that make a microservice’s capabilities available to other microservices. They are the primary means of service-to-service communication. Inputs are extracted from the path, query string or JSON body; outputs are marshaled as JSON in the response body. Routes default to the function name in kebab-case and may include path arguments. Upstream callers reach functional endpoints through generated client stubs.

func (svc *Service) Add(ctx context.Context, x int, y int) (sum int, err error) {
    return x + y, nil
}

2. Web Handlers

Direct access to the http.ResponseWriter for serving HTML, static files or any response that needs control over the raw HTTP envelope. Like functional endpoints, web handlers can be restricted to a specific HTTP method or accept any method, and may take path arguments.

func (svc *Service) Dashboard(w http.ResponseWriter, r *http.Request) (err error) {
    return svc.WriteResTemplate(w, "dashboard.html", data)
}

3. Outbound Events

Fire-and-forget messages a microservice broadcasts to notify others of something that happened, without knowing who (if anyone) is listening. Outbound events use port :417 by default to differentiate them from regular endpoints. They decouple producers from consumers and let new consumers be added without changing the producer.

for range orderapi.NewMulticastTrigger(svc).OnOrderPlaced(ctx, orderID, total) {
}

4. Inbound Event Sinks

The other side of events: a sink subscribes to events emitted by another microservice. The sink’s signature must match the source event. Multiple sinks can listen to the same event, and a sink can rename its handler when two source services emit events with the same name.

func (svc *Service) OnOrderPlaced(ctx context.Context, orderID string, total float64) (err error) {
    svc.LogInfo(ctx, "New order received", "order", orderID, "total", total)
    return nil
}

5. Configuration Properties

Runtime settings a microservice declares for itself. Values are managed externally in config.yaml and delivered by the configurator core microservice. Supported types are string, bool, int, float64 and time.Duration. Validation rules are enforced before a new value is accepted. Microservices read values through generated accessors and may opt in to a callback that fires when a value changes.

configs:
  APIKey:
    type: string
    validation: str ^[A-Za-z0-9]+$
  MaxRetries:
    type: int
    default: 3

See Configuration for the full mechanics.

6. Tickers

Recurring scheduled jobs - useful for polling external systems, refreshing caches and running cleanup tasks. The framework hands each ticker a context that is canceled at shutdown so long-running iterations terminate gracefully.

tickers:
  RefreshRates:
    interval: 1h

func (svc *Service) RefreshRates(ctx context.Context) (err error) {
    // Fetch latest rates...
    return nil
}

See Tickers for details.

7. Workflow Tasks

A workflow task is a functional endpoint that performs a single step of an agentic workflow. It receives a *workflow.Flow carrier with access to the workflow’s shared state and control signals. Tasks read their inputs from the state, do their work, write their outputs back, and return - they have no knowledge of what comes before or after them. Tasks are registered on port :428 by default and are dispatched by the Foreman.

8. Workflow Definitions

A workflow is a directed graph of tasks defined in code by a microservice and exposed as an endpoint. Each node is a task or a reference to another workflow (a subgraph); edges are transitions that determine routing - unconditional, conditional on the state, goto for explicit jumps, fan-out for parallel branches, dynamic fan-out (forEach) over an array field, and fan-in that merges state changes from converging branches. The Foreman fetches the graph once when a flow is created and stores it alongside, so the definition is immutable for the lifetime of that flow.

Cross-cutting Capabilities

Beyond features that microservice authors define, the connector provides cross-cutting capabilities applied uniformly to every microservice:

• Transport - unicast, multicast, multiplexed connections, time budget, ack-or-fail, dynamic discovery, load balancing, locality-aware routing, connectivity-liveness.
• Observability - structured logging, distributed tracing, metrics (counter, gauge, histogram), error capture with full stack traces.
• Authorization - actor-based JWT authorization on incoming requests, expressed as boolean expressions over the actor’s claims.
• Embedded resources - images, scripts, templates and other static assets via FS.
• Internationalization (i18n) - localized display strings via text.yaml.
• Distributed cache - in-memory cache shared among replicas of a microservice.
• Graceful shutdown - drain pending requests, goroutines and jobs before the microservice quits.

Each is documented in its respective page.