{"id":25428245,"url":"https://github.com/xizhibei/go-reverse-rpc","last_synced_at":"2025-06-26T07:04:04.271Z","repository":{"id":221943465,"uuid":"721030556","full_name":"xizhibei/go-reverse-rpc","owner":"xizhibei","description":"A remote procedure call (RPC) framework designed for connecting to devices remotely.","archived":false,"fork":false,"pushed_at":"2025-06-23T13:48:03.000Z","size":337,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-06-23T14:25:59.278Z","etag":null,"topics":["json","mqtt","protobuf","reverse-rpc","rpc","rpc-framework"],"latest_commit_sha":null,"homepage":"","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/xizhibei.png","metadata":{"files":{"readme":"Readme.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-11-20T08:08:01.000Z","updated_at":"2025-06-23T13:40:21.000Z","dependencies_parsed_at":"2024-06-21T14:11:52.115Z","dependency_job_id":"f988dbe6-50ca-4d67-98a3-a678522f56f9","html_url":"https://github.com/xizhibei/go-reverse-rpc","commit_stats":null,"previous_names":["xizhibei/go-reverse-rpc"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/xizhibei/go-reverse-rpc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xizhibei%2Fgo-reverse-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xizhibei%2Fgo-reverse-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xizhibei%2Fgo-reverse-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xizhibei%2Fgo-reverse-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/xizhibei","download_url":"https://codeload.github.com/xizhibei/go-reverse-rpc/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/xizhibei%2Fgo-reverse-rpc/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262018759,"owners_count":23245619,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["json","mqtt","protobuf","reverse-rpc","rpc","rpc-framework"],"created_at":"2025-02-17T01:38:22.153Z","updated_at":"2025-06-26T07:04:04.263Z","avatar_url":"https://github.com/xizhibei.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Go reverse RPC\n\nA remote procedure call (RPC) framework designed for connecting to devices remotely. It enables the \"server\" to call functions provided by the \"client\". This inverted model is particularly useful for devices behind firewalls or NATs that can't accept incoming connections.\n\n[![Build Status](https://github.com/xizhibei/go-reverse-rpc/actions/workflows/go.yml/badge.svg)](https://github.com/xizhibei/go-reverse-rpc/actions/workflows/go.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/xizhibei/go-reverse-rpc)](https://goreportcard.com/report/github.com/xizhibei/go-reverse-rpc)\n[![GoDoc](https://pkg.go.dev/badge/github.com/xizhibei/go-reverse-rpc?status.svg)](https://pkg.go.dev/github.com/xizhibei/go-reverse-rpc?tab=doc)\n\u003c!-- [![codecov](https://codecov.io/gh/xizhibei/go-reverse-rpc/branch/master/graph/badge.svg)](https://codecov.io/gh/xizhibei/go-reverse-rpc) --\u003e\n\u003c!-- [![Sourcegraph](https://sourcegraph.com/github.com/xizhibei/go-reverse-rpc/-/badge.svg)](https://sourcegraph.com/github.com/xizhibei/go-reverse-rpc?badge) --\u003e\n\u003c!-- [![Release](https://img.shields.io/github/release/xizhibei/go-reverse-rpc.svg?style=flat-square)](https://github.com/xizhibei/go-reverse-rpc/releases) --\u003e\n\n## Architecture Overview\n\nIn traditional RPC, clients connect to servers. In reverse RPC, both the server (service provider) and client (service consumer) connect to a message broker:\n\n```\nTraditional RPC: Client → Server\nReverse RPC:    Server → Broker ← Client\n```\n\nThis architecture is ideal for:\n- Services behind firewalls/NATs\n- Dynamic service registration\n- Centralized routing control\n\n## Features\n\n- **Multiple Transport Protocols**\n  - MQTT 3.1/3.11 (implemented)\n  - MQTT v5, WebSocket, AMQP (planned)\n- **Flexible Data Formats**\n  - JSON and Protobuf (implemented)\n  - MessagePack, Avro (planned)\n- **Observability**\n  - OpenTelemetry integration (tracing and metrics)\n  - Configurable telemetry export (OTLP, debug mode)\n  - Built-in RPC performance metrics\n- **Reliability**\n  - Structured error handling\n  - Request rate limiting\n  - Configurable timeouts\n- **Performance**\n  - Payload compression\n  - Worker pool management\n\n## Installation\n\n```bash\ngo get github.com/xizhibei/go-reverse-rpc@latest\n```\n\n## Quick Start\n\n### Server Setup\n```go\nimport (\n    \"github.com/xizhibei/go-reverse-rpc/mqttpb\"\n    \"github.com/xizhibei/go-reverse-rpc/mqttadapter\"\n)\n\nmqttClient, err := mqttadapter.New(\"tcp://localhost\", \"client-id-123456-server\")\nif err != nil {\n    panic(err)\n}\n\nserver := mqttpb.NewServer(\n    mqttClient,\n    \"example-prefix\",\n    \"device-123456\",\n)\n```\n\n### Client Setup\n```go\nimport (\n    \"github.com/xizhibei/go-reverse-rpc/mqttpb\"\n    \"github.com/xizhibei/go-reverse-rpc/mqttadapter\"\n)\n\nmqttClient, err := mqttadapter.New(\"tcp://localhost\", \"client-id-123456-client\")\nif err != nil {\n    panic(err)\n}\n\nclient := mqttpb.New(\n    mqttClient,\n    \"example-prefix\",\n    mqttpb.ContentEncoding_GZIP,\n)\n```\n\n### Register Handler (Server Side)\n```go\nimport (\n    rrpc \"github.com/xizhibei/go-reverse-rpc\"\n)\n\nserver.Register(\"example-method\", \u0026rrpc.Handler{\n    Method: func(c rrpc.Context) {\n        var req Req\n        err := c.Bind(\u0026req)\n        if err != nil {\n            c.ReplyError(rrpc.RPCStatusClientError, err)\n            return\n        }\n\n        // your business logic ...\n\n        c.ReplyOK(req)\n    },\n    Timeout: 5 * time.Second,\n})\n```\n\n### Make RPC Call (Client Side)\n```go\nvar res Req\nerr := client.Call(context.Background(), \"device-123456\", \"example-method\", \u0026reqParams, \u0026res)\n```\n\n## Telemetry Configuration\n\nThe framework includes comprehensive OpenTelemetry support with both programmatic and environment-based configuration.\n\n### Environment Variables\n\n```bash\n# Enable/disable telemetry (default: false)\nexport OTEL_ENABLED=true\n\n# Enable debug mode with stdout output (default: false)  \nexport OTEL_DEBUG=true\n\n# OTLP collector endpoint (default: localhost:4317)\nexport OTEL_EXPORTER_OTLP_ENDPOINT=localhost:4317\n\n# Deployment environment (default: development)\nexport ENVIRONMENT=production\n```\n\n### Programmatic Configuration\n\n```go\nimport \"github.com/xizhibei/go-reverse-rpc/telemetry\"\n\ntel, err := telemetry.New(telemetry.Config{\n    ServiceName:    \"my-service\",\n    ServiceVersion: \"1.0.0\", \n    Environment:    \"production\",\n    OTLPEndpoint:   \"localhost:4317\",\n    Debug:          false,\n    Enabled:        true,\n})\nif err != nil {\n    // Handle error\n}\ndefer tel.Shutdown(context.Background())\n\n// Configure server with telemetry\nserver.SetTelemetry(tel)\n```\n\n## Server Configuration Options\n\n```go\n// Server configuration options\nrrpc.WithServerName(name string)       // Set server name for metrics labels\nrrpc.WithLogResponse(logResponse bool) // Enable/disable response logging\nrrpc.WithLimiter(d time.Duration, count int) // Set rate limiter parameters\nrrpc.WithLimiterReject()               // Reject requests when limiter is full (default)\nrrpc.WithLimiterWait()                 // Wait for resources instead of rejecting\nrrpc.WithWorkerNum(count int)          // Set worker pool size\n```\n\n## Examples\n\nThe project includes comprehensive examples to help you get started:\n\n### Basic Client/Server Demo\n\nLocated in `examples/basic/`, this example demonstrates:\n- Simple server with math operations (Add, Multiply, Divide)\n- Client implementation making RPC calls\n- Error handling and timeout management\n- OpenTelemetry integration with metrics and tracing\n\n```bash\n# Start the server\ngo run examples/basic/server/main.go\n\n# In another terminal, run the client\ngo run examples/basic/client/main.go\n```\n\nThe example includes both manual telemetry configuration and environment-based configuration patterns. Check `examples/basic/server-with-env/main.go` for environment variable usage.\n\n\n## License\n\nGo reverse RPC is released under MIT license, refer to [LICENSE](LICENSE) file.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxizhibei%2Fgo-reverse-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fxizhibei%2Fgo-reverse-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fxizhibei%2Fgo-reverse-rpc/lists"}