Documentation
¶
Overview ¶
Package handlers is the transport layer of the JSON-keys application, sitting above the service layer.
There are two transport implementations, each serving a distinct audience:
gRPC handlers: the private API for authenticated service-to-service calls, covering token signing, key retrieval, and dependency health checks. Wired by cmd/grpc.
REST handlers: the public, read-only API for token verification, exposing the JSON Web Keys without requiring authentication. Wired by cmd/rest.
All handlers translate incoming requests into service-layer calls and map the results back to protocol-level responses. They do not contain business logic.
Index ¶
- Constants
- func NewGrpcHealthStatus(err error) *protogen.DependencyHealth
- type GrpcClaimsSign
- type GrpcClaimsSignService
- type GrpcJwkGet
- type GrpcJwkGetService
- type GrpcJwkList
- type GrpcJwkListService
- type GrpcStatus
- type RestHealth
- type RestHealthStatus
- type RestJwkGet
- type RestJwkGetService
- type RestJwkList
- type RestJwkListService
- type RestPing
Constants ¶
const ( // RestHealthStatusUp is the JSON status value reported when a dependency is healthy. RestHealthStatusUp = "up" // RestHealthStatusDown is the JSON status value reported when a dependency is unhealthy. RestHealthStatusDown = "down" )
Variables ¶
This section is empty.
Functions ¶
func NewGrpcHealthStatus ¶
func NewGrpcHealthStatus(err error) *protogen.DependencyHealth
NewGrpcHealthStatus converts an error into a DependencyHealth proto message, mapping nil to DEPENDENCY_STATUS_UP and any non-nil error to DEPENDENCY_STATUS_DOWN.
The error itself is intentionally discarded from the returned message; raw dependency errors routinely embed internal hostnames, ports, or schema names that would leak infrastructure topology. Operators get the underlying error from the trace span the failing health probe records on its way out.
Types ¶
type GrpcClaimsSign ¶
type GrpcClaimsSign struct {
protogen.UnimplementedClaimsSignServiceServer
// contains filtered or unexported fields
}
GrpcClaimsSign is the gRPC handler that signs a set of claims and returns a compact JWT.
func NewGrpcClaimsSign ¶
func NewGrpcClaimsSign(service GrpcClaimsSignService) *GrpcClaimsSign
NewGrpcClaimsSign returns a new GrpcClaimsSign handler backed by the given service.
func (*GrpcClaimsSign) ClaimsSign ¶
func (handler *GrpcClaimsSign) ClaimsSign( ctx context.Context, request *protogen.ClaimsSignRequest, ) (*protogen.ClaimsSignResponse, error)
type GrpcClaimsSignService ¶
type GrpcClaimsSignService interface {
Exec(ctx context.Context, request *core.ClaimsSignRequest) (string, error)
}
GrpcClaimsSignService is the service dependency of GrpcClaimsSign.
type GrpcJwkGet ¶
type GrpcJwkGet struct {
protogen.UnimplementedJwkGetServiceServer
// contains filtered or unexported fields
}
GrpcJwkGet is the gRPC handler that retrieves a single JSON Web Key by its ID.
func NewGrpcJwkGet ¶
func NewGrpcJwkGet(service GrpcJwkGetService) *GrpcJwkGet
NewGrpcJwkGet returns a new GrpcJwkGet handler backed by the given service.
func (*GrpcJwkGet) JwkGet ¶
func (handler *GrpcJwkGet) JwkGet( ctx context.Context, request *protogen.JwkGetRequest, ) (*protogen.JwkGetResponse, error)
type GrpcJwkGetService ¶
type GrpcJwkGetService interface {
Exec(ctx context.Context, request *core.JwkSelectRequest) (*core.Jwk, error)
}
GrpcJwkGetService is the service dependency of GrpcJwkGet.
type GrpcJwkList ¶
type GrpcJwkList struct {
protogen.UnimplementedJwkListServiceServer
// contains filtered or unexported fields
}
GrpcJwkList is the gRPC handler that returns the active public keys for a given usage.
func NewGrpcJwkList ¶
func NewGrpcJwkList(service GrpcJwkListService) *GrpcJwkList
NewGrpcJwkList returns a new GrpcJwkList handler backed by the given service.
func (*GrpcJwkList) JwkList ¶
func (handler *GrpcJwkList) JwkList( ctx context.Context, request *protogen.JwkListRequest, ) (*protogen.JwkListResponse, error)
type GrpcJwkListService ¶
type GrpcJwkListService interface {
Exec(ctx context.Context, request *core.JwkSearchRequest) ([]*core.Jwk, error)
}
GrpcJwkListService is the service dependency of GrpcJwkList.
type GrpcStatus ¶
type GrpcStatus struct {
protogen.UnimplementedStatusServiceServer
}
GrpcStatus is the gRPC handler that reports the operational health of the service and its dependencies.
func NewGrpcStatus ¶
func NewGrpcStatus() *GrpcStatus
NewGrpcStatus returns a new GrpcStatus handler.
func (*GrpcStatus) Status ¶
func (handler *GrpcStatus) Status(ctx context.Context, _ *protogen.StatusRequest) (*protogen.StatusResponse, error)
type RestHealth ¶
type RestHealth struct{}
RestHealth is the HTTP handler that reports the operational health of the service and its dependencies as a JSON object.
func NewRestHealth ¶
func NewRestHealth() *RestHealth
NewRestHealth returns a new RestHealth handler.
func (*RestHealth) ServeHTTP ¶
func (handler *RestHealth) ServeHTTP(w http.ResponseWriter, r *http.Request)
type RestHealthStatus ¶
type RestHealthStatus struct {
// Status is either [RestHealthStatusUp] or [RestHealthStatusDown].
Status string `json:"status"`
}
RestHealthStatus is the JSON representation of a single dependency's health. The shape is deliberately minimal: /healthcheck is an unauthenticated public endpoint, so it must not expose raw error messages — those routinely include internal hostnames, ports, or schema names that leak infrastructure topology. The underlying error is recorded on the trace span for operators instead.
func NewRestHealthStatus ¶
func NewRestHealthStatus(err error) *RestHealthStatus
NewRestHealthStatus converts an error into a RestHealthStatus, mapping nil to RestHealthStatusUp and any non-nil error to RestHealthStatusDown. The error itself is intentionally discarded from the public response; see RestHealthStatus.
type RestJwkGet ¶
type RestJwkGet struct {
// contains filtered or unexported fields
}
RestJwkGet is the REST handler that returns a single public JWK by its ID, reading the key ID from the "id" query parameter.
func NewRestJwkGet ¶
func NewRestJwkGet(service RestJwkGetService, logger logging.Log) *RestJwkGet
NewRestJwkGet returns a new RestJwkGet handler backed by the given service.
func (*RestJwkGet) ServeHTTP ¶
func (handler *RestJwkGet) ServeHTTP(w http.ResponseWriter, r *http.Request)
type RestJwkGetService ¶
type RestJwkGetService interface {
Exec(ctx context.Context, request *core.JwkSelectRequest) (*core.Jwk, error)
}
RestJwkGetService is the service dependency of RestJwkGet.
type RestJwkList ¶
type RestJwkList struct {
// contains filtered or unexported fields
}
RestJwkList is the REST handler that returns the active public keys for a given usage, reading the usage from the "usage" query parameter.
func NewRestJwkList ¶
func NewRestJwkList(service RestJwkListService, logger logging.Log) *RestJwkList
NewRestJwkList returns a new RestJwkList handler backed by the given service.
func (*RestJwkList) ServeHTTP ¶
func (handler *RestJwkList) ServeHTTP(w http.ResponseWriter, r *http.Request)
type RestJwkListService ¶
type RestJwkListService interface {
Exec(ctx context.Context, request *core.JwkSearchRequest) ([]*core.Jwk, error)
}
RestJwkListService is the service dependency of RestJwkList.