{"id":47725839,"url":"https://github.com/z5labs/avroc","last_synced_at":"2026-04-27T04:01:43.226Z","repository":{"id":345210118,"uuid":"1184926164","full_name":"z5labs/avroc","owner":"z5labs","description":"A modular code generator for messages and services defined in Avro IDL.","archived":false,"fork":false,"pushed_at":"2026-04-15T21:39:08.000Z","size":103,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-15T23:27:11.317Z","etag":null,"topics":["avro","avro-schema","code-generation","code-generator","go","golang"],"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/z5labs.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":null,"dco":null,"cla":null}},"created_at":"2026-03-18T04:10:00.000Z","updated_at":"2026-04-15T21:39:10.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/z5labs/avroc","commit_stats":null,"previous_names":["z5labs/avroc"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/z5labs/avroc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favroc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favroc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favroc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favroc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/z5labs","download_url":"https://codeload.github.com/z5labs/avroc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z5labs%2Favroc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32321940,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"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":["avro","avro-schema","code-generation","code-generator","go","golang"],"created_at":"2026-04-02T20:24:15.281Z","updated_at":"2026-04-27T04:01:43.208Z","avatar_url":"https://github.com/z5labs.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# avroc\n\nA modular code generator for messages and services defined in [Avro IDL](https://avro.apache.org/docs/current/idl-language/).\n\n## Features\n\n- **Dynamic generator discovery** — avroc automatically discovers generator plugins on your `PATH` using the naming convention `avroc-gen-\u003cname\u003e`. No configuration file needed; just install a plugin and it is available immediately.\n- **Type validation** — avroc resolves all type references in your Avro IDL schemas and reports errors for any undefined types before invoking generators.\n- **Value validation** — avroc validates field defaults and enum defaults against their declared types, catching mistakes (e.g. a `null` default on an `int` field) at generation time.\n- **Parallel generation** — all active generators run concurrently, so code generation scales with the number of plugins you use.\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────┐\n│  avroc (CLI)                                         │\n│                                                      │\n│  1. Scan PATH for avroc-gen-* executables            │\n│  2. Register -\u003cname\u003e_out / -\u003cname\u003e_opt flags         │\n│  3. Parse \u0026 validate Avro IDL files                  │\n│  4. For each active generator (concurrently):        │\n│     a. Create a temporary Unix socket                │\n│     b. Launch avroc-gen-\u003cname\u003e subprocess            │\n│     c. Connect via gRPC (Generator service)          │\n│     d. Send GenerateRequest  ──────────────────────► │  avroc-gen-\u003cname\u003e\n│     e. Receive GenerateResponse ◄──────────────────  │  (gRPC server on\n└─────────────────────────────────────────────────────┘   Unix socket)\n```\n\nGenerators communicate with `avroc` over a gRPC `Generator` service defined in [`proto/`](proto/). This means you can write a generator in **any language** that supports gRPC — just name the executable `avroc-gen-\u003cname\u003e` and put it on your `PATH`.\n\n## Installation\n\n```bash\ngo install github.com/z5labs/avroc/cmd/avroc@latest\n```\n\nInstall the built-in generators you need:\n\n```bash\n# Go code generator\ngo install github.com/z5labs/avroc/cmd/avroc-gen-go@latest\n\n# Avro JSON schema generator\ngo install github.com/z5labs/avroc/cmd/avroc-gen-json@latest\n\n# Avro Parsing Canonical Form generator\ngo install github.com/z5labs/avroc/cmd/avroc-gen-pcf@latest\n```\n\n## Usage\n\n```\navroc [options] \u003cidl files...\u003e\n```\n\nFor each generator plugin discovered on `PATH`, avroc registers two flags:\n\n| Flag | Description |\n|---|---|\n| `-\u003cname\u003e_out \u003cdir\u003e` | Output directory for the `\u003cname\u003e` generator. Passing this flag activates the generator. |\n| `-\u003cname\u003e_opt \u003ckey\u003e=\u003cvalue\u003e` | Generator option. Can be specified multiple times. |\n\n### Example\n\nGiven the following Avro IDL file (`schema.avdl`):\n\n```\nnamespace org.apache.avro.test;\n\nschema TestRecord;\n\nenum Kind {\n  FOO,\n  BAR,\n  BAZ\n}\n\nfixed MD5(16);\n\nrecord TestRecord {\n  string name;\n  Kind kind;\n  MD5 hash;\n  union { null, MD5 } nullableHash;\n}\n```\n\nGenerate Go types, an Avro JSON schema file, and a Parsing Canonical Form file:\n\n```bash\navroc \\\n  -go_out=./gen \\\n  -go_opt=package_name=mypackage \\\n  -json_out=. \\\n  -pcf_out=./pcf \\\n  schema.avdl\n```\n\nThis produces:\n- `./gen/test_record.go` — Go types with `MarshalAvroBinary` / `UnmarshalAvroBinary` methods\n- `./test_record.avsc` — Avro JSON schema\n- `./pcf/test_record.avsc` — Avro Parsing Canonical Form\n\nSee the [`example/`](example/) directory for a working example.\n\n## Built-in Generators\n\n### `avroc-gen-go`\n\nGenerates idiomatic Go types with binary Avro serialization support.\n\n| Option | Required | Description |\n|---|---|---|\n| `package_name` | Yes | The Go package name for all generated files. |\n| `encoding` | No | Set to `single_object` to generate a `Fingerprint()` method on the primary record type for [Avro Single Object Encoding](https://avro.apache.org/docs/current/specification/#single-object-encoding). |\n\n**Generated types:**\n\n| Avro type | Go type |\n|---|---|\n| `record` | `struct` with `MarshalAvroBinary` / `UnmarshalAvroBinary` |\n| `enum` | `int` type with typed constants |\n| `fixed` | `[N]byte` type |\n| `union { null, T }` | interface with `Null` and `T` implementations |\n| `string` | `string` |\n| `int` / `long` | `int32` / `int64` |\n| `float` / `double` | `float32` / `float64` |\n| `boolean` | `bool` |\n| `bytes` | `[]byte` |\n\n### `avroc-gen-json`\n\nGenerates [Avro JSON schema](https://avro.apache.org/docs/current/specification/#schema-declaration) files (`.avsc`). Named types are inlined on their first use and referenced by name afterwards.\n\nNo options required.\n\n### `avroc-gen-pcf`\n\nGenerates [Avro Parsing Canonical Form](https://avro.apache.org/docs/1.12.0/specification/#parsing-canonical-form-for-schemas) files (`.avsc`). The output is a compact JSON representation with attribute names and type ordering normalized per the Avro specification. Named types are inlined on first use and referenced by their fully-qualified name on subsequent uses. The file content is written as exact canonical bytes — no trailing newline — so it can be used directly for fingerprinting.\n\nNo options required.\n\n## Writing a Custom Generator\n\n1. Create an executable named `avroc-gen-\u003cname\u003e` and put it on your `PATH`.\n2. On startup, read the Unix socket path from `os.Args[1]`.\n3. Start a gRPC server on that socket and register your implementation of the `Generator` service (see [`proto/generator.proto`](proto/generator.proto)).\n4. Handle `GenerateRequest` messages (output directory, options, schemas) and return a `GenerateResponse` with the list of generated file paths.\n\nThe protobuf definitions and generated Go stubs are in [`internal/avrocpb/`](internal/avrocpb/).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz5labs%2Favroc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fz5labs%2Favroc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz5labs%2Favroc/lists"}