Tractatus contains the canonical transport proto files, generated Go bindings, and helper packages (envelope, transport) that every bobrapet operator, SDK, Engram, and connector relies on. Keeping these contracts in a dedicated repo makes it easy to lint, version, and publish checked-in Go bindings plus release bundles for other language targets.

• HubService.Process is the hub-facing bidirectional stream for DataPacket traffic.
• TransportConnectorService.Data, Control, and HubPush are the connector-side bidirectional streams used by SDKs and sidecars.

go get github.com/bubustack/tractatus

import (
    "encoding/json"

    transportpb "github.com/bubustack/tractatus/gen/go/proto/transport/v1"
    "github.com/bubustack/tractatus/envelope"
)

// conn is a grpc.ClientConnInterface and ctx is already in scope.
client := transportpb.NewHubServiceClient(conn)
stream, _ := client.Process(ctx)

env := &envelope.Envelope{
    Payload: json.RawMessage(`{"message":"hello"}`),
}
frame, _ := envelope.ToBinaryFrame(env)

_ = stream.Send(&transportpb.ProcessRequest{
    Packet: &transportpb.DataPacket{
        Frame: &transportpb.DataPacket_Binary{Binary: frame},
    },
})

The Go bindings are checked in to this repo, so consumers do not need protoc or buf installed.

make lint          # golangci-lint for helper packages
make test          # Go unit tests
make buf-lint      # Buf lint on proto definitions
make buf-breaking  # Compatibility diff against the local main baseline
make generate      # Regenerate tracked Go bindings under gen/go

All commands rely on the Buf CLI and Go 1.25.1+. The lint (.github/workflows/lint.yml) and test (.github/workflows/test.yml) workflows run the same checks on every push and pull request.

When a proto change lands, run:

make proto-dist

This target:

1. Regenerates the Go bindings under gen/go.
2. Uses buf.gen.release.yaml to emit ecosystem-ready packages:
   • dist/release/go/ — Go module bindings (proto + gRPC).
   • dist/release/ts/ — TypeScript outputs via ts-proto (gRPC JS clients).
   • dist/release/python/ — Python protobuf + gRPC stubs.
3. Builds a descriptor set (dist/release/descriptors/tractatus.bin).
4. Copies the raw proto/ tree, Buf templates, README, and LICENSE into dist/release/.
5. Bundles everything into dist/tractatus-protos.tar.gz for manual distribution when we build non-Go SDKs.

Releases currently focus on the Go module (indexed automatically by pkg.go.dev). When a GitHub Release is published, the Publish Proto Bundle workflow builds dist/tractatus-protos.tar.gz and uploads it to the release automatically. Extending buf.gen.release.yaml with new plugins is all that’s required to add more language targets.

We use release-please to manage version bumps and GitHub Releases. On pushes to main, the workflow updates or opens the release PR; merging that PR cuts the tag and GitHub Release. pkg.go.dev picks up the new tag automatically, and the proto bundle is uploaded by the release workflow chain.

• Contributing guide
• Support
• Discord
• Security policy
• Code of Conduct

Copyright 2025 BubuStack.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.