tether

package module
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 20, 2026 License: Apache-2.0 Imports: 17 Imported by: 0

README

Tether

Tether is an experimental reactive backend framework for Go. It automatically syncs your database queries with your frontend in real-time. No need to write custom WebSocket logic or manage complex state. Just write your queries, and Tether keeps your UI up to date.

[!WARNING] Tether is in early alpha. Its API may change without notice, and it has not been tested in production. Use it for experimentation, not production workloads.

Features

  • Real-time UI: Queries automatically update over WebSockets when data changes.
  • Smart Tracking: Automatically tracks dependencies for records loaded through GORM.
  • Client Libraries: First-class support for TypeScript and React.
  • Authentication: Built-in support for optional token-based auth (JWTs, session tokens, etc).
  • Database Support: Currently supports SQLite (PostgreSQL planned).

Getting started

Install the Go package:

go get github.com/recodeorg/tether
1. Define your models

Define a GORM model. Mark fields used to group records with tether:"track":

type Message struct {
	ID     uint   `gorm:"primaryKey"`
	Body   string
	RoomID string `tether:"track"`
}
2. Set up the backend

Create an engine, register your queries and mutations, and expose the WebSocket handler:

db, err := gorm.Open(sqlite.Open("app.db"), &gorm.Config{})
if err != nil {
	log.Fatal(err)
}

engine := tether.NewEngine(db, "sqlite")
engine.CreateTable("messages", &Message{})

// Queries automatically re-run and push updates when their dependencies change
engine.RegisterQuery("getMessages", func(ctx *tether.QueryCtx) interface{} {
	roomID := ctx.Params["room"].(string)
	ctx.TrackCollection("messages", "room_id", roomID)

	var messages []Message
	if err := ctx.DB.Where("room_id = ?", roomID).Find(&messages).Error; err != nil {
		return map[string]interface{}{"error": err.Error()}
	}
	return messages
}, []string{"messages"})

// Mutations automatically trigger updates for any affected queries
engine.RegisterMutation("createMessage", func(ctx *tether.MutationCtx) interface{} {
	message := Message{
		Body:   ctx.Params["body"].(string),
		RoomID: ctx.Params["room"].(string),
	}
	if err := ctx.DB.Create(&message).Error; err != nil {
		return map[string]interface{}{"error": err.Error()}
	}
	return message
})

http.HandleFunc("/tether", engine.Handle)
log.Fatal(http.ListenAndServe(":8080", nil))
3. Connect your frontend

You can use the companion React library to automatically bind queries to your UI:

import { useState } from "react"
import { useMutation, useQuery } from "@tetherdb/react"

export const App = () => {
	// useQuery automatically reflects the backend state in real-time!
    const data = useQuery("getMessages", { room: "1" })
	
    const [message, setMessage] = useState("")
    const [localError, setLocalError] = useState<string | null>(null)
    const { mutate, isPending } = useMutation("createMessage")

    const handleSendMessage = async () => {
        const result = await mutate({ room: "1", message })
        if (result.error) {
            setLocalError(result.error)
        }
        setMessage("")
    }

    return (
        <div>
            {data?.map((msg) => (
                <div key={msg.id}>{msg.sender?.name}: {msg.message}</div>
            ))}
            <input type="text" value={message} onChange={(e) => setMessage(e.target.value)} />
            <button onClick={handleSendMessage}>Send Message</button>
            {isPending && <div>Sending...</div>}
            {localError && <div>Error: {localError}</div>}
        </div>
    )
}

Or use the vanilla TypeScript client:

import { TetherClient } from "@tetherdb/client";

const client = new TetherClient();
client.connect("ws://localhost:8080/tether");

// The callback runs again whenever a message in the `general` room is created, updated, or deleted
client.subscribe("getMessages", { room: "general" }, (messages) => {
	console.log("Messages updated:", messages);
});

await client.sendMutation("createMessage", {
	room: "general",
	body: "Hello, Tether!",
});

How it works

Clients subscribe to named queries with a set of parameters. While a query runs, Tether records the rows and collections it depends on. When a mutation changes one of those dependencies, Tether reruns the affected query and sends the new result to each subscribed client.

Authentication

Authentication is optional. Implement the tether.Auth interface and pass it to engine.SetAuth. Tether associates the returned user ID and expiration time with the client's WebSocket connection.

Current status

Tether currently targets SQLite. PostgreSQL support, broader client support, API stabilization, and production hardening are still in progress.

License

Licensed under the Apache License 2.0.

Documentation

Index

Constants

View Source
const (
	ContextKeyExecutionID traceContextKey = "exec_id"
	ContextKeyActionName  traceContextKey = "action_name"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Auth

type Auth interface {
	VerifyToken(DB *gorm.DB, token string) (userID string, expiresAt time.Time, error error)
}

type AuthCtx

type AuthCtx struct {
	GetIdentity  func() (string, error)
	ExecuteGuard func(guardName string, params map[string]interface{}) (interface{}, error)
}

type Engine

type Engine struct {
	Profiler *utilities.Profiler
	// contains filtered or unexported fields
}

func NewEngine

func NewEngine(db *gorm.DB, dbType string) *Engine

func (*Engine) CreateTable

func (e *Engine) CreateTable(name string, schema interface{})

func (*Engine) ExecuteMutation

func (e *Engine) ExecuteMutation(mutation string, params map[string]interface{}, clientID string, mutationID string) (interface{}, error)

func (*Engine) ExecuteMutationInternal added in v0.3.0

func (e *Engine) ExecuteMutationInternal(mutation string, params map[string]interface{}) (interface{}, error)

func (*Engine) ExecuteQuery

func (e *Engine) ExecuteQuery(query string, params map[string]interface{}, subscription *reactivity.Subscription, forceSend bool) ([]byte, error)

func (*Engine) GetDependentQueries

func (e *Engine) GetDependentQueries(tableName string) []string

func (*Engine) Handle

func (e *Engine) Handle(w http.ResponseWriter, r *http.Request)

func (*Engine) InvalidateTag

func (e *Engine) InvalidateTag(tag string)

func (*Engine) InvalidateTags added in v0.2.0

func (e *Engine) InvalidateTags(tags []string, execID string, actionName string)

InvalidateTags re-runs each distinct subscription that listens to any of the given tags. Subscriptions are snapshotted before any query executes so a re-run that picks up additional tags (e.g. auto-tracked primary keys) cannot cause the same mutation to fire the query a second time. Matching subscriptions (same query, params, and auth fingerprint) share one execution and are fanned out with each client's own query_key.

func (*Engine) OnConnect

func (e *Engine) OnConnect(clientID string) error

func (*Engine) OnDisconnect

func (e *Engine) OnDisconnect(clientID string) error

func (*Engine) OnReceiveMessage

func (e *Engine) OnReceiveMessage(clientID string, msg map[string]interface{}) error

func (*Engine) RegisterGuard added in v0.4.0

func (e *Engine) RegisterGuard(name string, guard func(ctx *GuardCtx) interface{})

func (*Engine) RegisterMutation

func (e *Engine) RegisterMutation(name string, mutation func(ctx *MutationCtx) interface{}, opts ...MutationOptions)

func (*Engine) RegisterQuery

func (e *Engine) RegisterQuery(name string, query func(ctx *QueryCtx) interface{}, dependencies []string, opts ...QueryOptions)

func (*Engine) SetAllowedOrigins

func (e *Engine) SetAllowedOrigins(allowedOrigins []string)

Simple helper to set the allowed origins for the websocket connection

func (*Engine) SetAuth

func (e *Engine) SetAuth(auth Auth)

func (*Engine) SetCheckOrigin

func (e *Engine) SetCheckOrigin(checkOrigin func(r *http.Request) bool)

type Guard added in v0.4.0

type Guard struct {
	Func func(ctx *GuardCtx) interface{}
}

type GuardCtx added in v0.4.0

type GuardCtx struct {
	DB           *gorm.DB
	Auth         *AuthCtx
	Params       map[string]interface{}
	Profiler     *utilities.Profiler
	Dependencies []string
}

func (*GuardCtx) TrackCollection added in v0.4.0

func (c *GuardCtx) TrackCollection(tableName string, columnName string, value interface{})

func (*GuardCtx) TrackTable added in v0.4.0

func (c *GuardCtx) TrackTable(tableName string)

type Mutation added in v0.3.0

type Mutation struct {
	Func     func(ctx *MutationCtx) interface{}
	Internal bool
}

type MutationCtx

type MutationCtx struct {
	DB       *gorm.DB
	Auth     *AuthCtx
	Params   map[string]interface{}
	Profiler *utilities.Profiler
}

type MutationOptions added in v0.3.0

type MutationOptions struct {
	Internal bool
}

type Query added in v0.3.0

type Query struct {
	Func     func(ctx *QueryCtx) interface{}
	Internal bool
}

type QueryCtx

type QueryCtx struct {
	DB           *gorm.DB
	Auth         *AuthCtx
	Params       map[string]interface{}
	Dependencies []string
}

func (*QueryCtx) TrackCollection

func (c *QueryCtx) TrackCollection(tableName string, columnName string, value interface{})

func (*QueryCtx) TrackTable

func (c *QueryCtx) TrackTable(tableName string)

type QueryOptions added in v0.3.0

type QueryOptions struct {
	Internal bool
}

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL