fabric

Algoryn Fabric

The contract hub for the Algoryn ecosystem — shared types, events, and telemetry that keep Pulse, Relay, and upcoming tools (e.g. Beacon) aligned.

What is Fabric?

Fabric defines how Algoryn tools talk to each other: the same messages, fields, and semantics in Go and in binary serialization. Every product stands on its own, but when you combine them you avoid one-off adapters — the contract lives here.

Native Go contracts and Protocol Buffers

The algoryn.io/fabric/metrics and algoryn.io/fabric/events packages expose Go structs for straightforward integrations.

For high serialization throughput and cross-service traffic — for example environments producing telemetry and events from 100M+ requests per day — Fabric adds Protocol Buffers v3: compact messages, no JSON on the hot path, and interoperability with other languages and stacks (Kafka, gRPC, analytics stores, etc.).

• Idiomatic Go remains available for application code and tests.
• Protobuf is the canonical binary shape for fan-out, queues, and bulk storage.

The root fabric package also provides conversion.go: ToProto / FromProto helpers between legacy structs and generated messages.

Repository layout

fabric/
├── proto/
│   ├── fabric/v1/          # .proto definitions (metrics, events, common types)
│   └── third_party/        # Well-known types (e.g. google/protobuf/*.proto); build without system include tree
├── gen/go/fabric/v1/       # Go code generated by protoc (*.pb.go) — do not edit by hand
├── metrics/                # Go contracts (MetricSnapshot, RunEvent, …)
├── events/                 # Go contracts (Event, payloads, …)
├── conversion.go           # Legacy Go ↔ protobuf bridge
├── Makefile                # make proto
├── go.mod
└── README.md

Installation

go get algoryn.io/fabric

The official Go module is algoryn.io/fabric (see go.mod). Development is on GitHub at algoryn-io/fabric; imports in your code must use the module path, not the repository URL.

Importing generated messages (Protobuf)

import fabricv1 "algoryn.io/fabric/gen/go/fabric/v1"

func example() *fabricv1.MetricSnapshot {
    return &fabricv1.MetricSnapshot{
        Source:  "relay",
        Service: "api",
    }
}

Note: If you use replace or a different module path in a monorepo, adjust the import accordingly. A path like github.com/algoryn-io/fabric/... does not match the published module today unless you change go.mod explicitly.

Go-only packages (no Protobuf)

import (
    "algoryn.io/fabric/metrics"
    "algoryn.io/fabric/events"
)

Quickstart (legacy Go)

Consuming a Pulse event in Relay

import (
    "algoryn.io/fabric/events"
)

func handleRunEvent(e events.Event) {
    if e.Type != events.EventTypeRunCompleted {
        return
    }
    // e.Payload → JSON for events.RunCompletedPayload
}

Emitting a MetricSnapshot from Relay

import (
    "algoryn.io/fabric/metrics"
    "time"
)

snapshot := metrics.MetricSnapshot{
    Source:  metrics.SourceRelay,
    Service: "api-gateway",
    Window:  time.Minute,
    Total:   1500,
    Failed:  3,
    RPS:     25.0,
    Labels:  map[string]string{"route": "/api/users"},
}

Bridge to Protobuf

import (
    "algoryn.io/fabric"
    fabricv1 "algoryn.io/fabric/gen/go/fabric/v1"
    "algoryn.io/fabric/metrics"
)

var _ *fabricv1.RunEvent = fabric.RunEventToProto(metrics.RunEvent{})

Development

Regenerate .pb.go code

Requirements: protoc and protoc-gen-go (go install google.golang.org/protobuf/cmd/protoc-gen-go@latest).

Well-known types live under proto/third_party/; make proto does not rely on a global Protobuf include tree on the machine.

make proto

This regenerates gen/go/fabric/v1/*.pb.go from proto/fabric/v1/*.proto. Review the diff before committing; you can add a CI check for generation drift if needed.

See CONTRIBUTING.md for compatibility policy and changelog notes.

Compatibility

Fabric follows semantic versioning. While on v0.x.x, minor versions may ship breaking changes called out in CHANGELOG.md.

Ecosystem

License

MIT