@openstatus/health-s3 0.1.4-dev.0

package/README.md

@@ -0,0 +1,73 @@
+# @openstatus/health-s3
+
+S3 probe for [`@openstatus/health`](https://jsr.io/@openstatus/health).
+Sends [`HeadBucket`](https://docs.aws.amazon.com/AmazonS3/latest/API/API_HeadBucket.html)
+through an [`@aws-sdk/client-s3`](https://github.com/aws/aws-sdk-js-v3)
+client and fails the check when the bucket does not answer — on AWS S3,
+Cloudflare R2, Tigris, Backblaze B2, MinIO or any other S3-compatible store.
+
+```sh
+deno add jsr:@openstatus/health jsr:@openstatus/health-s3
+npm install @openstatus/health @openstatus/health-s3 @aws-sdk/client-s3
+```
+
+```ts
+import { S3Client } from "@aws-sdk/client-s3";
+import { createHealthHandler } from "@openstatus/health";
+import { s3Probe } from "@openstatus/health-s3";
+
+const client = new S3Client({ region: env.AWS_REGION });
+
+Deno.serve(
+  createHealthHandler({
+    probes: [s3Probe({ client, bucket: env.S3_BUCKET })],
+  }),
+);
+```
+
+`HeadBucket` is the cheapest request that proves the endpoint, the
+credentials and the bucket at once: it transfers no body, and a `403` or
+`404` — wrong credentials, wrong bucket, wrong region — fails the check
+just like a network error. The probe's `AbortSignal` is passed as
+`abortSignal`, so a `timeoutMs` cancels the request in flight.
+
+```ts
+s3Probe({
+  client,
+  bucket: "uploads",
+  // optional overrides from the Probe contract
+  name: "uploads",
+  critical: true,
+  timeoutMs: 2000,
+  skip: () => env.S3_BUCKET == null,
+});
+```
+
+Non-critical by default: object storage usually backs uploads and assets
+whose outage degrades the report instead of taking the service out of
+rotation. Set `critical: true` when requests cannot proceed without it.
+
+Unlike most probes here, this one imports `HeadBucketCommand` at runtime,
+so `@aws-sdk/client-s3` is a required peer dependency. The client itself is
+typed structurally as `{ send(command, options?) }`. The factory throws
+`ProbeConfigError` at construction when the client has no `send()` or
+`bucket` is empty. Inside a Cloudflare Worker, prefer
+`@openstatus/health-cloudflare-r2` and its binding over the S3 API.
+
+## About openstatus
+
+[openstatus](https://www.openstatus.dev/) is the open-source uptime monitoring
+and status page platform. This package is part of
+[`@openstatus/health`](https://github.com/openstatusHQ/health), the `/health`
+endpoints behind openstatus's own services, extracted so any JavaScript server
+can expose one. Point an
+[openstatus monitor](https://www.openstatus.dev/docs/reference/http-monitor)
+at the endpoint and assert on `status` in the body to be alerted on
+`degraded` before it becomes `unhealthy`.
+
+Source: [github.com/openstatusHQ/health](https://github.com/openstatusHQ/health).
+Issues and PRs welcome.
+
+## License
+
+[MIT](https://github.com/openstatusHQ/health/blob/main/LICENSE)

package/dist/_virtual/rolldown_runtime.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/mod.cjs

@@ -0,0 +1,33 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const __aws_sdk_client_s3 = require_rolldown_runtime.__toESM(require("@aws-sdk/client-s3"));
+const __openstatus_health = require_rolldown_runtime.__toESM(require("@openstatus/health"));
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const s3DefaultName = "storage";
+/** A probe that sends `HeadBucket`; non-critical by default. Throws `ProbeConfigError` without `send()` or with an empty `bucket`. */
+function s3Probe(options) {
+	const client = options.client;
+	if (typeof client?.send !== "function") throw new __openstatus_health.ProbeConfigError("s3Probe", "client", `must expose send(), got ${describe(client)}`);
+	const bucket = options.bucket;
+	if (typeof bucket !== "string" || bucket.length === 0) throw new __openstatus_health.ProbeConfigError("s3Probe", "bucket", typeof bucket !== "string" ? `must be a string, got ${String(bucket)}` : "must not be empty");
+	return {
+		name: options.name ?? s3DefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async (signal) => {
+			await client.send(new __aws_sdk_client_s3.HeadBucketCommand({ Bucket: bucket }), { abortSignal: signal });
+		}
+	};
+}
+function describe(client) {
+	if (client == null) return String(client);
+	if (typeof client !== "object") return typeof client;
+	const keys = Object.keys(client);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+exports.s3DefaultName = s3DefaultName;
+exports.s3Probe = s3Probe;

package/dist/mod.d.cts

@@ -0,0 +1,30 @@
+import { HeadBucketCommand } from "@aws-sdk/client-s3";
+import { Probe, ProbeOverrides, ProbeResult } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const s3DefaultName = "storage";
+/** What the probe passes to `send()` after the command. */
+interface S3SendOptions {
+  /** Aborts when the probe times out. */
+  readonly abortSignal?: AbortSignal;
+}
+/** The subset of an `S3Client` the probe uses. */
+interface S3LikeClient {
+  /** Send one command. */
+  send(command: HeadBucketCommand, options?: S3SendOptions): PromiseLike<ProbeResult>;
+}
+/** Options for `s3Probe()`. */
+interface S3ProbeOptions extends ProbeOverrides {
+  /** An `S3Client`. */
+  readonly client: S3LikeClient;
+  /** Bucket to `HeadBucket`. */
+  readonly bucket: string;
+}
+/** A probe that sends `HeadBucket`; non-critical by default. Throws `ProbeConfigError` without `send()` or with an empty `bucket`. */
+declare function s3Probe(options: S3ProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { S3LikeClient, S3ProbeOptions, S3SendOptions, s3DefaultName, s3Probe };
+//# sourceMappingURL=mod.d.cts.map

package/dist/mod.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.cts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;;AA0CsD,cAlBzC,aAAA,GAkByC,SAAA;AAQtD;AAAuB,UAvBN,aAAA,CAuBM;EAAA;EAAwB,SAAG,WAAA,CAAA,EArBzB,WAqByB;AAAK;;UAjBtC,YAAA;;gBAGJ,6BACC,gBACT,YAAY;;;UAIA,cAAA,SAAuB;;mBAErB;;;;;iBAMH,OAAA,UAAiB,iBAAiB"}

package/dist/mod.d.ts

@@ -0,0 +1,30 @@
+import { HeadBucketCommand } from "@aws-sdk/client-s3";
+import { Probe, ProbeOverrides, ProbeResult } from "@openstatus/health";
+
+//#region src/mod.d.ts
+
+/** Probe name when `name` is unset. */
+declare const s3DefaultName = "storage";
+/** What the probe passes to `send()` after the command. */
+interface S3SendOptions {
+  /** Aborts when the probe times out. */
+  readonly abortSignal?: AbortSignal;
+}
+/** The subset of an `S3Client` the probe uses. */
+interface S3LikeClient {
+  /** Send one command. */
+  send(command: HeadBucketCommand, options?: S3SendOptions): PromiseLike<ProbeResult>;
+}
+/** Options for `s3Probe()`. */
+interface S3ProbeOptions extends ProbeOverrides {
+  /** An `S3Client`. */
+  readonly client: S3LikeClient;
+  /** Bucket to `HeadBucket`. */
+  readonly bucket: string;
+}
+/** A probe that sends `HeadBucket`; non-critical by default. Throws `ProbeConfigError` without `send()` or with an empty `bucket`. */
+declare function s3Probe(options: S3ProbeOptions): Probe;
+//# sourceMappingURL=mod.d.ts.map
+//#endregion
+export { S3LikeClient, S3ProbeOptions, S3SendOptions, s3DefaultName, s3Probe };
+//# sourceMappingURL=mod.d.ts.map

package/dist/mod.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.d.ts","names":[],"sources":["../src/mod.ts"],"sourcesContent":[],"mappings":";;;;;;AA0CsD,cAlBzC,aAAA,GAkByC,SAAA;AAQtD;AAAuB,UAvBN,aAAA,CAuBM;EAAA;EAAwB,SAAG,WAAA,CAAA,EArBzB,WAqByB;AAAK;;UAjBtC,YAAA;;gBAGJ,6BACC,gBACT,YAAY;;;UAIA,cAAA,SAAuB;;mBAErB;;;;;iBAMH,OAAA,UAAiB,iBAAiB"}

package/dist/mod.js

@@ -0,0 +1,32 @@
+import { HeadBucketCommand } from "@aws-sdk/client-s3";
+import { ProbeConfigError } from "@openstatus/health";
+
+//#region src/mod.ts
+/** Probe name when `name` is unset. */
+const s3DefaultName = "storage";
+/** A probe that sends `HeadBucket`; non-critical by default. Throws `ProbeConfigError` without `send()` or with an empty `bucket`. */
+function s3Probe(options) {
+	const client = options.client;
+	if (typeof client?.send !== "function") throw new ProbeConfigError("s3Probe", "client", `must expose send(), got ${describe(client)}`);
+	const bucket = options.bucket;
+	if (typeof bucket !== "string" || bucket.length === 0) throw new ProbeConfigError("s3Probe", "bucket", typeof bucket !== "string" ? `must be a string, got ${String(bucket)}` : "must not be empty");
+	return {
+		name: options.name ?? s3DefaultName,
+		critical: options.critical ?? false,
+		timeoutMs: options.timeoutMs,
+		skip: options.skip,
+		run: async (signal) => {
+			await client.send(new HeadBucketCommand({ Bucket: bucket }), { abortSignal: signal });
+		}
+	};
+}
+function describe(client) {
+	if (client == null) return String(client);
+	if (typeof client !== "object") return typeof client;
+	const keys = Object.keys(client);
+	return keys.length === 0 ? "an object with no keys" : `an object with keys ${keys.slice(0, 8).join(", ")}`;
+}
+
+//#endregion
+export { s3DefaultName, s3Probe };
+//# sourceMappingURL=mod.js.map

package/dist/mod.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mod.js","names":["options: S3ProbeOptions","client: S3LikeClient"],"sources":["../src/mod.ts"],"sourcesContent":["/**\n * S3 probe for `@openstatus/health`: sends `HeadBucket` through an\n * `@aws-sdk/client-s3` client, so it covers AWS S3, Cloudflare R2, Tigris,\n * MinIO and every other S3-compatible store.\n *\n * ```ts\n * import { S3Client } from \"@aws-sdk/client-s3\";\n * import { s3Probe } from \"@openstatus/health-s3\";\n *\n * const probe = s3Probe({ client: new S3Client({}), bucket: \"uploads\" });\n * ```\n *\n * @module\n */\n\nimport { HeadBucketCommand } from \"@aws-sdk/client-s3\";\nimport {\n  type Probe,\n  ProbeConfigError,\n  type ProbeOverrides,\n  type ProbeResult,\n} from \"@openstatus/health\";\n\n/** Probe name when `name` is unset. */\nexport const s3DefaultName = \"storage\";\n\n/** What the probe passes to `send()` after the command. */\nexport interface S3SendOptions {\n  /** Aborts when the probe times out. */\n  readonly abortSignal?: AbortSignal;\n}\n\n/** The subset of an `S3Client` the probe uses. */\nexport interface S3LikeClient {\n  /** Send one command. */\n  send(\n    command: HeadBucketCommand,\n    options?: S3SendOptions,\n  ): PromiseLike<ProbeResult>;\n}\n\n/** Options for `s3Probe()`. */\nexport interface S3ProbeOptions extends ProbeOverrides {\n  /** An `S3Client`. */\n  readonly client: S3LikeClient;\n  /** Bucket to `HeadBucket`. */\n  readonly bucket: string;\n}\n\n/** A probe that sends `HeadBucket`; non-critical by default. Throws `ProbeConfigError` without `send()` or with an empty `bucket`. */\nexport function s3Probe(options: S3ProbeOptions): Probe {\n  const client = options.client;\n  if (typeof client?.send !== \"function\") {\n    throw new ProbeConfigError(\n      \"s3Probe\",\n      \"client\",\n      `must expose send(), got ${describe(client)}`,\n    );\n  }\n  const bucket = options.bucket;\n  if (typeof bucket !== \"string\" || bucket.length === 0) {\n    throw new ProbeConfigError(\n      \"s3Probe\",\n      \"bucket\",\n      typeof bucket !== \"string\"\n        ? `must be a string, got ${String(bucket)}`\n        : \"must not be empty\",\n    );\n  }\n  return {\n    name: options.name ?? s3DefaultName,\n    critical: options.critical ?? false,\n    timeoutMs: options.timeoutMs,\n    skip: options.skip,\n    run: async (signal) => {\n      await client.send(new HeadBucketCommand({ Bucket: bucket }), {\n        abortSignal: signal,\n      });\n    },\n  };\n}\n\nfunction describe(client: S3LikeClient): string {\n  if (client == null) return String(client);\n  if (typeof client !== \"object\") return typeof client;\n  const keys = Object.keys(client);\n  return keys.length === 0\n    ? \"an object with no keys\"\n    : `an object with keys ${keys.slice(0, 8).join(\", \")}`;\n}\n"],"mappings":";;;;;AAwBA,MAAa,gBAAgB;;AA0B7B,SAAgB,QAAQA,SAAgC;CACtD,MAAM,SAAS,QAAQ;AACvB,YAAW,QAAQ,SAAS,WAC1B,OAAM,IAAI,iBACR,WACA,WACC,0BAA0B,SAAS,OAAO,CAAC;CAGhD,MAAM,SAAS,QAAQ;AACvB,YAAW,WAAW,YAAY,OAAO,WAAW,EAClD,OAAM,IAAI,iBACR,WACA,iBACO,WAAW,YACb,wBAAwB,OAAO,OAAO,CAAC,IACxC;AAGR,QAAO;EACL,MAAM,QAAQ,QAAQ;EACtB,UAAU,QAAQ,YAAY;EAC9B,WAAW,QAAQ;EACnB,MAAM,QAAQ;EACd,KAAK,OAAO,WAAW;AACrB,SAAM,OAAO,KAAK,IAAI,kBAAkB,EAAE,QAAQ,OAAQ,IAAG,EAC3D,aAAa,OACd,EAAC;EACH;CACF;AACF;AAED,SAAS,SAASC,QAA8B;AAC9C,KAAI,UAAU,KAAM,QAAO,OAAO,OAAO;AACzC,YAAW,WAAW,SAAU,eAAc;CAC9C,MAAM,OAAO,OAAO,KAAK,OAAO;AAChC,QAAO,KAAK,WAAW,IACnB,4BACC,sBAAsB,KAAK,MAAM,GAAG,EAAE,CAAC,KAAK,KAAK,CAAC;AACxD"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@openstatus/health-s3",
+  "version": "0.1.4-dev.0",
+  "description": "S3 HeadBucket probe for @openstatus/health",
+  "keywords": [
+    "openstatus",
+    "health",
+    "healthcheck",
+    "s3",
+    "aws",
+    "r2",
+    "minio",
+    "tigris",
+    "storage"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "openstatus",
+    "url": "https://www.openstatus.dev/"
+  },
+  "homepage": "https://github.com/openstatusHQ/health",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/openstatusHQ/health.git",
+    "directory": "packages/s3/"
+  },
+  "bugs": {
+    "url": "https://github.com/openstatusHQ/health/issues"
+  },
+  "type": "module",
+  "module": "./dist/mod.js",
+  "main": "./dist/mod.cjs",
+  "types": "./dist/mod.d.ts",
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/mod.d.ts",
+        "require": "./dist/mod.d.cts"
+      },
+      "import": "./dist/mod.js",
+      "require": "./dist/mod.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist/"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "peerDependencies": {
+    "@openstatus/health": "^0.1.4-dev.0",
+    "@aws-sdk/client-s3": ">=3.0.0"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.850.0",
+    "tsdown": "^0.12.7",
+    "typescript": "^5.8.3"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepack": "tsdown",
+    "test": "node --experimental-transform-types --test"
+  }
+}