A simple RPC framework with protobuf service definitions
Go Python Other
Clone or download
spenczar Merge pull request #115 from schoenobates/patch-1
Added link to java server implementation
Latest commit cafc5e8 Jun 22, 2018
Permalink
Failed to load latest commit information.
.github Adding missing files; fixing license to be standard; adding license t… Jan 17, 2018
_tools v5.0.0: Initial public commit Jan 16, 2018
clientcompat Version 5.4.1 May 22, 2018
ctxsetters Add Apache 2 license header to all source files Jan 18, 2018
docs Fix documentation's mention of obsolete ContextSource param Jun 6, 2018
example Version 5.4.1 May 22, 2018
hooks/statsd Add Apache 2 license header to all source files Jan 18, 2018
internal Version 5.4.1 May 22, 2018
protoc-gen-twirp Merge pull request #105 from twitchtv/nil_responses_on_errors May 22, 2018
protoc-gen-twirp_python Make the python client code ascii-encode server urls. Apr 5, 2018
vendor/github.com Vendor go packages for well-known types used in tests May 22, 2018
website Fix documentation's mention of obsolete ContextSource param Jun 6, 2018
.gitignore gitignore npm debug logs Feb 8, 2018
.travis.yml Remove dep installation from travis Jan 26, 2018
CONTRIBUTING.md Add notes on documentation contributions to CONTRIBUTING.md Feb 8, 2018
Gopkg.lock Vendor go packages for well-known types used in tests May 22, 2018
Gopkg.toml Commit vendor directory Jan 26, 2018
LICENSE Adding missing files; fixing license to be standard; adding license t… Jan 17, 2018
Makefile v5.0.0: Initial public commit Jan 16, 2018
NOTICE Adding missing files; fixing license to be standard; adding license t… Jan 17, 2018
PROTOCOL.md Update PROTOCOL.md Feb 2, 2018
README.md Added link to java server implementation Jun 22, 2018
THIRD_PARTY Fixing license; i had the wrong one Jan 19, 2018
context.go fix(client) Added Accept header to JSON and protobuf clients. Feb 15, 2018
errors.go fixing some typos Jan 22, 2018
errors_test.go Add Apache 2 license header to all source files Jan 18, 2018
hooks.go Update documenting comment on Errors hook Feb 9, 2018
hooks_test.go Add Apache 2 license header to all source files Jan 18, 2018
install_proto.bash protoc: update to 3.5.1 everywhere; verify from Makefile Jan 26, 2018
license_test.go Add Apache 2 license header to all source files Jan 18, 2018
logo.png v5.0.0: Initial public commit Jan 16, 2018
requirements.txt protoc: update to 3.5.1 everywhere; verify from Makefile Jan 26, 2018
tools.json v5.0.0: Initial public commit Jan 16, 2018
vendor_test.go Add test that ensures we have no external dependencies Jan 30, 2018

README.md

Twirp Logo Build Status Go Report Card GoDoc


Twirp is a framework for service-to-service communication emphasizing simplicity and minimalism. It generates routing and serialization from API definition files and lets you focus on your application's logic instead of thinking about folderol like HTTP methods and paths and JSON.

Define your service in a Protobuf file and then Twirp autogenerates Go code with a server interface and fully functional clients. It's similar to gRPC, but without the custom HTTP server and transport implementations: it runs on the standard library's extremely-well-tested-and-high-performance net/http Server. It can run on HTTP 1.1, not just http/2, and supports JSON clients for easy integrations across languages

Twirp handles routing and serialization for you in a well-tested, standardized, thoughtful way so you don't have to. Serialization and deserialization code is error-prone and tricky, and you shouldn't be wasting your time deciding whether it should be "POST /friends/:id/new" or "POST /:id/friend" or whatever. Just get to the real work of building services!

Along the way, you get an autogenerated client and a simple, smart framework for passing error messages. Nice!

For more on the motivation behind Twirp (and a comparison to REST APIs and gRPC), the announcement blog post is a good read.

Installation

Use go get to install the Go client-and-server generator:

go get github.com/twitchtv/twirp/protoc-gen-twirp

You will also need:

Documentation

Thorough documentation is on the website.

Source for this documentation is in the docs subdirectory. The website is generated from that folder using Docusaurus.

Implementations in other languages

This repo only has the official generators, which write out Go and Python code. For other languages, there are third-party generators available:

Language Clients Servers Repository
Java github.com/fajran/protoc-gen-twirp_java_jaxrs
Java https://github.com/devork/flit
JavaScript github.com/thechriswalker/protoc-gen-twirp_js
JavaScript github.com/Xe/twirp-codegens/cmd/protoc-gen-twirp_jsbrowser
Typescript github.com/larrymyers/protoc-gen-twirp_typescript
Ruby github.com/twitchtv/twirp-ruby
Rust github.com/cretz/prost-twirp
Swagger github.com/elliots/protoc-gen-twirp_swagger
PHP github.com/twirphp/twirp

This list isn't an endorsement, it's just a convenience to help you find stuff for your language.

Support and Community

We have a channel on the Gophers slack, #twirp, which is the best place to get quick answers to your questions. You can join the Gopher slack here.

Releases

Twirp follows semantic versioning through git tags, and uses Github Releases for release notes and upgrade guides: Twirp Releases

Contributing

Check out CONTRIBUTING.md for notes on making contributions.

License

This library is licensed under the Apache 2.0 License.