twirp

package module
v0.0.0-...-0905f47 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 18, 2020 License: Apache-2.0 Imports: 11 Imported by: 8

README

twirp

twirp 框架已经整合到 sniper 框架，具体参见

https://github.com/bilibili/sniper/commit/d867599121ac9dc85aec12ca077f0d5fdc0aca48

原版请参考：https://github.com/twitchtv/twirp

移动 App 框架不方便在调接口的时候发送 json 数据，所以给 twirp 引入了表单支持。

另外还支持修改 /twirp 接口前缀，注入服务扩展信息等功能。

Documentation

Overview

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.

DO NOT USE CTXSETTERS OUTSIDE OF TWIRP'S GENERATED CODE.

Package twirp provides core types used in generated Twirp servers and client.

Twirp services handle errors using the `twirp.Error` interface.

For example, a server method may return an InvalidArgumentError: 

if req.Order != "DESC" && req.Order != "ASC" {
    return nil, twirp.InvalidArgumentError("Order", "must be DESC or ASC")
}

And the same twirp.Error is returned by the client, for example: 

resp, err := twirpClient.RPCMethod(ctx, req)
if err != nil {
    if twerr := err.(twirp.Error) {
        switch twerr.Code() {
        case twirp.InvalidArgument:
            log.Error("invalid argument "+twirp.Meta("argument"))
        default:
            log.Error(twerr.Error())
        }
    }
}

Clients may also return Internal errors if something failed on the system: the server, the network, or the client itself (i.e. failure parsing response).

Index

Constants

View Source 
const (
	MethodNameKey contextKey = 1 + iota
	ServiceNameKey
	PackageNameKey
	StatusCodeKey
	RequestHeaderKey
	ResponseWriterKey
	RequestKey
	ResponseKey
	AllowGETKey
	MethodOptionKey
)

Variables

This section is empty.

Functions

func AddHTTPResponseHeader 

func AddHTTPResponseHeader(ctx context.Context, key, value string) error

AddHTTPResponseHeader adds an HTTP header key-value pair using a context provided by a twirp-generated server, or a child of that context. The server will include the header in its response for that request context.

func AllowGET 

func AllowGET(ctx context.Context) bool

AllowGET check whether allow the current request using post method.

func DoJSONRequest 

func DoJSONRequest(ctx context.Context, client HTTPClient, url string, in, out proto.Message) (err error)

DoJSONRequest is common code to make a request to the remote twirp service.

func DoProtobufRequest 

func DoProtobufRequest(ctx context.Context, client HTTPClient, url string, in, out proto.Message) (err error)

DoProtobufRequest is common code to make a request to the remote twirp service.

func HTTPRequestHeaders 

func HTTPRequestHeaders(ctx context.Context) (http.Header, bool)

func IsValidErrorCode 

func IsValidErrorCode(code ErrorCode) bool

IsValidErrorCode returns true if is one of the valid predefined constants.

func MethodName 

func MethodName(ctx context.Context) (string, bool)

MethodName extracts the name of the method being handled in the given context. If it is not known, it returns ("", false).

func MethodOption 

func MethodOption(ctx context.Context) (string, bool)

MethodOption retrieves the option of service method. If it is known returns (string, true). If it is not known, it returns ("", false).

func PackageName 

func PackageName(ctx context.Context) (string, bool)

PackageName extracts the fully-qualified protobuf package name of the service handling the given context. If it is not known, it returns ("", false). If the service comes from a proto file that does not declare a package name, it returns ("", true).

Note that the protobuf package name can be very different than the go package name; the two are unrelated.

func Request 

func Request(ctx context.Context) (*http.Request, bool)

Request retrieves the request. If it is known returns (req, true). If it is not known, it returns (nil, false).

func Response 

func Response(ctx context.Context) (proto.Message, bool)

Response retrieves the response. If it is known returns (resp, true). If it is not known, it returns (nil, false).

func ServerHTTPStatusFromErrorCode 

func ServerHTTPStatusFromErrorCode(code ErrorCode) int

ServerHTTPStatusFromErrorCode maps a Twirp error type into a similar HTTP response status. It is used by the Twirp server handler to set the HTTP response status code. Returns 0 if the ErrorCode is invalid.

func ServiceName 

func ServiceName(ctx context.Context) (string, bool)

ServiceName extracts the name of the service handling the given context. If it is not known, it returns ("", false).

func SetHTTPResponseHeader 

func SetHTTPResponseHeader(ctx context.Context, key, value string) error

SetHTTPResponseHeader sets an HTTP header key-value pair using a context provided by a twirp-generated server, or a child of that context. The server will include the header in its response for that request context.

This can be used to respond with custom HTTP headers like "Cache-Control". But note that HTTP headers are a Twirp implementation detail, only visible by middleware, not by the clients or their responses.

The header will be ignored (noop) if the context is invalid (i.e. using a new context.Background() instead of passing the context from the handler).

If called multiple times with the same key, it replaces any existing values associated with that key.

SetHTTPResponseHeader returns an error if the provided header key would overwrite a header that is needed by Twirp, like "Content-Type".

func StatusCode 

func StatusCode(ctx context.Context) (string, bool)

StatusCode retrieves the status code of the response (as string like "200"). If it is known returns (status, true). If it is not known, it returns ("", false).

func WithAllowGET 

func WithAllowGET(ctx context.Context, f bool) context.Context

WithAllowGET allow get method.

func WithHTTPRequestHeaders 

func WithHTTPRequestHeaders(ctx context.Context, h http.Header) (context.Context, error)

WithHTTPRequestHeaders stores an http.Header in a context.Context. When using a Twirp-generated client, you can pass the returned context into any of the request methods, and the stored header will be included in outbound HTTP requests.

This can be used to set custom HTTP headers like authorization tokens or client IDs. But note that HTTP headers are a Twirp implementation detail, only visible by middleware, not by the server implementation.

WithHTTPRequestHeaders returns an error if the provided http.Header would overwrite a header that is needed by Twirp, like "Content-Type".

func WithMethodName 

func WithMethodName(ctx context.Context, name string) context.Context

func WithMethodOption 

func WithMethodOption(ctx context.Context, option string) context.Context

func WithPackageName 

func WithPackageName(ctx context.Context, name string) context.Context

func WithRequest 

func WithRequest(ctx context.Context, r *http.Request) context.Context

func WithResponse 

func WithResponse(ctx context.Context, resp proto.Message) context.Context

func WithResponseWriter 

func WithResponseWriter(ctx context.Context, w http.ResponseWriter) context.Context

func WithServiceName 

func WithServiceName(ctx context.Context, name string) context.Context

func WithStatusCode 

func WithStatusCode(ctx context.Context, code int) context.Context

Types

type Error 

type Error interface {
	// Code is of the valid error codes.
	Code() ErrorCode

	// Msg returns a human-readable, unstructured messages describing the error.
	Msg() string

	// WithMeta returns a copy of the Error with the given key-value pair attached
	// as metadata. If the key is already set, it is overwritten.
	WithMeta(key string, val string) Error

	// Meta returns the stored value for the given key. If the key has no set
	// value, Meta returns an empty string. There is no way to distinguish between
	// an unset value and an explicit empty string.
	Meta(key string) string

	// MetaMap returns the complete key-value metadata map stored on the error.
	MetaMap() map[string]string

	// Error returns a string of the form "twirp error <Type>: <Msg>"
	Error() string
}

Error represents an error in a Twirp service call.

func InternalError 

func InternalError(msg string) Error

InternalError constructor for the common Internal error. Should be used to specify that something bad or unexpected happened.

func InternalErrorWith 

func InternalErrorWith(err error) Error

InternalErrorWith is an easy way to wrap another error. It adds the underlying error's type as metadata with a key of "cause", which can be useful for debugging. Should be used in the common case of an unexpected error returned from another API, but sometimes it is better to build a more specific error (like with NewError(Unknown, err.Error()), for example).

The returned error also has a Cause() method which will return the original error, if it is known. This can be used with the github.com/pkg/errors package to extract the root cause of an error. Information about the root cause of an error is lost when it is serialized, so this doesn't let a client know the exact root cause of a server's error.

func InvalidArgumentError 

func InvalidArgumentError(argument string, validationMsg string) Error

InvalidArgumentError constructor for the common InvalidArgument error. Can be used when an argument has invalid format, is a number out of range, is a bad option, etc).

func NewError 

func NewError(code ErrorCode, msg string) Error

NewError is the generic constructor for a twirp.Error. The ErrorCode must be one of the valid predefined constants, otherwise it will be converted to an error {type: Internal, msg: "invalid error type {{code}}"}. If you need to add metadata, use .WithMeta(key, value) method after building the error.

func NotFoundError 

func NotFoundError(msg string) Error

NotFoundError constructor for the common NotFound error.

func RequiredArgumentError 

func RequiredArgumentError(argument string) Error

RequiredArgumentError is a more specific constructor for InvalidArgument error. Should be used when the argument is required (expected to have a non-zero value).

type ErrorCode 

type ErrorCode string

ErrorCode represents a Twirp error type. 

const (
	// Canceled indicates the operation was cancelled (typically by the caller).
	Canceled ErrorCode = "canceled"

	// Unknown error. For example when handling errors raised by APIs that do not
	// return enough error information.
	Unknown ErrorCode = "unknown"

	// InvalidArgument indicates client specified an invalid argument. It
	// indicates arguments that are problematic regardless of the state of the
	// system (i.e. a malformed file name, required argument, number out of range,
	// etc.).
	InvalidArgument ErrorCode = "invalid_argument"

	// DeadlineExceeded means operation expired before completion. For operations
	// that change the state of the system, this error may be returned even if the
	// operation has completed successfully (timeout).
	DeadlineExceeded ErrorCode = "deadline_exceeded"

	// NotFound means some requested entity was not found.
	NotFound ErrorCode = "not_found"

	// BadRoute means that the requested URL path wasn't routable to a Twirp
	// service and method. This is returned by the generated server, and usually
	// shouldn't be returned by applications. Instead, applications should use
	// NotFound or Unimplemented.
	BadRoute ErrorCode = "bad_route"

	// AlreadyExists means an attempt to create an entity failed because one
	// already exists.
	AlreadyExists ErrorCode = "already_exists"

	// PermissionDenied indicates the caller does not have permission to execute
	// the specified operation. It must not be used if the caller cannot be
	// identified (Unauthenticated).
	PermissionDenied ErrorCode = "permission_denied"

	// Unauthenticated indicates the request does not have valid authentication
	// credentials for the operation.
	Unauthenticated ErrorCode = "unauthenticated"

	// ResourceExhausted indicates some resource has been exhausted, perhaps a
	// per-user quota, or perhaps the entire file system is out of space.
	ResourceExhausted ErrorCode = "resource_exhausted"

	// FailedPrecondition indicates operation was rejected because the system is
	// not in a state required for the operation's execution. For example, doing
	// an rmdir operation on a directory that is non-empty, or on a non-directory
	// object, or when having conflicting read-modify-write on the same resource.
	FailedPrecondition ErrorCode = "failed_precondition"

	// Aborted indicates the operation was aborted, typically due to a concurrency
	// issue like sequencer check failures, transaction aborts, etc.
	Aborted ErrorCode = "aborted"

	// OutOfRange means operation was attempted past the valid range. For example,
	// seeking or reading past end of a paginated collection.
	//
	// Unlike InvalidArgument, this error indicates a problem that may be fixed if
	// the system state changes (i.e. adding more items to the collection).
	//
	// There is a fair bit of overlap between FailedPrecondition and OutOfRange.
	// We recommend using OutOfRange (the more specific error) when it applies so
	// that callers who are iterating through a space can easily look for an
	// OutOfRange error to detect when they are done.
	OutOfRange ErrorCode = "out_of_range"

	// Unimplemented indicates operation is not implemented or not
	// supported/enabled in this service.
	Unimplemented ErrorCode = "unimplemented"

	// Internal errors. When some invariants expected by the underlying system
	// have been broken. In other words, something bad happened in the library or
	// backend service. Do not confuse with HTTP Internal Server Error; an
	// Internal error could also happen on the client code, i.e. when parsing a
	// server response.
	Internal ErrorCode = "internal"

	// Unavailable indicates the service is currently unavailable. This is a most
	// likely a transient condition and may be corrected by retrying with a
	// backoff.
	Unavailable ErrorCode = "unavailable"

	// DataLoss indicates unrecoverable data loss or corruption.
	DataLoss ErrorCode = "data_loss"

	// NoError is the zero-value, is considered an empty error and should not be
	// used.
	NoError ErrorCode = ""
)

Valid Twirp error types. Most error types are equivalent to gRPC status codes and follow the same semantics.

type HTTPClient 

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HTTPClient is the interface used by generated clients to send HTTP requests. It is fulfilled by *(net/http).Client, which is sufficient for most users. Users can provide their own implementation for special retry policies.

HTTPClient implementations should not follow redirects. Redirects are automatically disabled if *(net/http).Client is passed to client constructors. See the withoutRedirects function in this file for more details.

type Server 

type Server interface {
	http.Handler
	// ServiceDescriptor returns gzipped bytes describing the .proto file that
	// this service was generated from. Once unzipped, the bytes can be
	// unmarshalled as a
	// github.com/golang/protobuf/protoc-gen-go/descriptor.FileDescriptorProto.
	//
	// The returned integer is the index of this particular service within that
	// FileDescriptorProto's 'Service' slice of ServiceDescriptorProtos. This is a
	// low-level field, expected to be used for reflection.
	ServiceDescriptor() ([]byte, int)
	// ProtocGenTwirpVersion is the semantic version string of the version of
	// twirp used to generate this file.
	ProtocGenTwirpVersion() string
}

Server is the interface generated server structs will support: they're HTTP handlers with additional methods for accessing metadata about the service. Those accessors are a low-level API for building reflection tools. Most people can think of TwirpServers as just http.Handlers.

type ServerHooks 

type ServerHooks struct {
	// RequestReceived is called as soon as a request enters the Twirp
	// server at the earliest available moment.
	RequestReceived func(context.Context) (context.Context, error)

	// RequestRouted is called when a request has been routed to a
	// particular method of the Twirp server.
	RequestRouted func(context.Context) (context.Context, error)

	// ResponsePrepared is called when a request has been handled and a
	// response is ready to be sent to the client.
	ResponsePrepared func(context.Context) context.Context

	// ResponseSent is called when all bytes of a response (including an error
	// response) have been written. Because the ResponseSent hook is terminal, it
	// does not return a context.
	ResponseSent func(context.Context)

	// Error hook is called when an error occurs while handling a request. The
	// Error is passed as argument to the hook.
	Error func(context.Context, Error) context.Context
}

ServerHooks is a container for callbacks that can instrument a Twirp-generated server. These callbacks all accept a context and return a context. They can use this to add to the request context as it threads through the system, appending values or deadlines to it.

The RequestReceived and RequestRouted hooks are special: they can return errors. If they return a non-nil error, handling for that request will be stopped at that point. The Error hook will be triggered, and the error will be sent to the client. This can be used for stuff like auth checks before deserializing a request.

The RequestReceived hook is always called first, and it is called for every request that the Twirp server handles. The last hook to be called in a request's lifecycle is always ResponseSent, even in the case of an error.

Details on the timing of each hook are documented as comments on the fields of the ServerHooks type.

func ChainHooks 

func ChainHooks(hooks ...*ServerHooks) *ServerHooks

ChainHooks creates a new *ServerHooks which chains the callbacks in each of the constituent hooks passed in. Each hook function will be called in the order of the ServerHooks values passed in.

For the erroring hooks, RequestReceived and RequestRouted, any returned errors prevent processing by later hooks.

func (*ServerHooks) CallError 

func (h *ServerHooks) CallError(ctx context.Context, err Error) context.Context

CallError call twirp.ServerHooks.Error if the hook is available

func (*ServerHooks) CallRequestReceived 

func (h *ServerHooks) CallRequestReceived(ctx context.Context) (context.Context, error)

CallRequestReceived call twirp.ServerHooks.RequestReceived if the hook is available

func (*ServerHooks) CallRequestRouted 

func (h *ServerHooks) CallRequestRouted(ctx context.Context) (context.Context, error)

CallRequestRouted call twirp.ServerHooks.RequestRouted if the hook is available

func (*ServerHooks) CallResponsePrepared 

func (h *ServerHooks) CallResponsePrepared(ctx context.Context) context.Context

CallResponsePrepared call twirp.ServerHooks.ResponsePrepared if the hook is available

func (*ServerHooks) CallResponseSent 

func (h *ServerHooks) CallResponseSent(ctx context.Context)

CallResponseSent call twirp.ServerHooks.ResponseSent if the hook is available

func (*ServerHooks) WriteError 

func (h *ServerHooks) WriteError(ctx context.Context, resp http.ResponseWriter, err error)

WriteError writes Twirp errors in the response and triggers hooks.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.