modulepackage
8.1.3+incompatible
Repository: https://github.com/twitchtv/twirp.git
Documentation: pkg.go.dev
# README
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.
Twirp is 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 serialization for easy debugging.
Along the way, you get autogenerated clients and a simple, smart framework for passing error messages. Nice!
Read more about the motivation behind on the announcement blog post.
Documentation
Implementations in other languages
This repo contains the generator and runtime library for the Go implementation.
Here is a list of some third-party implementations in other languages.
| Language | Clients | Servers | Repository |
|---|---|---|---|
| Python3 | ✓ | ✓ | github.com/verloop/twirpy |
| Java | ✓ | ✓ | github.com/fajran/protoc-gen-twirp_java_jaxrs |
| Java | ✓ | github.com/devork/flit | |
| JavaScript | ✓ | github.com/thechriswalker/protoc-gen-twirp_js | |
| JavaScript | ✓ | github.com/Xe/twirp-codegens/cmd/protoc-gen-twirp_jsbrowser | |
| JavaScript | ✓ | ✓ | github.com/tatethurston/TwirpScript |
| Typescript | ✓ | ✓ | github.com/hopin-team/twirp-ts |
| Typescript | ✓ | github.com/larrymyers/protoc-gen-twirp_typescript | |
| Typescript | ✓ | ✓ | github.com/tatethurston/TwirpScript |
| Typescript | ✓ | ✓ | github.com/timostamm/protobuf-ts |
| Ruby | ✓ | ✓ | github.com/twitchtv/twirp-ruby |
| Rust | ✓ | ✓ | github.com/cretz/prost-twirp |
| Scala | ✓ | ✓ | github.com/soundcloud/twinagle |
| Swagger | ✓ | ✓ | github.com/go-bridget/twirp-swagger-gen |
| PHP | ✓ | ✓ | github.com/twirphp/twirp |
| Dart | ✓ | github.com/apptreesoftware/protoc-gen-twirp_dart | |
| Elixir | ✓ | ✓ | github.com/keathley/twirp-elixir |
| Swift | ✓ | github.com/CrazyHulk/protoc-gen-swiftwirp | |
| Crystal | ✓ | ✓ | github.com/mloughran/twirp.cr |
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.
No description provided by the author
No description provided by the author
No description provided by the author
# Functions
AddHTTPResponseHeader behaves like SetHTTPResponseHeader, but it appends the key-value pair to the header (instead of replacing it).
ChainClientHooks creates a new *ClientHooks which chains the callbacks in each of the constituent hooks passed in.
ChainHooks creates a new *ServerHooks which chains the callbacks in each of the constituent hooks passed in.
ChainInterceptors chains multiple Interceptors into a single Interceptor.
No description provided by the author
InternalError is a convenience constructor for Internal errors.
InternalErrorf uses the formatted message as the internal error msg.
InternalErrorWith makes an internal error, wrapping the original error and using it for the error message, and with metadata "cause" with the original error type.
InvalidArgumentError is a convenience constructor for InvalidArgument errors.
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 builds a twirp.Error.
NewErrorf builds a twirp.Error with a formatted msg.
NotFoundError is a convenience constructor for NotFound errors.
PackageName extracts the fully-qualified protobuf package name of the service handling the given context.
RequiredArgumentError builds an 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").
WithClientHooks defines the hooks for a Twirp client.
WithClientInterceptors defines the interceptors for a Twirp client.
WithClientLiteralURLs configures the Twirp client to use the exact values as defined in the proto file for Service and Method names, fixing the issue https://github.com/twitchtv/twirp/issues/244, which is manifested when working with Twirp services implemented other languages (e.g.
WithClientPathPrefix specifies a different prefix to use for routing.
WithHTTPRequestHeaders stores an http.Header in a context.Context.
WithServerHooks defines the hooks for a Twirp server.
WithServerInterceptors defines the interceptors for a Twirp server.
WithServerJSONCamelCaseNames configures JSON serialization to use the default proto3 JSON encoding (lowerCamelCase) rather than the original proto field names.
WithServerJSONSkipDefaults configures JSON serialization to skip unpopulated or default values in JSON responses, which results in smaller response sizes.
WithServerPathPrefix specifies a different prefix for routing.
WrapError allows Twirp errors to wrap other errors.
WriteError writes an HTTP response with a valid Twirp error format (code, msg, meta).
# 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.
Malformed indicates an error occurred while decoding the client's request.
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 or rate-limited, perhaps a per-user quota, or perhaps the entire file system is out of space.
TwirpPackageIsVersion7 is a constant referenced from generated code to assert version compatibility at compile time.
TwirpPackageMinVersion_8_1_0 is required from generated code to assert version compatibility at compile time.
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
ClientHooks is a container for callbacks that can instrument a Twirp-generated client.
ClientOptions encapsulate the configurable parameters on a Twirp client.
ServerHooks is a container for callbacks that can instrument a Twirp-generated server.
ServerOptions encapsulate the configurable parameters on a Twirp server.
# Interfaces
Error represents an error in a Twirp service call.
# Type aliases
ClientOption is a functional option for extending a Twirp client.
ErrorCode represents a Twirp error type.
Interceptor is a form of middleware for Twirp requests, that can be installed on both clients and servers.
Method is a generic representation of a Twirp-generated RPC method.
ServerOption is a functional option for extending a Twirp service.