Documentation
¶
Overview ¶
Package info exposes build metadata, health probes, and OpenAPI endpoints. See ExampleInfoHandler_full for a runnable wiring of the handler and probes.
Index ¶
- type InfoHandler
- func (ih *InfoHandler) GetHealthz(w http.ResponseWriter, r *http.Request)
- func (ih *InfoHandler) GetOpenAPIHTML(w http.ResponseWriter, r *http.Request)
- func (ih *InfoHandler) GetOpenAPIJSON(w http.ResponseWriter, r *http.Request)
- func (ih *InfoHandler) GetReadyz(w http.ResponseWriter, r *http.Request)
- func (ih *InfoHandler) GetStatus(w http.ResponseWriter, r *http.Request)
- func (ih *InfoHandler) GetVersion(w http.ResponseWriter, r *http.Request)
- type InfoOption
- func WithBaseURL(baseURL string) InfoOption
- func WithInfoProvider(provider InfoProvider) InfoOption
- func WithInfoResponder(responder *responder.Responder) InfoOption
- func WithLivenessChecks(checks ...ProbeFunc) InfoOption
- func WithOpenAPITemplate(tmpl *template.Template) InfoOption
- func WithOpenAPITemplateData(provider TemplateDataProvider) InfoOption
- func WithProbeTimeout(timeout time.Duration) InfoOption
- func WithReadinessChecks(checks ...ProbeFunc) InfoOption
- func WithSwaggerProvider(provider SwaggerProvider) InfoOption
- type InfoProvider
- type ProbeFunc
- type SwaggerProvider
- type TemplateDataProvider
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type InfoHandler ¶
InfoHandler wires the generated OpenAPI handlers with auxiliary endpoints that expose build information, status checks, and a pre-built HTML UI.
Example (CustomTemplate) ¶
package main
import (
"fmt"
"html/template"
"net/http"
"net/http/httptest"
"strings"
"github.com/drblury/apiweaver/info"
)
func main() {
handler := info.NewInfoHandler(
info.WithBaseURL("https://api.example.com"),
info.WithOpenAPITemplate(template.Must(template.New("docs").Parse(`<div>{{.DocsURL}}</div>`))),
info.WithOpenAPITemplateData(func(r *http.Request, baseURL string) any {
return map[string]string{
"DocsURL": baseURL + "/info/openapi.json",
}
}),
)
req := httptest.NewRequest(http.MethodGet, "/docs", nil)
rr := httptest.NewRecorder()
handler.GetOpenAPIHTML(rr, req)
fmt.Println(rr.Code)
fmt.Println(strings.TrimSpace(rr.Body.String()))
}
Output: 200 <div>https://api.example.com/info/openapi.json</div>
Example (Full) ¶
package main
import (
"context"
"fmt"
"net/http"
"net/http/httptest"
"strings"
"github.com/drblury/apiweaver/info"
"github.com/drblury/apiweaver/probe"
)
func main() {
handler := info.NewInfoHandler(
info.WithBaseURL("/docs"),
info.WithInfoProvider(func() any {
return map[string]string{"version": "1.2.3"}
}),
info.WithSwaggerProvider(func() ([]byte, error) {
return []byte(`{"openapi":"3.1.0","info":{"title":"Demo","version":"1.0.0"}}`), nil
}),
info.WithLivenessChecks(probe.NewPingProbe("noop", func(ctx context.Context) error {
return nil
})),
info.WithReadinessChecks(probe.NewPingProbe("db", func(ctx context.Context) error {
return nil
})),
)
healthRec := httptest.NewRecorder()
handler.GetHealthz(healthRec, httptest.NewRequest(http.MethodGet, "/healthz", nil))
fmt.Println(healthRec.Code)
fmt.Println(strings.TrimSpace(healthRec.Body.String()))
versionRec := httptest.NewRecorder()
handler.GetVersion(versionRec, httptest.NewRequest(http.MethodGet, "/version", nil))
fmt.Println(versionRec.Code)
fmt.Println(strings.TrimSpace(versionRec.Body.String()))
}
Output: 200 {"status":"ok"} 200 {"version":"1.2.3"}
func NewInfoHandler ¶
func NewInfoHandler(opts ...InfoOption) *InfoHandler
NewInfoHandler constructs an InfoHandler with sensible defaults. Callers can supply InfoOption values to plug in domain specific providers or override the base responder implementation.
func (*InfoHandler) GetHealthz ¶
func (ih *InfoHandler) GetHealthz(w http.ResponseWriter, r *http.Request)
GetHealthz implements the liveness probe recommended for Kubernetes.
func (*InfoHandler) GetOpenAPIHTML ¶
func (ih *InfoHandler) GetOpenAPIHTML(w http.ResponseWriter, r *http.Request)
GetOpenAPIHTML renders an embedded Stoplight viewer that fetches the OpenAPI document from the JSON endpoint.
func (*InfoHandler) GetOpenAPIJSON ¶
func (ih *InfoHandler) GetOpenAPIJSON(w http.ResponseWriter, r *http.Request)
GetOpenAPIJSON streams the configured OpenAPI JSON document to the caller.
func (*InfoHandler) GetReadyz ¶
func (ih *InfoHandler) GetReadyz(w http.ResponseWriter, r *http.Request)
GetReadyz implements the readiness probe recommended for Kubernetes.
func (*InfoHandler) GetStatus ¶
func (ih *InfoHandler) GetStatus(w http.ResponseWriter, r *http.Request)
GetStatus returns a simple health payload that can be used for lightweight diagnostics.
func (*InfoHandler) GetVersion ¶
func (ih *InfoHandler) GetVersion(w http.ResponseWriter, r *http.Request)
GetVersion returns the structure provided by the configured InfoProvider.
type InfoOption ¶
type InfoOption func(*InfoHandler)
InfoOption follows the functional options pattern used by NewInfoHandler to configure optional collaborators such as the responder, base URL, and information providers.
func WithBaseURL ¶
func WithBaseURL(baseURL string) InfoOption
WithBaseURL sets the URL prefix that will be injected into the rendered documentation template.
func WithInfoProvider ¶
func WithInfoProvider(provider InfoProvider) InfoOption
WithInfoProvider swaps the default metadata provider with a user supplied implementation.
func WithInfoResponder ¶
func WithInfoResponder(responder *responder.Responder) InfoOption
WithInfoResponder replaces the responder used to craft JSON responses and handle error reporting.
func WithLivenessChecks ¶
func WithLivenessChecks(checks ...ProbeFunc) InfoOption
WithLivenessChecks replaces the default liveness checks with the supplied functions.
func WithOpenAPITemplate ¶
func WithOpenAPITemplate(tmpl *template.Template) InfoOption
WithOpenAPITemplate injects a custom html/template instance used to render the OpenAPI viewer page. Callers can parse templates from disk or embed them via go:embed before passing them in.
func WithOpenAPITemplateData ¶
func WithOpenAPITemplateData(provider TemplateDataProvider) InfoOption
WithOpenAPITemplateData overrides the template data provider that runs for each request to the HTML endpoint.
func WithProbeTimeout ¶
func WithProbeTimeout(timeout time.Duration) InfoOption
WithProbeTimeout adjusts the maximum duration allowed for probe checks.
func WithReadinessChecks ¶
func WithReadinessChecks(checks ...ProbeFunc) InfoOption
WithReadinessChecks replaces the default readiness checks with the supplied functions.
func WithSwaggerProvider ¶
func WithSwaggerProvider(provider SwaggerProvider) InfoOption
WithSwaggerProvider sets the source of the OpenAPI JSON document that backs the documentation endpoints.
type InfoProvider ¶
type InfoProvider func() any
InfoProvider returns the payload that will be exposed by the version endpoint. The provider allows callers to inject their own source for build metadata or runtime diagnostics.
type ProbeFunc ¶
ProbeFunc is executed to determine the outcome of liveness or readiness probes. Returning a non-nil error marks the probe as failed.
type SwaggerProvider ¶
SwaggerProvider returns the raw OpenAPI document that should be rendered by the documentation endpoints. It is commonly backed by an embedded JSON file generated at build time.
Source Files