node: configure publish

go-health/liveness.go

@@ -1,42 +0,0 @@
-package health
-
-import (
-	"encoding/json"
-	"net/http"
-	"time"
-)
-
-// Status of the service liveness.
-type LivenessStatus string
-
-const (
-	// Service is alive and functioning properly.
-	LivenessStatusAlive LivenessStatus = "ok"
-)
-
-// Result of a liveness check.
-type LivenessResult struct {
-	// Status of the service (always LivenessStatusAlive)
-	Status LivenessStatus
-	// Timestamp of the liveness check in milliseconds since Unix epoch
-	Timestamp int64
-}
-
-// Checks if the service is alive.
-func Liveness() LivenessResult {
-	return LivenessResult{
-		Status:    LivenessStatusAlive,
-		Timestamp: time.Now().UnixMilli(),
-	}
-}
-
-// Handler for liveness HTTP requests.
-// Returns a response with status 200 and a JSON body matching LivenessResult.
-func LivenessHandler() http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		result := Liveness()
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusOK)
-		json.NewEncoder(w).Encode(result)
-	}
-}

go-health/readiness.go

@@ -1,221 +0,0 @@
-package health
-
-import (
-	"encoding/json"
-	"net/http"
-	"slices"
-	"time"
-)
-
-// Status of the service readiness.
-type ReadinessStatus string
-
-// String returns the string representation of the readiness status.
-func (s ReadinessStatus) String() string {
-	return string(s)
-}
-
-// HTTPStatus returns the corresponding HTTP status code for the readiness status.
-func (s ReadinessStatus) HTTPStatus() int {
-	switch s {
-	case ReadinessStatusReady:
-		return http.StatusOK
-	case ReadinessStatusDegraded:
-		return http.StatusOK // 206 could also be suitable, but let's avoid false alarms
-	case ReadinessStatusFatal:
-		return http.StatusServiceUnavailable
-	case ReadinessStatusNotReady:
-		return http.StatusOK // treat as ok to avoid false alarms
-	default:
-		return http.StatusOK
-	}
-}
-
-const (
-	// Service is ready to handle requests.
-	ReadinessStatusReady ReadinessStatus = "ready"
-	// Service is not ready to handle requests.
-	ReadinessStatusNotReady ReadinessStatus = "not_ready"
-	// Service experienced a fatal error and cannot handle requests.
-	ReadinessStatusFatal ReadinessStatus = "fatal"
-	// Service is degraded but can still handle requests.
-	ReadinessStatusDegraded ReadinessStatus = "degraded"
-)
-
-// Returns the worst readiness status from a list of statuses.
-func worstStatus(statuses []ReadinessStatus) ReadinessStatus {
-	if slices.Contains(statuses, ReadinessStatusFatal) {
-		return ReadinessStatusFatal
-	}
-	if slices.Contains(statuses, ReadinessStatusNotReady) {
-		return ReadinessStatusNotReady
-	}
-	if slices.Contains(statuses, ReadinessStatusDegraded) {
-		return ReadinessStatusDegraded
-	}
-	return ReadinessStatusReady
-}
-
-// Readiness check function return type.
-type ReadinessReturn struct {
-	// Status of the readiness check.
-	Status ReadinessStatus
-	// Optional message providing additional information about the readiness status.
-	Message *string
-}
-
-// Function that performs a readiness check.
-type ReadinessCheckFn func() ReadinessReturn
-
-// Individual readiness check.
-type ReadinessCheck struct {
-	// Name of the readiness check.
-	Name string
-	// Function that performs the readiness check.
-	Fn ReadinessCheckFn
-	// Timeout for the readiness check (default: 5 seconds)
-	Timeout time.Duration
-}
-
-// System-generated result from an individual readiness check.
-type ReadinessCheckResult struct {
-	// Name of the readiness check.
-	Name string
-	// Status of the readiness check.
-	Status ReadinessStatus
-	// Optional message providing additional information about the readiness status.
-	Message *string
-	// Duration of the readiness check in milliseconds.
-	Duration int64
-}
-
-// System readiness status.
-type Readiness struct {
-	// Status of the service readiness. Aggregated as the worst status from
-	// all individual readiness checks. If no checks have been performed
-	// yet, the status is ReadinessStatusNotReady.
-	Status ReadinessStatus
-	// Start time of the readiness check in milliseconds since Unix epoch.
-	Start int64
-	// Duration of the readiness check in milliseconds.
-	Duration int64
-	// Individual readiness check results.
-	Details map[string]ReadinessCheckResult
-}
-
-// Performs a full system readiness check given a list of individual checks.
-func CheckReadiness(checks []ReadinessCheck) Readiness {
-	start := time.Now()
-	details := make(map[string]ReadinessCheckResult)
-	var statuses []ReadinessStatus
-
-	for _, check := range checks {
-		checkt0 := time.Now()
-		result := checkWithTimeout(check)
-		duration := time.Since(checkt0).Milliseconds()
-
-		details[check.Name] = ReadinessCheckResult{
-			Name:     check.Name,
-			Status:   result.Status,
-			Message:  result.Message,
-			Duration: duration,
-		}
-		statuses = append(statuses, result.Status)
-	}
-
-	return Readiness{
-		Status:   worstStatus(statuses),
-		Start:    start.UnixMilli(),
-		Duration: time.Since(start).Milliseconds(),
-		Details:  details,
-	}
-}
-
-// Creates a handler function for readiness HTTP requests.
-func ReadinessHandler(checks []ReadinessCheck) http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		respondWithResult(w, CheckReadiness(checks))
-	}
-}
-
-// Runs a readiness check with a timeout.
-func checkWithTimeout(check ReadinessCheck) ReadinessReturn {
-	timeout := check.Timeout
-	if timeout == 0 {
-		timeout = 5 * time.Second
-	}
-
-	resultCh := make(chan ReadinessReturn, 1)
-
-	go func() {
-		resultCh <- check.Fn()
-	}()
-
-	select {
-	case result := <-resultCh:
-		return result
-	case <-time.After(timeout):
-		msg := "readiness check timed out"
-		return ReadinessReturn{
-			Status:  ReadinessStatusFatal,
-			Message: &msg,
-		}
-	}
-}
-
-func respondWithResult(w http.ResponseWriter, result Readiness) {
-	w.Header().Set("Content-Type", "application/json")
-	w.WriteHeader(result.Status.HTTPStatus())
-	json.NewEncoder(w).Encode(result)
-}
-
-// ScheduledReadiness performs periodic readiness checks and stores the latest result.
-type ScheduledReadiness struct {
-	checks       []ReadinessCheck
-	interval     time.Duration
-	currentState Readiness
-	ticker       *time.Ticker
-	quit         chan struct{}
-}
-
-// NewScheduledReadiness creates a new ScheduledReadiness instance.
-func NewScheduledReadiness(checks []ReadinessCheck, interval time.Duration) *ScheduledReadiness {
-	return &ScheduledReadiness{
-		checks:   checks,
-		interval: interval,
-		quit:     make(chan struct{}),
-	}
-}
-
-// Start begins the periodic readiness checks.
-func (sr *ScheduledReadiness) Start() {
-	sr.ticker = time.NewTicker(sr.interval)
-	go func() {
-		for {
-			select {
-			case <-sr.ticker.C:
-				sr.currentState = CheckReadiness(sr.checks)
-			case <-sr.quit:
-				sr.ticker.Stop()
-				return
-			}
-		}
-	}()
-}
-
-// Stop halts the periodic readiness checks.
-func (sr *ScheduledReadiness) Stop() {
-	close(sr.quit)
-}
-
-// GetCurrentState returns the latest readiness state.
-func (sr *ScheduledReadiness) GetCurrentState() Readiness {
-	return sr.currentState
-}
-
-// Creates a handler function for scheduled readiness HTTP requests.
-func (sr *ScheduledReadiness) ReadinessHandler() http.HandlerFunc {
-	return func(w http.ResponseWriter, r *http.Request) {
-		respondWithResult(w, sr.GetCurrentState())
-	}
-}

node-health/package.json

@@ -1,5 +1,5 @@
 {
-	"name": "@end/node-health",
+	"name": "@health/node",
 	"repository": {
 		"type": "git",
 		"url": "https://gitea.auvem.com/end/health.git"
@@ -7,7 +7,7 @@
 	"publishConfig": {
 		"registry": "https://gitea.auvem.com/api/packages/end/npm/"
 	},
-	"version": "0.1.2",
+	"version": "0.1.0",
 	"license": "MIT",
 	"main": "dist/index.js",
 	"types": "dist/index.d.ts",

node-health/src/index.ts

@@ -1,3 +1,2 @@
 export * from './liveness';
 export * from './readiness';
-export * from './checks';

node-health/src/readiness.ts

@@ -1,5 +1,5 @@
-/** Readiness check function return type */
+/** Return type of a readiness check function */
-export type ReadinessReturn = {
+export type ReadinessFunctionReturn = {
 	/** Status of the readiness check */
 	status: ReadinessStatus;
 	/** Optional message providing additional information about the readiness check */
@@ -7,47 +7,45 @@ export type ReadinessReturn = {
 };
 
 /** Function that performs a readiness check */
-export type ReadinessCheckFn = (check: ReadinessCheck) => Promise<ReadinessReturn>;
+export type ReadinessFunction = (check: ReadinessCheck) => Promise<ReadinessFunctionReturn>;
 
-/** Status of the service readiness */
+/** Status of a readiness check */
-export type ReadinessStatus = 'fatal' | 'not_ready' | 'degraded' | 'ready';
+export type ReadinessStatus = 'ok' | 'error' | 'degraded';
 
-/** Returns the worst readiness status from a list of statuses. */
+const aggregateStatus = (statuses: ReadinessStatus[]): ReadinessStatus => {
-const worstStatus = (statuses: ReadinessStatus[]): ReadinessStatus => {
+	if (statuses.includes('error')) return 'error';
-	if (statuses.includes('fatal')) return 'fatal';
-	if (statuses.includes('not_ready')) return 'not_ready';
 	if (statuses.includes('degraded')) return 'degraded';
-	return 'ready';
+	return 'ok';
 };
 
-/** Individual readiness check */
+/** Represents a readiness check with an optional timeout */
 export type ReadinessCheck = {
 	/** Name of the readiness check */
 	name: string;
 	/** Function that performs the readiness check */
-	fn: ReadinessCheckFn;
+	fn: ReadinessFunction;
 	/** Timeout in milliseconds for the readiness check (default: 5000) */
 	timeout?: number;
 };
 
-/** System readiness status */
+/** Result of a system readiness check */
-export type Readiness = {
+export type ReadinessResult = {
 	/**
 	 * Status of the system readiness check, aggregated as the worst status
-	 * among individual checks. If no checks have been performed yet, the status
+	 * among individual checks. 'unknown' is a special case indicating that
-	 * is 'not_ready'.
+	 * no checks were performed, used by ScheduledReadiness before the first run.
-	 */
+	 * */
-	status: ReadinessStatus;
+	status: ReadinessStatus | 'unknown';
 	/** Start time of the system readiness check in milliseconds since the Unix epoch */
 	start: number;
 	/** Duration of the system readiness check in milliseconds */
 	duration: number;
 	/** Details of individual readiness checks */
-	details: ReadinessCheckResult[];
+	details: ReadinessDetail[];
 };
 
-/** System-generated result from an individual readiness check */
+/** Detail of an individual readiness check */
-export type ReadinessCheckResult = {
+export type ReadinessDetail = {
 	/** Name of the readiness check */
 	name: string;
 	/** Status of the readiness check */
@@ -61,12 +59,12 @@ export type ReadinessCheckResult = {
 /**
  * Performs a readiness check by executing the provided readiness functions.
  * @param checks - An array of readiness functions to execute.
- * @returns A Promise that resolves to a Readiness object.
+ * @returns A Promise that resolves to a ReadinessResult object.
  */
-export const readiness = async (checks: ReadinessCheck[]): Promise<Readiness> => {
+export const readiness = async (checks: ReadinessCheck[]): Promise<ReadinessResult> => {
 	const start = Date.now();
 	const t0 = performance.now();
-	const details: ReadinessCheckResult[] = [];
+	const details: ReadinessDetail[] = [];
 
 	for (const check of checks) {
 		const checkt0 = performance.now();
@@ -85,7 +83,7 @@ export const readiness = async (checks: ReadinessCheck[]): Promise<Readiness> =>
 		} catch (err) {
 			details.push({
 				name: check.name,
-				status: 'fatal',
+				status: 'error',
 				message: err instanceof Error ? err.message : String(err),
 				duration: performance.now() - checkt0,
 			});
@@ -95,7 +93,7 @@ export const readiness = async (checks: ReadinessCheck[]): Promise<Readiness> =>
 	const duration = performance.now() - t0;
 
 	return {
-		status: worstStatus(details.map((d) => d.status)),
+		status: aggregateStatus(details.map((d) => d.status)),
 		start,
 		duration,
 		details,
@@ -106,7 +104,7 @@ export const readiness = async (checks: ReadinessCheck[]): Promise<Readiness> =>
  * Creates a handler function for readiness HTTP requests. Warning: this runs all
  * checks on each request and may be slow.
  * @param checks - An array of readiness functions to execute.
- * @returns A function that returns a Response object with Readiness in JSON format.
+ * @returns A function that returns a Response object with ReadinessResult in JSON format.
  */
 export const createReadinessHandler = (checks: ReadinessCheck[]): (() => Promise<Response>) => {
 	return async () => {
@@ -123,8 +121,8 @@ export class ScheduledReadiness {
 	private interval: number;
 	private started: boolean = false;
 	private timer: NodeJS.Timeout | null = null;
-	private latestResult: Readiness | null = null;
+	private latestResult: ReadinessResult | null = null;
-	private nextResult: Promise<Readiness> | null = null;
+	private nextResult: Promise<ReadinessResult> | null = null;
 
 	/**
 	 * Creates an instance of ScheduledReadiness.
@@ -167,7 +165,7 @@ export class ScheduledReadiness {
 	}
 
 	/** Gets the next readiness result, waiting if a check is in progress */
-	async getNextResult(): Promise<Readiness | null> {
+	async getNextResult(): Promise<ReadinessResult | null> {
 		if (this.nextResult) {
 			return await this.nextResult;
 		}
@@ -175,7 +173,7 @@ export class ScheduledReadiness {
 	}
 
 	/** Gets the latest readiness result without waiting */
-	getResult(): Readiness | null {
+	getResult(): ReadinessResult | null {
 		return this.latestResult;
 	}
 
@@ -194,21 +192,21 @@ export class ScheduledReadiness {
 	/**
 	 * Creates a handler function for readiness HTTP requests using the latest scheduled result.
 	 * Scheduled handler always returns the most recent result, or 'unknown' if no checks have run yet.
-	 * @returns A function that returns a Response object with Readiness in JSON format.
+	 * @returns A function that returns a Response object with ReadinessResult in JSON format.
 	 */
 	createHandler(): () => Promise<Response> {
 		return async () => {
-			const result = this.getResult();
+			const result = await this.getNextResult();
 			if (!result) {
 				return new Response(
 					JSON.stringify({
-						status: 'not_ready',
+						status: 'unknown',
 						start: Date.now(),
 						duration: 0,
 						details: [],
-					} as Readiness),
+					} as ReadinessResult),
 					{
-						status: httpStatusFromReadiness('not_ready'),
+						status: httpStatusFromReadiness('unknown'),
 						headers: { 'Content-Type': 'application/json' },
 					},
 				);
@@ -219,8 +217,8 @@ export class ScheduledReadiness {
 	}
 }
 
-/** Returns a Response object with the given Readiness in JSON format */
+/** Returns a Response object with the given ReadinessResult in JSON format */
-const respondWithResult = (result: Readiness) => {
+const respondWithResult = (result: ReadinessResult) => {
 	return new Response(JSON.stringify(result), {
 		status: httpStatusFromReadiness(result.status),
 		headers: { 'Content-Type': 'application/json' },
@@ -228,11 +226,11 @@ const respondWithResult = (result: Readiness) => {
 };
 
 /** Returns the HTTP status code corresponding to a given readiness status */
-const httpStatusFromReadiness = (status: ReadinessStatus): number => {
+const httpStatusFromReadiness = (status: ReadinessStatus | 'unknown'): number => {
-	if (status === 'ready') return 200;
+	if (status === 'ok') return 200;
 	if (status === 'degraded') return 200; // 206 could also be suitable, but let's avoid false alarms
-	if (status === 'fatal') return 503;
+	if (status === 'error') return 503;
-	return 200; // not_ready, treat as ok to avoid false alarms
+	return 200; // unknown, treat as ok to avoid false alarms
 };
 
 const withTimeout = async <T>(