Categorygithub.com/thinkdata-works/twirp
modulepackage
6.0.0-prerelease.alpha1+incompatible
Repository: https://github.com/thinkdata-works/twirp.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
5
Dependents
21
Files
383 SLOC

# README

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:

LanguageClientsServersRepository
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
Dart✓github.com/apptreesoftware/protoc-gen-twirp_dart

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.

# Packages

No description provided by the author
Package ctxsetters is an implementation detail for twirp generated code, used by the generated servers to set values in contexts for later access with the twirp package's accessors.
Package example is a generated twirp stub package.
No description provided by the author
No description provided by the author
No description provided by the author

# Functions

ChainHooks creates a new *ServerHooks which chains the callbacks in each of the constituent hooks passed in.
No description provided by the author
InternalError constructor for the common Internal error.
InternalErrorWith is an easy way to wrap another error.
InvalidArgumentError constructor for the common InvalidArgument error.
IsValidErrorCode returns true if is one of the valid predefined constants.
MethodName extracts the name of the method being handled in the given context.
NewError is the generic constructor for a twirp.Error.
NotFoundError constructor for the common NotFound error.
PackageName extracts the fully-qualified protobuf package name of the service handling the given context.
RequiredArgumentError is a more specific constructor for InvalidArgument error.
ServerHTTPStatusFromErrorCode maps a Twirp error type into a similar HTTP response status.
ServiceName extracts the name of the service handling the given context.
SetHTTPResponseHeader sets an HTTP header key-value pair using a context provided by a twirp-generated server, or a child of that context.
StatusCode retrieves the status code of the response (as string like "200").
WithHTTPRequestHeaders stores an http.Header in a context.Context.

# Constants

Aborted indicates the operation was aborted, typically due to a concurrency issue like sequencer check failures, transaction aborts, etc.
AlreadyExists means an attempt to create an entity failed because one already exists.
BadRoute means that the requested URL path wasn't routable to a Twirp service and method.
Canceled indicates the operation was cancelled (typically by the caller).
DataLoss indicates unrecoverable data loss or corruption.
DeadlineExceeded means operation expired before completion.
FailedPrecondition indicates operation was rejected because the system is not in a state required for the operation's execution.
Internal errors.
InvalidArgument indicates client specified an invalid argument.
NoError is the zero-value, is considered an empty error and should not be used.
NotFound means some requested entity was not found.
OutOfRange means operation was attempted past the valid range.
PermissionDenied indicates the caller does not have permission to execute the specified operation.
ResourceExhausted indicates some resource has been exhausted, perhaps a per-user quota, or perhaps the entire file system is out of space.
Unauthenticated indicates the request does not have valid authentication credentials for the operation.
Unavailable indicates the service is currently unavailable.
Unimplemented indicates operation is not implemented or not supported/enabled in this service.
Unknown error.

# Structs

ServerHooks is a container for callbacks that can instrument a Twirp-generated server.

# Interfaces

Error represents an error in a Twirp service call.

# Type aliases

ErrorCode represents a Twirp error type.