{"id":50832068,"url":"https://github.com/varavelio/vdl-plugin-rpc-go","last_synced_at":"2026-06-14T00:05:09.604Z","repository":{"id":347620369,"uuid":"1194603603","full_name":"varavelio/vdl-plugin-rpc-go","owner":"varavelio","description":"Plugin to generate VDL RPC for Golang","archived":false,"fork":false,"pushed_at":"2026-03-28T17:03:18.000Z","size":8,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-28T19:05:37.127Z","etag":null,"topics":["api","codegen","go","golang","rpc","varavel","vdl","vdl-plugin","vdl-rpc"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","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/varavelio.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-28T15:25:38.000Z","updated_at":"2026-03-28T17:03:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/varavelio/vdl-plugin-rpc-go","commit_stats":null,"previous_names":["varavelio/vdl-plugin-rpc-go"],"tags_count":null,"template":false,"template_full_name":"varavelio/vdl-plugin-template","purl":"pkg:github/varavelio/vdl-plugin-rpc-go","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-rpc-go","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-rpc-go/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-rpc-go/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-rpc-go/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/varavelio","download_url":"https://codeload.github.com/varavelio/vdl-plugin-rpc-go/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/varavelio%2Fvdl-plugin-rpc-go/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34304633,"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-13T02:00:06.617Z","response_time":62,"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":["api","codegen","go","golang","rpc","varavel","vdl","vdl-plugin","vdl-rpc"],"created_at":"2026-06-14T00:05:08.894Z","updated_at":"2026-06-14T00:05:09.598Z","avatar_url":"https://github.com/varavelio.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg\n    src=\"https://raw.githubusercontent.com/varavelio/vdl/9cb8432f972f986ba91ffa1e4fe82220a8aa373f/assets/png/vdl.png\"\n    alt=\"VDL logo\"\n    width=\"130\"\n  /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eVDL RPC Golang Plugin\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  Generate Go \u003cstrong\u003eRPC clients\u003c/strong\u003e and \u003cstrong\u003eRPC servers\u003c/strong\u003e from annotation-based VDL services.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://varavel.com\"\u003e\n    \u003cimg src=\"https://cdn.jsdelivr.net/gh/varavelio/brand@1.0.0/dist/badges/project.svg\" alt=\"A Varavel project\"/\u003e\n  \u003c/a\u003e\n  \u003ca href=\"https://varavel.com/vdl\"\u003e\n    \u003cimg src=\"https://cdn.jsdelivr.net/gh/varavelio/brand@1.0.0/dist/badges/vdl-plugin.svg\" alt=\"VDL Plugin\"/\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThis plugin is RPC-focused.\n\nIt does not generate Go data models (types/enums/constants). Instead, it reuses the types generated by [`varavelio/vdl-plugin-go`](https://github.com/varavelio/vdl-plugin-go).\n\n## Quick Start\n\n1. Generate Go types first with `varavelio/vdl-plugin-go`.\n2. Generate the RPC client package (`target \"client\"`) and/or server package (`target \"server\"`).\n3. Run your normal VDL generation command (example: `vdl generate`).\n\n```vdl\nconst config = {\n  version 1\n  plugins [\n    {\n      src \"varavelio/vdl-plugin-go@v0.1.3\"\n      schema \"./schema.vdl\"\n      outDir \"./internal/types\"\n      options {\n        package \"types\"\n      }\n    }\n    {\n      src \"varavelio/vdl-plugin-rpc-go@v0.1.2\"\n      schema \"./schema.vdl\"\n      outDir \"./internal/client\"\n      options {\n        package \"client\"\n        target \"client\"\n        typesImport \"example.com/project/internal/types\"\n      }\n    }\n    {\n      src \"varavelio/vdl-plugin-rpc-go@v0.1.2\"\n      schema \"./schema.vdl\"\n      outDir \"./internal/server\"\n      options {\n        package \"server\"\n        target \"server\"\n        typesImport \"example.com/project/internal/types\"\n      }\n    }\n  ]\n}\n```\n\nIf you only need one side, keep only one RPC plugin block (`client` or `server`).\n\n## Plugin Options\n\n| Option        | Type     | Required | Default         | What it changes                                                                                                                          |\n| ------------- | -------- | -------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |\n| `target`      | `string` | yes      | -               | Selects generation target. Must be `client` or `server`.                                                                                 |\n| `typesImport` | `string` | no       | -               | Go import path for the package generated by `varavelio/vdl-plugin-go`. When omitted/empty, RPC types are resolved from the same package. |\n| `package`     | `string` | no       | `vdlrpc`        | Sets the package name used in generated RPC files (must be a valid Go package).                                                          |\n| `jsonPackage` | `string` | no       | `encoding/json` | Sets the Go package used for JSON marshal/unmarshal. It is always imported as `json \"...\"`.                                              |\n\n### `typesImport` behavior\n\n- Omitted or empty (`\"\"`): same-package mode. Generated code does not emit a types import and uses direct type names like `MessagesSendInput`.\n- Non-empty: imported-types mode. Generated code imports `typesImport` as `vdltypes` and uses `vdltypes.MessagesSendInput`.\n\nUse same-package mode when you generate Go types and RPC output into the same package. Use imported-types mode when RPC is generated in a different package.\n\n### `jsonPackage` behavior\n\n- Omitted: generated code imports `encoding/json` as `json`.\n- Non-empty: generated code imports the configured package as `json`.\n- Empty or whitespace-only: falls back to `encoding/json`.\n\nThis matches the native Go plugin behavior and lets you swap in compatible JSON implementations like `github.com/goccy/go-json` without changing generated call sites.\n\n## Generated Files\n\n- `target \"client\"` writes `client.go`.\n- `target \"server\"` writes `server.go`.\n- If your schema has no discovered `@rpc`, `@proc` or `@stream` operations, no RPC file is emitted.\n\n## What You Get\n\nFor `target \"client\"`:\n\n- `NewClient(baseURL).Build()` to create a typed RPC client.\n- Typed procedure builders and stream builders under `client.RPCs.\u003cService\u003e()`.\n- Headers and header providers at global, RPC, and operation levels.\n- Interceptors, retry/timeout policies for procs, reconnect policies for streams.\n- Stream lifecycle hooks and max message size controls.\n\nFor `target \"server\"`:\n\n- `NewServer[Props]()` with typed handler contexts.\n- Typed registration APIs for procedures and streams.\n- Middleware support at global, RPC, procedure, stream, and stream-emit levels.\n- `SetStreamConfig` and `SetErrorHandler` at global and RPC scope.\n- `NewNetHTTPAdapter(...)` + `HandleRequest(...)` integration for `net/http`.\n\nBoth targets also include generated operation catalogs:\n\n- `VDLPaths` for static operation paths.\n- `VDLProcedures` and `VDLStreams` with operation metadata.\n- Non-marker operation annotations preserved as `Annotation` values.\n\n## RPC Annotation Model\n\nThis plugin follows the VDL RPC annotation model:\n\n- `@rpc` marks a top-level type as an RPC service.\n- `@proc` marks a field as a request-response operation.\n- `@stream` marks a field as a server-streaming operation.\n\n```vdl\n@rpc\ntype Messages {\n  @proc\n  send {\n    input {\n      roomId string\n      text string\n    }\n\n    output {\n      accepted bool\n    }\n  }\n\n  @stream\n  events {\n    input {\n      roomId string\n    }\n\n    output {\n      text string\n    }\n  }\n}\n```\n\nValidation rules enforced by the plugin:\n\n- `@rpc` types must be objects.\n- An operation field can be `@proc` or `@stream`, but not both.\n- Operation nodes must be objects.\n- `input` and `output`, when present, must be objects.\n\nIf an operation omits `input` and/or `output`, generated code uses `Void` for the missing payload.\n\n## Minimal Usage Example\n\n```go\npackage main\n\nimport (\n  \"context\"\n  \"net/http\"\n\n  rpcclient \"example.com/project/internal/client\"\n  rpcserver \"example.com/project/internal/server\"\n  vdltypes \"example.com/project/internal/types\"\n)\n\nfunc example() {\n  server := rpcserver.NewServer[struct{}]()\n\n  server.RPCs.Messages().Procs.Send().Handle(\n    func(c *rpcserver.MessagesSendHandlerContext[struct{}]) (vdltypes.MessagesSendOutput, error) {\n      return vdltypes.MessagesSendOutput{Accepted: true}, nil\n    },\n  )\n\n  mux := http.NewServeMux()\n  mux.HandleFunc(\"POST /rpc/{rpc}/{operation}\", func(w http.ResponseWriter, r *http.Request) {\n    adapter := rpcserver.NewNetHTTPAdapter(w, r)\n    _ = server.HandleRequest(r.Context(), struct{}{}, r.PathValue(\"rpc\"), r.PathValue(\"operation\"), adapter)\n  })\n\n  client := rpcclient.NewClient(\"http://localhost:8080/rpc\").Build()\n  _, _ = client.RPCs.Messages().Procs.Send().Execute(\n    context.Background(),\n    vdltypes.MessagesSendInput{RoomId: \"room-1\", Text: \"hello\"},\n  )\n}\n```\n\n`baseURL` in `NewClient(baseURL)` should point to your RPC prefix (for example: `/rpc`). The generated client appends `/{RPC}/{operation}` automatically.\n\n## License\n\nThis plugin is released under the MIT License. See [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaravelio%2Fvdl-plugin-rpc-go","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvaravelio%2Fvdl-plugin-rpc-go","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvaravelio%2Fvdl-plugin-rpc-go/lists"}