iomesh-client-sdk-go

README

I/O Mesh Client SDK for Go

Official Go client SDK for the I/O Mesh broker and connector platform.

Official open-source tooling from IOMesh (IOMesh Technology Ltd.).

Capability	Package
HTTP publish / pull subscribe / streams / KV / memory	iomeshclient
Partner webhook HMAC + observation envelopes	connectorsdk
Kafka protocol (Produce subset)	kafka · via iomeshclient.KafkaClient
Shared envelope + CUID helpers	envelope · cuid

Module path: github.com/iome-sh/iomesh-client-sdk-go
Package: iomeshclient
Env prefix: IOMESH_*
Wire headers: X-IOMesh-Tenant, X-IOMesh-Org, X-IOMesh-Workspace, …
Status: public OSS v0.3.x (pre-1.0). Memory M2/M3 + multi-tenant headers aligned with iomesh-tui.

Requirements

• Go 1.22+ (module declares the toolchain used in CI)
• Network access to an I/O Mesh broker (or local foundation)

Install

go get github.com/iome-sh/iomesh-client-sdk-go@latest

Quick start — connect and publish

package main

import (
	"context"
	"log"

	"github.com/iome-sh/iomesh-client-sdk-go/iomeshclient"
)

func main() {
	nc, err := iomeshclient.Connect(
		iomeshclient.Options{URL: "http://127.0.0.1:8422"},
		iomeshclient.WithTenant("dept.engineering"),
		iomeshclient.WithOrg("acme-org"),
		iomeshclient.WithWorkspace("ws_default"), // multi-tenant metering / entitlements
	)
	if err != nil {
		log.Fatal(err)
	}

	ctx := context.Background()
	if err := nc.CreateStream(ctx, iomeshclient.StreamConfig{
		Name:     "EVENTS",
		Subjects: []string{"dept.engineering.events.>"},
	}); err != nil {
		log.Fatal(err)
	}

	ack, err := nc.Publish(ctx, "EVENTS", "dept.engineering.events.demo", []byte(`{"hello":"mesh"}`))
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("published seq=%d subject=%s partition=%d", ack.Seq, ack.Subject, ack.Partition)
}

Connector SDK (HMAC + envelope)

import "github.com/iome-sh/iomesh-client-sdk-go/connectorsdk"

payload, err := connectorsdk.NormalizeEnvelope(
	"acme-crm", "engineering", "acme-crm", "evt-42", "contact.created",
	json.RawMessage(`{"email":"user@example.com"}`),
)

See examples/connector-sdk-template/ for a full webhook adapter (IOMESH_URL, IOMESH_ORG, …).

Kafka Produce

kc := iomeshclient.NewKafkaClient("127.0.0.1:9423")
defer kc.Close()

offset, err := kc.Produce(ctx, "mesh.finance.events", 0, []byte("key"), []byte(`{"event_id":"evt-1"}`))

Memory (async streams + sync sidecar)

API	Path	Notes
PublishMemoryIngest	MEMORY_INGEST publish	Async dual-write; temporal fields on MemoryEnvelope
RequestMemoryRecall / RequestMemoryRecallFull	MEMORY_RPC publish	Async; Full adds session_id correlation
RetrieveMemory	POST /v1 then /v5/memory/retrieve	Sync hits; empty query OK if session_id set
IngestMemoryTurn	POST /v1 then /v5/memory/ingest	Sync Palace turn write

// Sync retrieve (sidecar URL or gateway that routes /v1|/v5/memory/*)
hits, err := nc.RetrieveMemory(ctx, iomeshclient.MemoryRetrieveRequest{
	TenantID:  "dept.research",
	Query:     "lease rotation",
	SessionID: "dept.research.mesh-dogfood",
	Limit:     8,
})
// hits.Path is "/v1/memory/retrieve" or "/v5/memory/retrieve"

The agent harness (iomesh-tui) mirrors these surfaces without depending on this module (lean public HTTP).

Security

• Report vulnerabilities privately: SECURITY.md (GitHub Security Advisory or security@iome.sh).
  Do not open public issues for exploits.
• Do not commit API tokens, broker URLs with credentials, or customer payloads into issues/PRs.
• Prefer short-lived bearer tokens (WithBearerToken) and tenant-scoped headers (WithTenant / WithOrg / WithWorkspace).
• Broker URLs must be absolute http/https (no file://, no embedded userinfo).
• Connector HMAC secrets must stay server-side; never embed partner secrets in mobile or browser clients.
• Treat X-IOMesh-Tenant / X-IOMesh-Org as an authorization boundary — enforce server-side.

Versioning & support

• Semantic versioning (vMAJOR.MINOR.PATCH).
• Breaking changes only in major versions; see CHANGELOG.md and RELEASING.md.
• Supported Go versions: last two stable releases (CI matrix).
• Help channels: SUPPORT.md.

Development

go test ./...
go test -race ./...
golangci-lint run ./...   # if installed

This repository is pure client code — no private platform dependencies. Unit tests use httptest and local helpers. Live broker integration belongs in your environment or private test harnesses, not in this public tree.

Public naming: packages, env vars, and wire headers use iomesh / IOMESH_* / X-IOMesh-*. Internal monorepo codenames are not part of this SDK.

Process docs: CONTRIBUTING · SUPPORT · RELEASING · docs/OPEN_SOURCE_AUDIT.md.

Related

Link	Role
iome.sh	Product / marketing site & documentation
Upcoming	iomesh-client-sdk-ts, iomesh-client-sdk-python, …

License

MIT © 2026 IOMesh Technology Ltd. — see also NOTICE.

Maintained by IOMesh Technology Ltd. · Product: iome.sh · Support: SUPPORT.md