Documentation
¶
Overview ¶
Package api describes the APIs a service serves, independently of deployment. Managed APIs are served by the SDK; declarations passed to Service.API describe the author's own listener. Publication and protocol conversion belong to the application and deployment. Middleware and interceptors execute inside the service.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Decl ¶
type Decl struct {
// contains filtered or unexported fields
}
Decl describes an API served on the author's own listener. Build one with GRPC, HTTP, GraphQL or WSProto.
func GRPC ¶
func GRPC(service string, opts ...GRPCDeclOption) Decl
GRPC declares a gRPC service (full name) the author serves.
func GraphQL ¶
func GraphQL(prefix string, introspection []byte, opts ...DeclOption) Decl
GraphQL declares a GraphQL endpoint the author serves, with its introspection result (JSON); nil when there is none.
func HTTP ¶
func HTTP(prefix string, opts ...HTTPDeclOption) Decl
HTTP declares an HTTP prefix the author serves.
type DeclOption ¶
type DeclOption interface {
// contains filtered or unexported methods
}
DeclOption configures api.GraphQL and api.WSProto.
type GRPCDeclOption ¶
type GRPCDeclOption interface {
// contains filtered or unexported methods
}
GRPCDeclOption configures api.GRPC.
func Descriptors ¶
func Descriptors(fds []byte) GRPCDeclOption
Descriptors attaches a serialized FileDescriptorSet to a declarative gRPC route; managed routes derive descriptors from registration.
type GRPCOption ¶
type GRPCOption interface {
// contains filtered or unexported methods
}
GRPCOption configures Service.GRPC.
func Reflection ¶
func Reflection() GRPCOption
Reflection serves grpc.reflection (v1 and v1alpha) on this route's port, once per port, for grpcurl and similar tools. It is not announced to external routing: it answers on the port directly.
type GraphQLFSOption ¶
type GraphQLFSOption interface {
HTTPOption
DeclOption
}
GraphQLFSOption attaches a separately delivered introspection document.
type HTTPDeclOption ¶
type HTTPDeclOption interface {
// contains filtered or unexported methods
}
HTTPDeclOption configures api.HTTP.
type HTTPOption ¶
type HTTPOption interface {
// contains filtered or unexported methods
}
HTTPOption configures Service.HTTP and Service.GraphQL.
type HostOption ¶
type HostOption interface {
HTTPOption
WSProtoOption
GRPCDeclOption
HTTPDeclOption
DeclOption
}
HostOption applies to managed HTTP/ws-proto APIs and API declarations.
func Host ¶
func Host(h string) HostOption
Host matches the route by Host header in addition to its prefix: an exact host ("api.example.com") or a wildcard ("*.example.com"). Managed HTTP routes with one prefix and different hosts share a port.
type InterceptorOption ¶
type InterceptorOption interface {
GRPCOption
WSProtoOption
}
InterceptorOption applies to Service.GRPC, Service.Internal and wsproto.Serve.
func Interceptors ¶
func Interceptors(i ...grpc.UnaryServerInterceptor) InterceptorOption
Interceptors wrap the unary calls of this registration's services only, the first outermost, inside the SDK's recovery and tracing. The same register function passed to Service.GRPC and wsproto.Serve takes them separately.
func StreamInterceptors ¶
func StreamInterceptors(i ...grpc.StreamServerInterceptor) InterceptorOption
StreamInterceptors wrap the streaming calls of this registration's services only, the first outermost.
type ListenOption ¶
type ListenOption interface {
GRPCOption
HTTPOption
WSProtoOption
}
ListenOption applies to managed routes.
func Listen ¶
func Listen(addr string) ListenOption
Listen serves a managed route on its own listener instead of the shared public port; routes with the same address share one server.
type MTLSOption ¶ added in v0.6.20
type MTLSOption interface {
GRPCOption
HTTPOption
WSProtoOption
}
MTLSOption applies to Service.GRPC, Service.HTTP, Service.GraphQL and wsproto.Serve.
func MTLS ¶ added in v0.6.20
func MTLS() MTLSOption
MTLS serves the route's port to services of the mesh only: mutual TLS with the certificates of the installed driver (Consul's CA), every call authorized by the mesh's rules (Consul intentions) and its caller in backplane.CallerOf. A port is mTLS or not as a whole: every route on it says the same, or Run fails. Without the driver or Consul, Run fails. Clients call it with Root.ServiceCredentials (gRPC) or Root.ServiceTLS.
type MiddlewareOption ¶
type MiddlewareOption interface {
HTTPOption
WSProtoOption
}
MiddlewareOption applies to Service.HTTP, Service.GraphQL and wsproto.Serve.
func Middleware ¶
func Middleware(mw func(http.Handler) http.Handler) MiddlewareOption
Middleware wraps this route's handler; repeated, the first is outermost. On ws-proto it runs once per connection, around its whole life: it sees the upgrade request and rejects it by answering without calling next; the request context it passes to next is the connection's, every call's context derives from it and canceling it closes the connection; next returns when the connection has closed.
type OpenAPIOption ¶
type OpenAPIOption interface {
HTTPOption
HTTPDeclOption
}
OpenAPIOption applies to HTTP routes.
func OpenAPI ¶
func OpenAPI(spec []byte) OpenAPIOption
OpenAPI attaches a self-contained OpenAPI document (JSON or YAML) to an HTTP API. spec can be a []byte populated by go:embed. Bundle multi-file specifications with internal $ref links before embedding, or use OpenAPIFS to carry several files without bundling. Each HTTP route may carry its own document; a service can announce multiple routes.
func OpenAPIFS ¶
func OpenAPIFS(files fs.FS, entry string) OpenAPIOption
OpenAPIFS publishes a directory of OpenAPI JSON/YAML files with a root document. It accepts embed.FS or any fs.FS; use fs.Sub to select the API directory. Relative $ref links stay inside that directory. Files are snapshotted once; only the snapshot's hash and entry path enter the manifest. No bundler is needed. Declaration failures are returned by Service.Run, like other route errors.
type Origins ¶
type Origins struct {
// contains filtered or unexported fields
}
Origins is the browser origin policy of a WebSocket endpoint (ws-proto). It is a required argument where it applies; the zero value allows only same-origin browsers and non-browser clients.
func AllowOrigins ¶
AllowOrigins accepts upgrades from browsers on these host patterns ("app.example.com", "*.example.com") in addition to same-origin ones.
func AnyOrigin ¶
func AnyOrigin() Origins
AnyOrigin accepts every origin: for endpoints that authenticate each call themselves and never rely on cookies.
type PortOption ¶
type PortOption interface {
GRPCDeclOption
HTTPDeclOption
DeclOption
}
PortOption applies to declarative routes.
func Port ¶
func Port(p uint16) PortOption
Port is where the author serves a declarative route; 0 means the port registered in Consul.
type WSProtoOption ¶
type WSProtoOption interface {
// contains filtered or unexported methods
}
WSProtoOption configures wsproto.Serve.
func CallMiddleware ¶ added in v0.6.46
func CallMiddleware(mw ...wsrpc.Middleware) WSProtoOption
CallMiddleware wraps every call of a ws-proto endpoint, however its services were registered, the first outermost, inside the SDK's recovery and tracing. Its context is the call's, derived from the connection's (see Middleware).
func Keepalive ¶ added in v0.6.46
func Keepalive(interval, timeout time.Duration) WSProtoOption
Keepalive pings the clients of a ws-proto endpoint every interval and closes a connection whose pong does not come within timeout; interval <= 0 disables pinging. Without it: every 20s, timeout 10s.