{"id":16960129,"url":"https://github.com/dflemstr/prost-simple-rpc","last_synced_at":"2025-10-25T21:14:43.517Z","repository":{"id":62443030,"uuid":"127546852","full_name":"dflemstr/prost-simple-rpc","owner":"dflemstr","description":null,"archived":false,"fork":false,"pushed_at":"2018-08-07T08:24:53.000Z","size":34,"stargazers_count":7,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-25T18:07:14.954Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dflemstr.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-03-31T15:50:18.000Z","updated_at":"2025-03-04T09:15:30.000Z","dependencies_parsed_at":"2022-11-01T22:16:32.834Z","dependency_job_id":null,"html_url":"https://github.com/dflemstr/prost-simple-rpc","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Fprost-simple-rpc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Fprost-simple-rpc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Fprost-simple-rpc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dflemstr%2Fprost-simple-rpc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dflemstr","download_url":"https://codeload.github.com/dflemstr/prost-simple-rpc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247999866,"owners_count":21031046,"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":[],"created_at":"2024-10-13T22:47:12.328Z","updated_at":"2025-10-25T21:14:43.447Z","avatar_url":"https://github.com/dflemstr.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# `prost-simple-rpc`\n\nDo you want to use type-safe Protobuf-based RPC without having to use something heavy-weight like\ngRPC?\n\nThis library lets you generate traits for implementing a generic RPC mechanism using Protobuf as\nthe schema language.  You have to supply your own underlying transport mechanism, for example\nWebSockets, UNIX pipes, HTTP, etc.\n\n## TODO\n\nThis library is quite complete but there are still a few things I would like to fix before a \"1.0\":\n\n  - [ ] Clean up the code generation code.\n  - [x] Use unboxed futures in generated client code.\n  - [ ] Use unboxed futures in generated server code.\n  - [x] Try to support execution errors that don't implement `failure::Fail`.\n\n## Usage\n\nFor the complete example, see the [example](./example) directory.\n\nStart by defining a schema for your service in e.g. `src/schema/echo/service.proto`:\n\n```proto\nsyntax = \"proto3\";\n\npackage echo;\n\n// The Echo service. This service returns back the same data that it is given.\nservice Echo {\n  // Echoes back the data sent, unmodified.\n  rpc Echo (EchoRequest) returns (EchoResponse);\n}\n\n// The request for an `Echo.Echo` call.\nmessage EchoRequest {\n  // The data to be echoed back.\n  bytes data = 1;\n}\n\n// The response for an `Echo.Echo` call.\nmessage EchoResponse {\n  // The echoed back data from `EchoRequest.data`.\n  bytes data = 1;\n}\n```\n\nUse `prost`, `prost-build` and `prost-simple-rpc-build` to generate Rust code for this service, by\nputting this in your `build.rs`:\n\n```rust\nextern crate prost_build;\nextern crate prost_simple_rpc_build;\n\nfn main() {\n    prost_build::Config::new()\n        .service_generator(Box::new(prost_simple_rpc_build::ServiceGenerator::new()))\n        .compile_protos(\n            \u0026[\"src/schema/echo/service.proto\"],\n            \u0026[\"src/schema\"],\n        )\n        .unwrap();\n}\n```\n\nThen, include the generated code in your Rust build, for example in `main.rs`.  There are a bunch of\nextra crate dependencies for the generated code:\n\n```rust\nextern crate bytes;\nextern crate failure;\nextern crate futures;\nextern crate prost;\n#[macro_use]\nextern crate prost_derive;\nextern crate prost_simple_rpc;\nextern crate tokio;\n\nmod schema {\n    pub mod echo {\n        include!(concat!(env!(\"OUT_DIR\"), \"/echo.rs\"));\n    }\n}\n\nfn main() {\n    // ...\n}\n```\n\n### Client\n\nLet's say you want to create a client for your service.  You need to implement a `Handler` that\nhandles the transport for your client calls.  Let's imagine you have some form of `WebSockets`\ntransport:\n\n```rust\nstruct WebSocketTransport { /* ... */ }\n\nimpl prost_simple_rpc::handler::Handler for WebSocketTransport {\n    // From our imaginary websocket library:\n    type Error = websocket::Error;\n    // This type is generated by prost-simple-rpc:\n    type Descriptor = schema::echo::EchoDescriptor;\n    // From our imaginary websocket library:\n    type CallFuture = websocket::Future;\n\n    /// Perform a raw call to the specified service and method.\n    fn call(\n        \u0026mut self,\n        method: \u003cSelf::Descriptor as descriptor::ServiceDescriptor\u003e::Method,\n        input: bytes::Bytes,\n    ) -\u003e Self::CallFuture {\n        // You can use information from the descriptors to include in the request:\n        self.websocket.call(Self::Descriptor::name(), method.name(), input)\n    }\n}\n```\n\nYou can now use this handler with the client generated by `prost-simple-rpc`:\n\n```rust\nfn main() {\n    let websocket = WebSocketTransport::connect(\"...\");\n    let client = schema::echo::EchoClient::new(websocket);\n    let future = client.echo(schema::echo::EchoRequest { /* ... */ });\n    // ... use the future to wait for a response.\n}\n```\n\n### Server\n\nTo create a server for your service, start by implementing the generated service trait for the\nservice:\n\n```rust\nstruct EchoService;\n\n#[derive(Debug, Eq, Fail, PartialEq)]\n#[fail(display = \"Error!\")]\nstruct Error;\n\nimpl schema::echo::Echo for EchoService {\n    // You can supply an error type here if your service can fail.\n    type Error = Error;\n    // The future type used in the `echo()` method; you can of course use Box\u003cFuture\u003c...\u003e\u003e here\n    // but this library assumes unboxed futures by default.\n    type EchoFuture = futures::future::FutureResult\u003cschema::echo::EchoResponse, Self::Error\u003e;\n\n    fn echo(\u0026self, input: schema::echo::EchoRequest) -\u003e Self::EchoFuture {\n        futures::future::ok(schema::echo::EchoResponse { data: input.data })\n    }\n}\n```\n\nYou can now wrap this service with the generated server implementation to get something that can be\nplugged into your preferred routing system:\n\n```rust\nfn main() {\n    let server = schema::echo::EchoServer::new(EchoService);\n    \n    websocket::spawn_server(move |request| {\n        // You would probably normally look up the right method descriptor via some kind of routing\n        // information; here's a hard-coded example:\n        let method = schema::echo::EchoMethodDescriptor::Echo;\n\n        server.call(method, request.data);\n    });\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdflemstr%2Fprost-simple-rpc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdflemstr%2Fprost-simple-rpc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdflemstr%2Fprost-simple-rpc/lists"}