{"id":28436867,"url":"https://github.com/moleculerjs/sidecar","last_synced_at":"2025-07-08T01:09:53.310Z","repository":{"id":84860925,"uuid":"323902562","full_name":"moleculerjs/sidecar","owner":"moleculerjs","description":"[WIP] Sidecar for Moleculer framework with HTTP support.","archived":false,"fork":false,"pushed_at":"2021-03-25T18:35:53.000Z","size":235,"stargazers_count":16,"open_issues_count":0,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-05T01:51:28.270Z","etag":null,"topics":["microservices","moleculer","sidecar"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/moleculerjs.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}},"created_at":"2020-12-23T12:57:43.000Z","updated_at":"2024-11-28T01:19:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"88e8d6ad-122c-4faa-b4cb-e907bde58017","html_url":"https://github.com/moleculerjs/sidecar","commit_stats":{"total_commits":51,"total_committers":1,"mean_commits":51.0,"dds":0.0,"last_synced_commit":"a2cc0ba6e3152e1bfc9f147bcce804fcd7fd3a8c"},"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/moleculerjs/sidecar","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moleculerjs%2Fsidecar","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moleculerjs%2Fsidecar/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moleculerjs%2Fsidecar/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moleculerjs%2Fsidecar/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moleculerjs","download_url":"https://codeload.github.com/moleculerjs/sidecar/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moleculerjs%2Fsidecar/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260831301,"owners_count":23069453,"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":["microservices","moleculer","sidecar"],"created_at":"2025-06-05T23:07:48.300Z","updated_at":"2025-06-27T20:32:13.456Z","avatar_url":"https://github.com/moleculerjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Moleculer logo](http://moleculer.services/images/banner.png)\n\n![Integration Test](https://github.com/moleculerjs/sidecar/workflows/Integration%20Test/badge.svg)\n\n# [WIP] Moleculer Sidecar\nMoleculer Sidecar allows using external services (written in other programming languages which is not supported officially) in a Moleculer microservices project. The Sidecar is a HTTP server which gives a REST interface to communicate other Moleculer services instead of implementing the full Moleculer protocol és Service Registry \u0026 Discovery features. Sidecar is a full-fledged MoleculerJS node with all features (e.g. parameter validation, retries, fallback, timeout...etc), it means in the external services, you don't need to implement them because Sidecar manages them.\n\n## Features\n- write services any programming languages (which have http server \u0026 client support).\n- bundled to executable, no need to install Node.js environment for running.\n- configure Sidecar via environment variables or `moleculer.config.js` file.\n- contains all official transporter, cacher, discoverer, serializer libraries.\n- easy to add to any Docker image.\n- official Docker image, use it as a Sidecar pod container in Kubernetes cluster.\n\n## Install\n\n### Using executables\nDownload binaries from [releases](https://github.com/moleculerjs/sidecar/releases).\n\n### Docker\n**Simple start**\n```bash\ndocker run -p 5103:5103 moleculer/sidecar\n```\n\n**Start with REPL mode**\n```bash\ndocker run --it -p 5103:5103 moleculer/sidecar --repl\n```\n\n**Start with config file**\n```bash\ndocker run -v /my-folder/moleculer.config.js:/sidecar/moleculer.config.js moleculer/sidecar --config\n```\n\n### Kubernetes\nTODO\n\n### Using from source\nTODO\n\n## Usage (via HTTP interface)\nThe ServiceBroker inside the Sidecar can be configured via `moleculer.config.js` file or environment variables. The Sidecar HTTP server is listening on port 5103 (by default). _(Why 5103? To make it easier to remember: SIDE = S-\u003e5 I-\u003e1 D-\u003e0 E-\u003e3 = 5103)._ If you don't like it, you can change it with `SIDECAR_PORT` environment variable.\n\n### Register an external service\nThe request body should contains one or more service schema where the action/event handlers should be an URL what points to the external service HTTP endpoint. In the Service schema you can use all MoleculerJS features (e.g. parameter validation, metrics, tracing, bulkhead, timeout, retries ...etc), they are handled by the Sidecar.\n```\nPOST /v1/registry/services\n```\n\n**Request body**\n```js\n{\n    name: \"posts\",\n    version: 1,\n\n    settings: {\n        // It means, your HTTP server running on port 5000 and sidecar can reach it on `localhost`\n        // The URLs in action/event handlers contains relative URL.\n        baseUrl: \"http://localhost:5000\"\n    },\n\n    actions: {\n        list: {\n            params: {\n                limit: \"number\",\n                offset: \"number\"\n            },\n            // Shorthand handler URL what will be called by sidecar\n            handler: \"/actions/posts/list\"\n        }\n    },\n\n    events: {\n        \"user.created\": {\n            // Shorthand handler URL what will be called by sidecar\n            handler: \"/events/user.created\"\n        }\n    }\n}\n```\n\n### Call a service\n\nCalling `comments.create` service action.\n```\nPOST /v1/call/comments.create\n```\n\n**Request body**\n```js\n{\n    // Context params\n    params: {\n        title: \"Lorem ipsum\",\n        content: \"Lorem ipsum dolor sit amet...\"\n    },\n    // Context meta\n    meta: {\n        user: {\n            id: 12345\n        }\n    },\n    // Calling options\n    options: {\n        timeout: 3000\n    }\n}\n```\n\n**Response body** \n```js\n{\n    // Response data\n    response: {\n        id: 1,\n        title: \"Lorem ipsum\",\n        content: \"Lorem ipsum dolor sit amet...\"\n    },\n    // Optional: Context meta if you changed the content.\n    meta: {\n        user: {\n            id: 12345\n        }\n    }\n}\n```\n\n**Error response body**\n```js\n{\n    error: {\n        name: \"MoleculerClientError\",\n        code: 422,\n        type: \"VALIDATION_ERROR\",\n        message: \"Title is required\",\n        data: {\n            action: \"comments.create\",\n            params: {\n                title: null\n            }\n        }\n    }\n}\n```\n\n### Emit an event\n\nEmit a `post.created` event.\n```\nPOST /v1/emit/post.created\n```\n\nIn case of broadcast use the following URL:\n```\nPOST /broadcast/post.created\n```\n\n**Request body**\n```js\n{\n    // Context params\n    params: {\n        id: 1,\n        title: \"First post\",\n        content: \"Post content\",\n        author: 12345\n    },\n    // Context meta\n    meta: {\n        user: {\n            id: 12345\n        }\n    },\n    // Emit options\n    options: {\n        groups: \"users\"\n    }\n}\n```\n\n### Accepting action requests\nIf your external service implements actions, you should start a HTTP server. Create an endpoint for the action handler and set the address in the service schema. If another services calls your action, the Sidecar sends a POST request to the defined endpoint with the following request body:\n\n**Request body**\n```js\n{\n    // Action name\n    action: \"posts.list\",\n\n    // Caller NodeID\n    nodeID: \"node-123\",\n\n    // Context params\n    params: {\n        limit: 10,\n        offset: 50\n    },\n\n    // Context meta\n    meta: {\n        user: {\n            id: 12345\n        }\n    },\n\n    // Calling options\n    options: {\n        timeout: 3000\n    }\n}\n```\n\nYou should send a response with the following form:\n\n**Response body** \n```js\n{\n    // Response data\n    response: [\n        { id: 1, title: \"First post\" },\n        { id: 2, title: \"Second post\" },\n        { id: 3, title: \"Third post\" }\n    ],\n    // Optional: Context meta if you changed the content.\n    meta: {\n        user: {\n            id: 12345\n        }\n    }\n}\n```\n\nIf an error occured during execution, use correct response status code (4xx, 5xx) and send the following as a response body:\n\n**Error response body** \n```js\n{\n    // Error data\n    error: {\n        name: \"MoleculerClientError\",\n        code: 400,\n        type: \"INVALID_INPUT\",\n        message: \"Some user input is not valid\",\n        data: {\n            // Any useful data\n            action: \"posts.list\",\n            params: {\n                limit: \"asd\"\n            }\n        }\n    }\n}\n```\n\n### Accepting events\nIf you want to subscribe to Moleculer events, you should start a HTTP server. Create an endpoint for the event handler and set the address in the service schema. If the event emitted, the Sidecar sends a POST request to the defined endpoint with the following request body:\n\n**Request body**\n```js\n{\n    // Event name\n    event: \"user.created\",\n\n    // Type of event (emit, broadcast)\n    eventType: \"emit\",\n\n    eventGroups: \"posts\",\n\n    // Caller NodeID\n    nodeID: \"node-123\",\n\n    // Context params\n    params: {\n        limit: 10,\n        offset: 50\n    },\n\n    // Context meta\n    meta: {\n        user: {\n            id: 12345\n        }\n    }\n}\n```\n\n### Access the Sidecar's broker registry\n\nList of all Moleculer nodes\n```\nGET /v1/registry/nodes\n```\n\nList of all Moleculer services\n```\nGET /v1/registry/services\n```\n\nList of all Moleculer actions\n```\nGET /v1/registry/actions\n```\n\nList of all Moleculer event subscriptions\n```\nGET /v1/registry/events\n```\n\n### Unregister an external service\nYou can unregister your service if you call the following endpoint:\n```\nDELETE /v1/registry/services/:service-full-name\n```\n\n**Example**\n```\nDELETE /v1/registry/services/v1.posts\n```\n\n## Example external services\n\n### Go\nUsing Fiber: [examples/full/go-fiber/server.go](examples/full/go-fiber/server.go)\n\n### Python\nUsing Flask: [examples/full/python-flask/server.py](examples/full/python-flask/server.py)\n\n### Ruby\nUsing Sinatra: [examples/full/ruby-sinatra/server.rb](examples/full/ruby-sinatra/server.rb)\n\n### Rust\nUsing Actix: [examples/full/rust-actix/src/main.rs](examples/full/rust-actix/src/main.rs)\n\n### PHP\nUsing Mark: [examples/full/php-mark/server.php](examples/full/php-mark/server.php)\n\n### Ballerina\nUsing built-in tools [examples/full/ballerina/src/server/main.bal](examples/full/ballerina/src/server/main.bal)\n\n### Deno\nUsing Oak: [examples/full/deno-oak/server.ts](examples/full/deno-oak/server.ts)\n\n### Swift\nUsing Perfect: [examples/full/swift-perfect/Sources/server/main.swift](examples/full/swift-perfect/Sources/server/main.swift)\n\n### Crystal\nUsing kemal: [examples/full/crystal-kemal/server.cr](examples/full/crystal-kemal/server.cr)\n\n### C#\nTODO\n\n### C++\nTODO\n\n### Kotlin\nTODO\n\n### Delphi\nTODO\n\n## Contribution\nPlease send pull requests improving the usage and fixing bugs, improving documentation and providing better examples, or providing some testing, because these things are important.\n\n## License\nThe project is available under the [MIT license](https://tldrlegal.com/license/mit-license).\n\n## Contact\nCopyright (c) 2021 MoleculerJS\n\n[![@MoleculerJS](https://img.shields.io/badge/github-moleculerjs-green.svg)](https://github.com/moleculerjs) [![@MoleculerJS](https://img.shields.io/badge/twitter-MoleculerJS-blue.svg)](https://twitter.com/MoleculerJS)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoleculerjs%2Fsidecar","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoleculerjs%2Fsidecar","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoleculerjs%2Fsidecar/lists"}