api

package
v0.6.14 Latest Latest
Warning

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

Go to latest
Published: Oct 17, 2026 License: MIT Imports: 8 Imported by: 2

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.

func WSProto

func WSProto(prefix string, descriptors []byte, opts ...DeclOption) Decl

WSProto declares a ws-proto endpoint the author serves, with its serialized FileDescriptorSet; nil when there is none.

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.

func GraphQLFS

func GraphQLFS(files fs.FS, entry string) GraphQLFSOption

GraphQLFS publishes GraphQL introspection JSON outside the manifest. Pass nil as Service.GraphQL's inline introspection when using this option.

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

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 and wsproto.Serve.

func Interceptors

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 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 sees the upgrade request.

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

func AllowOrigins(patterns ...string) Origins

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.

func (Origins) IsAny

func (o Origins) IsAny() bool

IsAny reports whether every origin is accepted.

func (Origins) Patterns

func (o Origins) Patterns() []string

Patterns are the accepted host patterns.

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL