147 lines
2.6 KiB
Markdown
147 lines
2.6 KiB
Markdown
# 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:
|
|
|
|
```sh
|
|
go get ownwire.net/ownwire-sdk
|
|
```
|
|
|
|
Then import it in your code:
|
|
|
|
```go
|
|
import sdk "ownwire.net/ownwire-sdk"
|
|
```
|
|
|
|
---
|
|
|
|
## Using the SDK
|
|
|
|
### Creating a client and connecting
|
|
|
|
```go
|
|
client := sdk.NewClient(sdk.ClientOptions{
|
|
Url: "ws://localhost:8080/ownwire",
|
|
})
|
|
```
|
|
|
|
To connect and create a **new session**:
|
|
|
|
```go
|
|
ctx := context.Background()
|
|
err := client.Connect(ctx, "")
|
|
if err != nil {
|
|
log.Fatal(err)
|
|
}
|
|
```
|
|
|
|
To **resume an existing session**, pass the session ID:
|
|
|
|
```go
|
|
err := client.Connect(ctx, "cb653f53-6f7d-4aeb-ba0d-d2b17c290d8a")
|
|
```
|
|
|
|
---
|
|
|
|
### Receiving messages
|
|
|
|
The SDK uses channels in a Go-idiomatic way.
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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
|
|
|
|
```go
|
|
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:
|
|
|
|
```sh
|
|
go build -o ownwire-cli ./example/cli
|
|
```
|
|
|
|
### Running the CLI
|
|
|
|
```sh
|
|
./ownwire-cli -url ws://localhost:8080/ownwire
|
|
```
|
|
|
|
To resume an existing session:
|
|
|
|
```sh
|
|
./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.
|