Open-source status page, incident response and uptime monitoring
TypeScript alertingincident-managementmcpmcp-servermonitoringmonitoring-as-codeobservabilityon-callopen-sourcesrestatus-pagestatuspagesynthetic-monitoringterraformtinybirdtursouptimeuptime-checkeruptime-monitor
import { monitorRegionSchema } from "@openstatus/db/src/schema/constants";
import type { Region } from "@openstatus/db/src/schema/constants";
import { continentDict, getRegionInfo, regionDict } from "@openstatus/regions";
import { Redis } from "@upstash/redis";
import { z } from "zod";
// ============================================================================
// Constants
// ============================================================================
const FLY_CHECKER_URL = "https://checker.openstatus.dev/ping";
const KOYEB_CHECKER_URL = "https://openstatus-checker.koyeb.app/ping";
const RAILWAY_CHECKER_URL =
"https://railway-proxy-production-9cb1.up.railway.app/ping";
// ============================================================================
// Formatters
// ============================================================================
export function latencyFormatter(value: number) {
return `${new Intl.NumberFormat("en-US").format(value).toString()}ms`;
}
export function timestampFormatter(timestamp: number) {
return new Date(timestamp).toUTCString(); // GMT format
}
export function continentFormatter(region: Region) {
const continent = regionDict[region].continent;
return continentDict[continent].code;
}
export function regionFormatter(
region: string,
type: "short" | "long" = "short",
) {
const { code, flag, location } = getRegionInfo(region);
if (type === "short") return `${code} ${flag}`;
return `${location} ${flag}`;
}
// ============================================================================
// Timing Utilities
// ============================================================================
export function getTotalLatency(timing: Timing) {
const { dns, connection, tls, ttfb, transfer } = getTimingPhases(timing);
return dns + connection + tls + ttfb + transfer;
}
export function getTimingPhases(timing: Timing) {
const dns = timing.dnsDone - timing.dnsStart;
const connection = timing.connectDone - timing.connectStart;
const tls = timing.tlsHandshakeDone - timing.tlsHandshakeStart;
const ttfb = timing.firstByteDone - timing.firstByteStart;
const transfer = timing.transferDone - timing.transferStart;
return {
dns,
connection,
tls,
ttfb,
transfer,
};
}
export function getTimingPhasesWidth(timing: Timing) {
const total = getTotalLatency(timing);
const phases = getTimingPhases(timing);
const dns = { preWidth: 0, width: (phases.dns / total) * 100 };
const connection = {
preWidth: dns.preWidth + dns.width,
width: (phases.connection / total) * 100,
};
const tls = {
preWidth: connection.preWidth + connection.width,
width: (phases.tls / total) * 100,
};
const ttfb = {
preWidth: tls.preWidth + tls.width,
width: (phases.ttfb / total) * 100,
};
const transfer = {
preWidth: ttfb.preWidth + ttfb.width,
width: (phases.transfer / total) * 100,
};
return {
dns,
connection,
tls,
ttfb,
transfer,
};
}
// ============================================================================
// Schemas & Types
// ============================================================================
export const timingSchema = z.object({
dnsStart: z.number(),
dnsDone: z.number(),
connectStart: z.number(),
connectDone: z.number(),
tlsHandshakeStart: z.number(),
tlsHandshakeDone: z.number(),
firstByteStart: z.number(),
firstByteDone: z.number(),
transferStart: z.number(),
transferDone: z.number(),
});
export const checkerSchema = z.object({
type: z.literal("http").prefault("http"),
state: z.literal("success").prefault("success"),
status: z.number(),
latency: z.number(),
headers: z.record(z.string(), z.string()),
timestamp: z.number(),
timing: timingSchema,
body: z.string().optional().nullable(),
});
export const cachedCheckerSchema = z.object({
url: z.string(),
timestamp: z.number(),
method: z.string(), // Simplified - validation happens at runtime
headers: z.array(z.object({ key: z.string(), value: z.string() })).optional(),
body: z.string().optional(),
checks: checkerSchema.extend({ region: monitorRegionSchema }).array(),
});
const errorRequest = z.object({
message: z.string(),
state: z.literal("error").prefault("error"),
});
export const regionCheckerSchema = checkerSchema.extend({
region: monitorRegionSchema,
state: z.literal("success").prefault("success"),
});
export const regionCheckerSchemaResponse = regionCheckerSchema.or(
errorRequest.extend({
region: monitorRegionSchema,
}),
);
export type Timing = z.infer<typeof timingSchema>;
export type Checker = z.infer<typeof checkerSchema>;
export type RegionChecker = z.infer<typeof regionCheckerSchema>;
export type RegionCheckerResponse = z.infer<typeof regionCheckerSchemaResponse>;
export type Method =
| "GET"
| "HEAD"
| "OPTIONS"
| "POST"
| "PUT"
| "DELETE"
| "PATCH"
| "CONNECT"
| "TRACE";
export type CachedRegionChecker = z.infer<typeof cachedCheckerSchema>;
export type ErrorRequest = z.infer<typeof errorRequest>;
type CheckRegionRequest = {
url: string;
region: Region;
method?: Method;
headers?: { value: string; key: string }[];
body?: string;
signal?: AbortSignal;
};
// ============================================================================
// API Functions
// ============================================================================
// A timeout / unreachable target is an expected outcome, not a bug. Callers
// throw this so a route catch can return 400 while keeping it out of Sentry.
export class TargetUnreachableError extends Error {}
// Bound the upstream checker request below the client's 10s abort so a stalled
// checker can't keep the route running to the platform limit.
export const CHECKER_REQUEST_TIMEOUT_MS = 9_000;
export function isTimeoutError(e: unknown): boolean {
return e instanceof Error && e.name === "TimeoutError";
}
export async function checkRegion(
props: CheckRegionRequest,
): Promise<RegionCheckerResponse> {
const { url, region, method, headers, body, signal } = props;
const regionInfo = regionDict[region];
let endpoint = "";
let regionHeader = {};
switch (regionInfo.provider) {
case "fly":
endpoint = `${FLY_CHECKER_URL}/${region}`;
regionHeader = { "fly-prefer-region": region };
break;
case "koyeb":
endpoint = `${KOYEB_CHECKER_URL}/${region}`;
regionHeader = {
"X-KOYEB-REGION-OVERRIDE": region.replace("koyeb_", ""),
};
break;
case "railway":
endpoint = `${RAILWAY_CHECKER_URL}/${region}`;
regionHeader = { "railway-region": region.replace("railway_", "") };
break;
default:
break;
}
// A caller-supplied signal is the caller's to interpret (it inspects the raw
// TimeoutError); only our own default bound maps to TargetUnreachableError.
const usingDefaultTimeout = !signal;
let res: Response;
try {
res = await fetch(endpoint, {
headers: {
Authorization: `Basic ${process.env.CRON_SECRET}`,
"Content-Type": "application/json",
...regionHeader,
},
method: "POST",
body: JSON.stringify({
url,
method: method || "GET",
headers: headers?.reduce(
(acc, { key, value }) => {
if (!key) return acc; // key === "" is an invalid header
return { ...acc, [key]: value };
},
{} as Record<string, string>,
),
body: body ? body : undefined,
}),
next: { revalidate: 0 },
signal: signal ?? AbortSignal.timeout(CHECKER_REQUEST_TIMEOUT_MS),
});
} catch (e) {
if (usingDefaultTimeout && isTimeoutError(e)) {
throw new TargetUnreachableError("checker request timed out");
}
throw e;
}
const json = await res.json();
const data = checkerSchema.or(errorRequest).safeParse(json);
if (!data.success) {
// Neither the success nor the error shape matched — likely checker schema
// drift rather than an unreachable target. Warn (not error) so it stays
// observable in production without paging Sentry.
console.warn("Unexpected checker response shape:", json);
throw new TargetUnreachableError(data.error.message);
}
return {
region,
...data.data,
};
}
// ============================================================================
// Redis Caching
// ============================================================================
export async function storeBaseCheckerData({
url,
method,
id,
}: {
url: string;
method: Method;
id: string;
}) {
const redis = Redis.fromEnv();
const timestamp = new Date().getTime();
const cache = { url, method, timestamp };
const parsed = cachedCheckerSchema
.pick({ url: true, method: true, timestamp: true })
.safeParse(cache);
if (!parsed.success) {
throw new Error(parsed.error.message);
}
await redis.hset(`check:base:${id}`, parsed.data);
const expire = 60 * 60 * 24 * 7; // 7days
await redis.expire(`check:base:${id}`, expire);
}
export async function storeCheckerData({
check,
id,
}: {
check: RegionChecker;
id: string;
}) {
const parsed = cachedCheckerSchema
.pick({ checks: true })
.safeParse({ checks: [check] });
if (!parsed.success) {
throw new Error(parsed.error.message);
}
const first = parsed.data.checks?.[0];
const redis = Redis.fromEnv();
if (first) await redis.sadd(`check:data:${id}`, first);
return id;
}
export async function getCheckerDataById(id: string) {
const redis = Redis.fromEnv();
const pipe = redis.pipeline();
pipe.hgetall(`check:base:${id}`);
pipe.smembers(`check:data:${id}`);
const res =
await pipe.exec<
[{ url: string; method: Method; time: number }, RegionChecker]
>();
if (!res) {
return null;
}
const parsed = cachedCheckerSchema.safeParse({ ...res[0], checks: res[1] });
if (!parsed.success) {
// throw new Error(parsed.error.message);
return null;
}
return parsed.data;
}
// ============================================================================
// Validation Utilities
// ============================================================================
/**
* Simple function to validate crypto.randomUUID() format like "aec4e0ec3c4f4557b8ce46e55078fc95"
* @param uuid
* @returns
*/
export function is32CharHex(uuid: string) {
const hexRegex = /^[0-9a-fA-F]{32}$/;
return hexRegex.test(uuid);
}