Ownwire Go SDK

A minimal Go SDK for connecting to an Ownwire backend over WebSockets, plus a small CLI example that demonstrates the SDK end-to-end.

The SDK handles:

• session creation and resumption
• cryptographic handshake
• encrypted message send/receive
• ordered delivery via sequence numbers

The CLI is intentionally simple and exists only as a working example.

---

Installation

Add the module to your project:

go get ownwire.net/ownwire-sdk

Then import it in your code:

import sdk "ownwire.net/ownwire-sdk"

---

Using the SDK

Creating a client and connecting

client := sdk.NewClient(sdk.ClientOptions{
	Url: "ws://localhost:8080/ownwire",
})

To connect and create a new session:

ctx := context.Background()
err := client.Connect(ctx, "")
if err != nil {
	log.Fatal(err)
}

To resume an existing session, pass the session ID:

err := client.Connect(ctx, "cb653f53-6f7d-4aeb-ba0d-d2b17c290d8a")

---

Receiving messages

The SDK uses channels in a Go-idiomatic way.

for ev := range client.Events() {
	switch ev.Kind {
	case sdk.EventOpened:
		fmt.Println("connection opened")

	case sdk.EventMessage:
		fmt.Println("received:", ev.Message.Content)

	case sdk.EventError:
		log.Println("error:", ev.Err)

	case sdk.EventClosed:
		fmt.Println("connection closed")
	}
}

All messages delivered via EventMessage are already decrypted.

---

Sending messages

err := client.Send(ctx, "hello world", "")
if err != nil {
	log.Println("send failed:", err)
}

Messages are automatically encrypted once the session handshake is complete.

---

Closing the connection

client.Close()

---

Example CLI

The repository includes a small CLI app that demonstrates the SDK working against a real Ownwire backend.

Building the CLI

From the repository root:

go build -o ownwire-cli ./example/cli

Running the CLI

./ownwire-cli -url ws://localhost:8080/ownwire

To resume an existing session:

./ownwire-cli -url ws://localhost:8080/ownwire -resume <session-id>

What the CLI demonstrates

• dialing an Ownwire WebSocket endpoint
• creating or resuming a session
• printing incoming messages
• sending stdin lines as encrypted messages
• clean shutdown on Ctrl-C

The CLI is intentionally minimal and meant only as a reference implementation.

---

Notes

• The SDK exposes only a small, stable API (Client, Event, Message).
• Internal protocol and crypto helpers are intentionally not documented as part of the public API.
• Unit tests cover handshake, crypto, and client behavior without requiring a server.