{"id":16992437,"url":"https://github.com/clemensv/xregistry-cli","last_synced_at":"2025-03-17T09:30:39.099Z","repository":{"id":65434130,"uuid":"585938027","full_name":"clemensv/xregistry-cli","owner":"clemensv","description":"This project is a command line client for CNCF xRegistry","archived":false,"fork":false,"pushed_at":"2025-01-21T16:19:30.000Z","size":1340,"stargazers_count":18,"open_issues_count":10,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2025-02-27T21:50:16.501Z","etag":null,"topics":["amqp","cloudevents","eventing","messaging","mqtt"],"latest_commit_sha":null,"homepage":"","language":"Jinja","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/clemensv.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}},"created_at":"2023-01-06T13:53:46.000Z","updated_at":"2025-02-27T00:41:28.000Z","dependencies_parsed_at":"2023-02-12T23:01:03.562Z","dependency_job_id":"4a943190-d90f-4d94-9c92-eb3e7fe6bcd8","html_url":"https://github.com/clemensv/xregistry-cli","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemensv%2Fxregistry-cli","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemensv%2Fxregistry-cli/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemensv%2Fxregistry-cli/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/clemensv%2Fxregistry-cli/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/clemensv","download_url":"https://codeload.github.com/clemensv/xregistry-cli/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243858333,"owners_count":20359253,"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":["amqp","cloudevents","eventing","messaging","mqtt"],"created_at":"2024-10-14T03:29:10.478Z","updated_at":"2025-03-17T09:30:39.086Z","avatar_url":"https://github.com/clemensv.png","language":"Jinja","funding_links":[],"categories":[],"sub_categories":[],"readme":"# xRegistry CLI\n\n[![Python Test](https://github.com/clemensv/xregistry-cli/actions/workflows/test.yml/badge.svg)](https://github.com/clemensv/xregistry-cli/actions/workflows/test.yml)\n[![Python Release](https://github.com/clemensv/xregistry-cli/actions/workflows/build.yml/badge.svg)](https://github.com/clemensv/xregistry-cli/actions/workflows/build.yml)\n\n\u003e **NOTE**: However finished this project might look, this is currently just a prototype.\n\u003e **Do not use any of its output for any serious purpose at the moment.**\n\nThis project is a command line client for the xRegistry document format and API, with\na focus on generating code artifacts from xRegistry definitions, especially message catalogs.\n\n## Table of Contents\n\n- [What is xRegistry?](#what-is-xregistry)\n- [xRegistry Message Catalogs](#xregistry-message-catalogs)\n\n## What is xRegistry?\n\nThe [xRegistry project](https://xregistry.io/) run by the CNCF Serverless WG\ndefines a generic, extensible, and interoperable registry for metadata and\nmetadata documents. In particular, it is designed to support registries that aid\nwith the discovery and description of messaging and eventing endpoints and\ntherefore has three built-in registries for (payload-)schemas, message\ndefinitions, and endpoints.\n\nxRegistry defines both an API and a document format for managing metadata and\none of its key characteristics is that the REST API and the document model are\nsymmetrical. An HTTP endpoint path in the API corresponds to a JSON pointer path\nin the document model.\n\nAll metadata resources are organized in groups, and each group can contain\nmultiple resources. Some resources allow for maintaining multiple versions, as\nit is the case for schemas.\n\nThe xRegistry API and document model is defined in the\n[xRegistry API specification](https://github.com/xregistry/spec).\n\n## xRegistry Message Catalogs\n\nxRegistry Message Catalogs are a set of registries that are built on top of\nxRegistry and are designed to support the discovery and description of messaging\nand eventing endpoints. The following catalogs are defined:\n\n-   **Schema Catalog**: A registry for schemas that can be used to validate\n    messages.\n-   **Message Catalog**: A registry for message definitions that describe the\n    structure of messages. Messages can be defined as abstract, transport\n    neutral envelopes based on [CloudEvents](https://cloudevents.io) or as concrete\n    messages that are bound to a specific transport protocol, whereby AMQP, HTTP, MQTT,\n    and Apache Kafka are directly supported. Each message definition can associated\n    with a schema from the schema catalog for describing the message payload.\n-   **Endpoint Catalog**: A registry for endpoints that can be used to send or\n    receive messages. Each endpoint can be associated with one or more groups of\n    message definitions from the message catalog.\n\nThe three catalogs are designed to be used together, with the endpoint catalog\nreferring to message definition groups and message definitions referring to schemas.\n\nYou can study some examples of xRegistry Message Catalog documents in the\nsamples directory of this repository:\n\n-   [**Contoso ERP**](samples/message-definitions/contoso-erp.xreg.json): A\n    simple example of a message catalog for a fictional ERP system.\n-   [**Inkjet Printer**](samples/message-definitions/inkjet.xreg.json): A\n    fictitious group of events as they may be raised by an inkhet printer.\n-   [**Fabrikam Motorsports**](samples/message-definitions/fabrikam-motorsports.xreg.json):\n    An example for an event stream as it may be used in a motorsports telemetry\n    scenario.\n-   [**Vacuum Cleaner**](samples/message-definitions/vacuumcleaner.xreg.json):\n    A fictitious group of events as they may be raised by a vacuum cleaner.\n\n## Installation\n\nThe tool requires Python 3.10 or later. Until the tool is published in an\nofficial package source (_this is a prototype, remember?_), you can install the\ntool with pip directly from the repo:\n\n```\npip install git+https://github.com/clemensv/cloudevents-registry-cli.git\n```\n\nIf you want to develop locally and/or run the included tests follow the\ninstructions in [Development Environment](docs/development_environment.md).\n\n## Usage\n\nThe tool is invoked as `xregistry` and supports the following subcommands:\n\n- `xregistry manifest`: Generate a manifest document (a file-based catalog) for a s et of schemas and definitions\n- `xregistry catalog`: Interact with a catalog service (specifically [https://github.com/duglin/xreg-github/](https://github.com/duglin/xreg-github/) at the moment; no authNZ supported yet)\n- `xregistry generate`: Generate code\n- `xregistry validate`: Validate a definition\n- `xregistry list`: List available templates\n\n### Manifest and Catalog commands\n\nThe `manifest` and `catalog` commands allow you to interact with the xRegistry catalog service and manage manifests, endpoints, message groups, messages, and schemas.\n\nRun `xregistry manifest --help` or `xregistry catalog --help` for more information.\n\n### Generate\n\nThe `generate` subcommand generates code from a definition file. The tool\nincludes a set of built-in language/style template sets that can be enumerated\nwith the [List](#list) command.\n\nThe `generate` command takes the following options:\n\n| Option             | Description                                                                                                                                                                        |\n| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| `--projectname`    | **Required** The project name (namespace name) for the generated code.                                                                                                             |\n| `--language`       | **Required** The shorthand code of the language to use for the generated code, for instance \"cs\" for C# or \"ts\" for TypeScript/JavaScript. See [Languages](#languages-and-styles). |\n| `--style`          | The code style. This selects one of the template sets available for the given language, for instance \"producer\". See [Styles](#languages-and-styles)                               |\n| `--output`         | The directory where the generated code will be saved. The generator will overwrite existing files in this directory.                                                               |\n| `--definitions`    | The path to a local file or a URL to a file containing CloudEvents Registry definitions.                                                                                           |\n| `--requestheaders` | Extra HTTP headers for HTTP requests to the given URL in the format `key=value`.                                                                                                   |\n| `--templates`      | Paths of extra directories containing custom templates See [Custom Templates].                                                                                                     |\n| `--template-args`  | Extra template arguments to pass to the code generator in the form `key=value`.                                                                                                    |\n\n#### Languages and Styles\n\nThe tool supports the following languages and styles (as emitted by the `list` command):\n\n```\n--languages options:\nstyles:\n├── asaql: Azure Stream Analytics\n│   ├── dispatch: Azure Stream Analytics: Dispatch to outputs by CloudEvent type\n│   └── dispatchpayload: Azure Stream Analytics: Dispatch to outputs by CloudEvent type\n├── py: Python 3.9+\n│   ├── ehconsumer: Python Event Hubs consumer class\n│   ├── ehproducer: Python Event Hubs producer class\n│   ├── kafkaconsumer: Python Apache Kafka consumer class\n│   ├── kafkaproducer: Python Event Hubs producer class\n│   └── producer: Python generic HTTP producer class\n├── ts: JavaScript/TypeScript\n│   └── producerhttp: JavaScript/TypeScript HTTP Producer\n├── asyncapi: Async API 2.0\n│   └── producer: Async API 2.0 Producer/Publisher\n├── openapi: Open API 3.0\n│   ├── producer: Open API 3.0 Producer\n│   └── subscriber: Open API 3.0 Subscriber\n├── java: Java 21+\n│   ├── consumer: Java Experimental CloudEvents SDK endpoint consumer class\n│   └── producer: Java Experimental CloudEvents SDK endpoint producer class\n└── cs: C# / .NET 6.0+\n    ├── egazfn: C# Azure Function with Azure Event Grid trigger\n    ├── ehazfn: C# Azure Function with Azure Event Hubs trigger\n    ├── sbazfn: C# Azure Function with Azure Service Bus trigger\n    ├── amqpconsumer: C# CloudEvents SDK AMQP endpoint consumer class\n    ├── amqpproducer: C# CloudEvents SDK AMQP endpoint producer class\n    ├── egproducer: C# Azure Service Bus producer class\n    ├── ehconsumer: C# Azure Event Hubs consumer\n    ├── ehproducer: Azure Event Hubs producer class\n    ├── kafkaconsumer: C# Apache Kafka consumer\n    ├── kafkaproducer: Apache Kafka producer class\n    ├── mqttclient: C# MQTT Client\n    ├── sbconsumer: C# Azure Service Bus consumer\n    └── sbproducer: Azure Service Bus producer class\n```\n\nEspecially noteworthy might be the support for both AsyncAPI and OpenAPI.\n\n##### OpenAPI\n\nThe tool can generate AsyncAPI definitions for producer endpoints with:\n\n```shell\nxregistry generate --language=openapi --style=producer --projectname=MyProjectProducer --definitions=definitions.json --output=MyProjectProducer\n```\n\nThis will yield a `MyProjectProducer/MyProjectProducer.yml' file that can be used to generate a\nproducer client for the given endpoint.\n\nSimilarly, the tool can generate OpenAPI definitions for subscriber endpoints with:\n\n```shell\nxregistry generate --language=openapi --style=subscriber --projectname=MyProjectSubscriber --definitions=definitions.json --output=MyProjectSubscriber\n```\n\nThis will yield a `MyProjectSubscriber/MyProjectSubcriber.yml' file that can be\nused to generate a subscriber server for the given endpoint, which is compatible\nwith the CloudEvents Subscription API.\n\n##### AsyncAPI\n\nThe tool can generate AsyncAPI definitions with:\n\n```shell\nxregistry generate --language=asyncapi --style=producer --projectname=MyProjectProducer --definitions=definitions.json --output=MyProjectProducer\n```\n\nFor AsyncAPI, the tool support an extension parameter ce_content_mode that can be used to control the CloudEvents content mode of the generated AsyncAPI definition. The default is \"structured\" and the other supported value is \"binary\". The AsyncAPI template supports HTTP, MQTT, and AMQP 1.0 endpoints and injects the appropriate headers for the selected content mode for each protocol.\n\nUse it like this:\n\n```shell\nxregistry generate --language=asyncapi --style=producer --projectname=MyProjectProducer --definitions=definitions.json --output=MyProjectProducer --template-args ce_content_mode=binary\n```\n\n#### Custom Templates\n\nThe tool supports custom templates. Custom templates reside in a directory and are organized in subdirectories for each language and style. The directory structure is the same as the built-in templates. The tool will look for custom templates in the directories specified with the `--templates` option. Custom templates take precedence over built-in templates.\n\nFor more information on how to write custom templates, see [authoring templates](docs/authoring_templates.md).\n\nIf you are building a custom template that might be generally useful, submit a PR for includion into the built-in template set.\n\n### Validate\n\nThe `validate` subcommand validates a definition file. The tool will report any errors in the definition file.\n\nThe `validate` command takes the following options:\n\n| Option             | Description                                                                              |\n| ------------------ | ---------------------------------------------------------------------------------------- |\n| `--definitions`    | The path to a local file or a URL to a file containing xRegistry definitions. |\n| `--requestheaders` | Extra HTTP headers for HTTP requests to the given URL in the format `key=value`.         |\n\n### List\n\nThe `list` subcommand lists the available language/style template sets.\n\n## Community and Docs\n\nLearn more about the people and organizations who are creating a dynamic cloud\nnative ecosystem by making our systems interoperable with CloudEvents.\n\n- Our [Governance](https://github.com/cloudevents/spec/docs/GOVERNANCE.md) documentation.\n- [Contributing](https://github.com/cloudevents/spec/docs/CONTRIBUTING.md) guidance.\n- [Code of Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md)\n\n### Communications\n\nThe main mailing list for e-mail communications:\n\n- Send emails to: [cncf-cloudevents](mailto:cncf-cloudevents@lists.cncf.io)\n- To subscribe see: https://lists.cncf.io/g/cncf-cloudevents\n- Archives are at: https://lists.cncf.io/g/cncf-cloudevents/topics\n\nAnd a #cloudevents Slack channel under\n[CNCF's Slack workspace](http://slack.cncf.io/).\n\n## License\n\n[Apache 2.0](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclemensv%2Fxregistry-cli","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fclemensv%2Fxregistry-cli","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fclemensv%2Fxregistry-cli/lists"}