Repository navigation
feat(sdk): HealthCheck(ctx, service) #3379
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 4 commits
d23552b
6991a5f
ad6dd9e
ff55f3a
dcbf1c7
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -32,9 +32,12 @@ import ( | |
| const ( | ||
| // Failure while connecting to a service. | ||
| // Check your configuration and/or retry. | ||
| ErrGrpcDialFailed = Error("failed to dial grpc endpoint") | ||
| ErrShutdownFailed = Error("failed to shutdown sdk") | ||
| ErrPlatformUnreachable = Error("platform unreachable or not responding") | ||
| ErrGrpcDialFailed = Error("failed to dial grpc endpoint") | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. nit: alignment inconsistency |
||
| ErrShutdownFailed = Error("failed to shutdown sdk") | ||
| ErrPlatformUnreachable = Error("platform unreachable or not responding") | ||
| // ErrHealthCheckUnsupported is returned by SDK.HealthCheck when the SDK is configured | ||
| // in IPC mode, which does not support the gRPC Health protocol. | ||
| ErrHealthCheckUnsupported = Error("health check not supported in IPC mode") | ||
| ErrPlatformConfigFailed = Error("failed to retrieve platform configuration") | ||
| ErrPlatformEndpointMalformed = Error("platform endpoint is malformed") | ||
| ErrPlatformIssuerNotFound = Error("issuer not found in well-known idp configuration") | ||
|
|
@@ -58,6 +61,33 @@ func (c Error) Error() string { | |
| return string(c) | ||
| } | ||
|
|
||
| // HealthStatus is the serving status reported by the platform's gRPC Health v1 endpoint. | ||
| // It mirrors google.golang.org/grpc/health/grpc_health_v1.HealthCheckResponse_ServingStatus | ||
| // so callers do not need to import the grpc health protobuf to branch on results. | ||
| type HealthStatus int | ||
|
|
||
| const ( | ||
| // HealthStatusUnknown means the platform could not determine status, or the requested | ||
| // service is not registered on this deployment. | ||
| HealthStatusUnknown HealthStatus = iota | ||
| // HealthStatusServing means the requested scope reports SERVING. | ||
| HealthStatusServing | ||
| // HealthStatusNotServing means the requested scope was reached but reports NOT_SERVING. | ||
| HealthStatusNotServing | ||
| ) | ||
|
|
||
| // String returns the uppercase name of the status. Unknown or out-of-range values render as "UNKNOWN". | ||
| func (s HealthStatus) String() string { | ||
| switch s { //nolint:exhaustive // default intentionally covers HealthStatusUnknown and any future out-of-range values | ||
| case HealthStatusServing: | ||
| return "SERVING" | ||
| case HealthStatusNotServing: | ||
| return "NOT_SERVING" | ||
| default: | ||
| return "UNKNOWN" | ||
| } | ||
| } | ||
|
|
||
| // getLogger returns the package-level logger, defaulting to slog.Default() if not set to | ||
| // provide access to the logger in exported functions where signatures are unable to be altered | ||
| func getLogger() *slog.Logger { | ||
|
|
@@ -310,6 +340,57 @@ func (s SDK) Conn() *ConnectRPCConnection { | |
| return s.conn | ||
| } | ||
|
|
||
| // HealthCheck queries the platform's gRPC Health v1 endpoint (grpc.health.v1.Health/Check) | ||
| // and returns the reported serving status. | ||
| // | ||
| // The service argument selects the check scope: | ||
| // | ||
| // - "" — reachability check. Returns SERVING if the health handler responds. Does | ||
| // not exercise any registered readiness probe. | ||
| // - "all" — runs every readiness check the platform has registered. Returns | ||
| // NOT_SERVING if any registered service reports an error. | ||
| // - other — runs only the named service's readiness check (e.g. "kas", "authorization"). | ||
| // Returns HealthStatusUnknown if the service is not registered on this deployment. | ||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The valid values for service ("", "all", "kas", "authorization", etc.) are documented here but there are no constants for them. Consider exported constants like HealthServiceAll = "all" (even just for "all" and "") for discoverability since this is a public SDK API. (Or at minimum, a note in the README/docs listing the known service names)
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @pflynn-virtru Any reason not to just simplify this to |
||
| // | ||
| // The call honors ctx for deadline, cancellation, and trace-context propagation. Callers are | ||
| // expected to manage timeouts via context.WithTimeout and to drive probe cadence / retry themselves. | ||
| // | ||
| // OTEL tracing works automatically when the caller has registered otelconnect.NewInterceptor() | ||
| // via sdk.WithExtraClientOptions at SDK construction time. The SDK does not emit spans of its own. | ||
| // | ||
| // Returns (HealthStatusServing, nil) on SERVING; (HealthStatusNotServing, nil) on NOT_SERVING; | ||
| // (HealthStatusUnknown, nil) on UNKNOWN / SERVICE_UNKNOWN; (HealthStatusUnknown, err wrapping | ||
| // ErrPlatformUnreachable) on any transport failure including ctx errors; and | ||
| // (HealthStatusUnknown, ErrHealthCheckUnsupported) when the SDK is in IPC mode. | ||
| func (s SDK) HealthCheck(ctx context.Context, service string) (HealthStatus, error) { | ||
| if s.ipc || s.conn == nil { | ||
| return HealthStatusUnknown, ErrHealthCheckUnsupported | ||
| } | ||
| status, err := checkPlatformHealth(ctx, s.conn.Endpoint, service, s.conn.Client, s.conn.Options) | ||
| if err != nil { | ||
| // Unregistered services can surface in two ways depending on the server | ||
| // implementation. The OpenTDF platform's handler reports them via proto | ||
| // HealthCheckResponse_UNKNOWN, which falls through to the switch default | ||
| // below. Generic grpchealth servers (e.g. grpchealth.NewStaticChecker, | ||
| // which the SDK tests use) surface them as a Connect not_found error. | ||
| // Both paths map to HealthStatusUnknown with no transport-error wrapper. | ||
| var connErr *connect.Error | ||
| if errors.As(err, &connErr) && connErr.Code() == connect.CodeNotFound { | ||
| return HealthStatusUnknown, nil | ||
| } | ||
| return HealthStatusUnknown, errors.Join(ErrPlatformUnreachable, err) | ||
| } | ||
| switch status { //nolint:exhaustive // default intentionally covers UNKNOWN and SERVICE_UNKNOWN | ||
| case healthpb.HealthCheckResponse_SERVING: | ||
| return HealthStatusServing, nil | ||
| case healthpb.HealthCheckResponse_NOT_SERVING: | ||
| return HealthStatusNotServing, nil | ||
| default: | ||
| // UNKNOWN and SERVICE_UNKNOWN both map to HealthStatusUnknown. | ||
| return HealthStatusUnknown, nil | ||
| } | ||
| } | ||
|
|
||
| type TdfType string | ||
|
|
||
| const ( | ||
|
|
@@ -413,21 +494,40 @@ func isValidManifest(manifest string, intensity SchemaValidationIntensity) (bool | |
| return true, nil | ||
| } | ||
|
|
||
| // Test connectability to the platform and validate a healthy status | ||
| func validateHealthyPlatformConnection(platformEndpoint string, httpClient *http.Client, options []connect.ClientOption) error { | ||
| // checkPlatformHealth issues a single gRPC Health v1 Check against the platform health endpoint. | ||
| // ctx controls deadline, cancellation, and trace-context propagation. service selects scope: | ||
| // "" = reachability, "all" = every registered readiness probe, otherwise a specific service name. | ||
| func checkPlatformHealth( | ||
| ctx context.Context, | ||
| endpoint, service string, | ||
| httpClient *http.Client, | ||
| options []connect.ClientOption, | ||
| ) (healthpb.HealthCheckResponse_ServingStatus, error) { | ||
| healthClient := connect.NewClient[healthpb.HealthCheckRequest, healthpb.HealthCheckResponse]( | ||
| httpClient, | ||
| platformEndpoint+"/grpc.health.v1.Health/Check", | ||
| endpoint+"/grpc.health.v1.Health/Check", | ||
|
pflynn-virtru marked this conversation as resolved.
Resolved
|
||
| options..., | ||
| ) | ||
| res, err := healthClient.CallUnary( | ||
| context.Background(), | ||
| connect.NewRequest(&healthpb.HealthCheckRequest{}), | ||
| ) | ||
| if err != nil || res.Msg.GetStatus() != healthpb.HealthCheckResponse_SERVING { | ||
| return errors.Join(ErrPlatformUnreachable, err) | ||
| res, err := healthClient.CallUnary(ctx, connect.NewRequest(&healthpb.HealthCheckRequest{Service: service})) | ||
| if err != nil { | ||
| return healthpb.HealthCheckResponse_UNKNOWN, err | ||
| } | ||
| return res.Msg.GetStatus(), nil | ||
| } | ||
|
|
||
| // validateHealthyPlatformConnection is the construction-time reachability gate used by New when | ||
| // WithConnectionValidation is set. It uses context.Background() to preserve today's behavior. | ||
| // Callers pass cfg.extraClientOptions (pre-auth) because the auth and audit interceptors are | ||
| // assembled after this gate fires; the runtime SDK.HealthCheck method uses the post-interceptor | ||
| // s.conn.Options instead. | ||
| func validateHealthyPlatformConnection(platformEndpoint string, httpClient *http.Client, options []connect.ClientOption) error { | ||
| status, err := checkPlatformHealth(context.Background(), platformEndpoint, "", httpClient, options) | ||
| if err != nil { | ||
| return errors.Join(ErrPlatformUnreachable, err) | ||
| } | ||
| if status != healthpb.HealthCheckResponse_SERVING { | ||
| return errors.Join(ErrPlatformUnreachable, fmt.Errorf("platform health status %q", status)) | ||
| } | ||
| return nil | ||
| } | ||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
nit (non-blocking): You already flagged this in the PR description —
grpchealthis test-only but Go modules can't express that, so this promotes it to a direct dep in sdk/go.mod for all downstream consumers.Can we move newHealthTestServer into
sdk/internal/healthtest/with its own go.mod? That keeps grpchealth out of the SDK's public dependency surface. Fine as a follow-up commit on this PR or a separate PR — no need to block on it.