{"id":51043746,"url":"https://github.com/floatpane/go-uds-jsonrpc","last_synced_at":"2026-06-22T12:02:25.253Z","repository":{"id":361606177,"uuid":"1254430570","full_name":"floatpane/go-uds-jsonrpc","owner":"floatpane","description":"Tiny newline-delimited JSON-RPC over Unix domain sockets, for Go.","archived":false,"fork":false,"pushed_at":"2026-06-19T10:51:25.000Z","size":106,"stargazers_count":2,"open_issues_count":9,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-19T12:27:21.515Z","etag":null,"topics":["background-service","daemon","go","golang","golang-library","ipc","json-lines","json-rpc","jsonrpc","ndjson","pidfile","pubsub","rpc","server-push","single-instance","uds","unix-domain-sockets","unix-sockets","xdg","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://udsrpc.floatpane.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/floatpane.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"floatpane"}},"created_at":"2026-05-30T14:57:19.000Z","updated_at":"2026-06-04T19:18:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/floatpane/go-uds-jsonrpc","commit_stats":null,"previous_names":["floatpane/go-uds-jsonrpc"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/floatpane/go-uds-jsonrpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-uds-jsonrpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-uds-jsonrpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-uds-jsonrpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-uds-jsonrpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/floatpane","download_url":"https://codeload.github.com/floatpane/go-uds-jsonrpc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/floatpane%2Fgo-uds-jsonrpc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34647750,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["background-service","daemon","go","golang","golang-library","ipc","json-lines","json-rpc","jsonrpc","ndjson","pidfile","pubsub","rpc","server-push","single-instance","uds","unix-domain-sockets","unix-sockets","xdg","zero-dependencies"],"created_at":"2026-06-22T12:02:24.046Z","updated_at":"2026-06-22T12:02:25.226Z","avatar_url":"https://github.com/floatpane.png","language":"Go","funding_links":["https://github.com/sponsors/floatpane"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# go-uds-jsonrpc\n\n**Tiny newline-delimited JSON-RPC over Unix domain sockets, for Go.**\n\n[![Go Version](https://img.shields.io/github/go-mod/go-version/floatpane/go-uds-jsonrpc)](https://golang.org)\n[![Go Reference](https://pkg.go.dev/badge/github.com/floatpane/go-uds-jsonrpc.svg)](https://pkg.go.dev/github.com/floatpane/go-uds-jsonrpc)\n[![GitHub release (latest by date)](https://img.shields.io/github/v/release/floatpane/go-uds-jsonrpc)](https://github.com/floatpane/go-uds-jsonrpc/releases)\n[![CI](https://github.com/floatpane/go-uds-jsonrpc/actions/workflows/ci.yml/badge.svg)](https://github.com/floatpane/go-uds-jsonrpc/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\n\u003c/div\u003e\n\n`go-uds-jsonrpc` is what `net/rpc` should be in 2026: JSON on the wire, Unix-socket framing, server-pushed events, no gob, no reflection. It sits between `net/rpc` (too rigid) and gRPC (too heavy) for the very common case of *one daemon, several local clients, one machine*.\n\n## Features\n\n- **Three message shapes** — Request, Response, Event (server-pushed) — on one TCP-ish stream of `\\n`-terminated JSON.\n- **Cross-platform PID file + IsRunning** — Unix uses signal-0; Windows uses OpenProcess + GetExitCodeProcess.\n- **XDG-aware socket paths** — `$XDG_RUNTIME_DIR/\u003capp\u003e/` on Linux, `~/Library/Caches/\u003capp\u003e/` on macOS, sensible fallback on others.\n- **Server scaffolding** — handler registry, panic recovery, broadcast helpers, OnConnect / OnDisconnect hooks, context-driven shutdown.\n- **Signal handler** — SIGTERM/SIGINT → shutdown, SIGHUP → reload, both wired in one call.\n- **Zero dependencies.** stdlib-only.\n\n## Install\n\n```bash\ngo get github.com/floatpane/go-uds-jsonrpc\n```\n\nRequires Go 1.26+.\n\n## Usage\n\n### Server\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"encoding/json\"\n    \"log\"\n    \"net\"\n    \"os\"\n    \"os/signal\"\n    \"syscall\"\n\n    udsrpc \"github.com/floatpane/go-uds-jsonrpc\"\n)\n\nfunc main() {\n    const app = \"myd\"\n\n    if err := udsrpc.EnsureRuntimeDir(app); err != nil {\n        log.Fatal(err)\n    }\n    if pid, running := udsrpc.IsRunning(udsrpc.PIDPath(app)); running {\n        log.Fatalf(\"already running (PID %d)\", pid)\n    }\n    if err := udsrpc.WritePID(udsrpc.PIDPath(app)); err != nil {\n        log.Fatal(err)\n    }\n    defer udsrpc.RemovePID(udsrpc.PIDPath(app))\n\n    _ = os.Remove(udsrpc.SocketPath(app))\n    l, err := net.Listen(\"unix\", udsrpc.SocketPath(app))\n    if err != nil {\n        log.Fatal(err)\n    }\n    defer l.Close()\n\n    s := udsrpc.NewServer()\n    s.Handle(\"Ping\", func(_ context.Context, _ *udsrpc.Conn, _ json.RawMessage) (any, error) {\n        return map[string]bool{\"pong\": true}, nil\n    })\n\n    ctx, cancel := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)\n    defer cancel()\n    log.Println(s.Serve(ctx, l))\n}\n```\n\n### Client\n\n```go\npackage main\n\nimport (\n    \"encoding/json\"\n    \"fmt\"\n    \"log\"\n    \"net\"\n\n    udsrpc \"github.com/floatpane/go-uds-jsonrpc\"\n)\n\nfunc main() {\n    conn, err := net.Dial(\"unix\", udsrpc.SocketPath(\"myd\"))\n    if err != nil {\n        log.Fatal(err)\n    }\n    c := udsrpc.NewConn(conn)\n    defer c.Close()\n\n    if err := c.Send(\u0026udsrpc.Request{ID: 1, Method: \"Ping\"}); err != nil {\n        log.Fatal(err)\n    }\n    msg, err := c.ReceiveMessage()\n    if err != nil {\n        log.Fatal(err)\n    }\n    var result map[string]bool\n    json.Unmarshal(msg.Response.Result, \u0026result)\n    fmt.Println(\"pong:\", result[\"pong\"])\n}\n```\n\n### Push events from server to all clients\n\n```go\ngo func() {\n    for range time.Tick(5 * time.Second) {\n        s.Broadcast(\"Tick\", map[string]int64{\"unix\": time.Now().Unix()})\n    }\n}()\n```\n\nClients receive these as `Event` messages when they call `ReceiveMessage()`.\n\n## Wire format\n\nEvery message is one JSON object followed by `\\n`:\n\n```\n{\"id\":1,\"method\":\"Ping\",\"params\":{}}\n{\"id\":1,\"result\":{\"pong\":true}}\n{\"type\":\"Tick\",\"data\":{\"unix\":1748000000}}\n```\n\n`DecodeMessage` discriminates by inspecting the keys:\n\n- has `\"type\"`  → `Event`\n- has `\"method\"` → `Request`\n- otherwise → `Response`\n\nStandard error codes (borrowed from JSON-RPC 2.0):\n\n| Code     | Constant              | Meaning                  |\n|----------|-----------------------|--------------------------|\n| `-32700` | `ErrCodeParse`        | Invalid JSON received    |\n| `-32600` | `ErrCodeInvalidReq`   | Not a valid Request      |\n| `-32601` | `ErrCodeNotFound`     | Method not registered    |\n| `-32602` | `ErrCodeInvalidParams`| Method exists, bad params|\n| `-32603` | `ErrCodeInternal`     | Handler error            |\n\nReturn an `*Error` from a handler to forward a specific code/message to the client. Any other non-nil error becomes `ErrCodeInternal` with the message.\n\n## Documentation\n\nFull API reference: [pkg.go.dev/github.com/floatpane/go-uds-jsonrpc](https://pkg.go.dev/github.com/floatpane/go-uds-jsonrpc)\n\n## Contributing\n\nPRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Security\n\nReport vulnerabilities privately via [SECURITY.md](SECURITY.md).\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloatpane%2Fgo-uds-jsonrpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffloatpane%2Fgo-uds-jsonrpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffloatpane%2Fgo-uds-jsonrpc/lists"}