@adalo/metrics 0.0.0-staging.1

package/.env.example

@@ -0,0 +1,14 @@
+BUILD_APP_NAME="staging"
+HOSTNAME="staging-queue-metricus"
+BUILD_DYNO_PROCESS_TYPE="web"
+METRICS_ENABLED=true
+# Set to true to collect app_requests_total and app_requests_total_duration (default: false)
+# METRICS_HTTP_ENABLED=false
+METRICS_LOG_VALUES=true
+METRICS_PUSHGATEWAY_URL=https://vm-agent.infradalogs.adalo.com
+METRICS_PUSHGATEWAY_SECRET="METRICS_PUSHGATEWAY_SECRET"
+METRICS_INTERVAL_SEC=60
+# METRICS_REMOVE_OLD_METRICS=false  (set true to delete this instance's metrics from VM on exit)
+
+
+

package/.eslintignore

@@ -0,0 +1,3 @@
+lib/
+node_modules/
+babel.config.js

package/.eslintrc

@@ -0,0 +1,61 @@
+{
+  "extends": [
+    "airbnb-base",
+    "airbnb-typescript/base",
+    "prettier" // Prettier must always be last as it overrides all other configs (https://github.com/prettier/eslint-config-prettier)
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "project": "./tsconfig.json"
+  },
+  "plugins": ["@typescript-eslint"],
+  "env": {
+    "browser": true,
+    "commonjs": true,
+    "es6": true,
+    "node": true
+  },
+  "settings": {
+    "import/resolver": {
+      "typescript": {} // this loads <rootdir>/tsconfig.json
+    }
+  },
+  "overrides": [
+    {
+      "files": ["**/*.test.js"],
+      "env": {
+        "jest": true
+      }
+    }
+  ],
+  "rules": {
+    "curly": ["error", "multi-line"],
+    "lines-between-class-members": [
+      "error",
+      "always",
+      {
+        "exceptAfterSingleLine": true
+      }
+    ],
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "vars": "all",
+        "args": "none",
+        "ignoreRestSiblings": true
+      }
+    ],
+
+    // Disabled rules
+    "arrow-body-style": "off",
+    "import/prefer-default-export": "off",
+    "no-param-reassign": "off",
+    "no-restricted-syntax": "off",
+    "@typescript-eslint/no-shadow": "off",
+    "no-underscore-dangle": "off",
+    "class-methods-use-this": "off",
+    "no-await-in-loop": "off",
+    "no-console": "off",
+    "no-continue": "off"
+  }
+}

package/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Problem
+*Describe the specific bug or product issue that's being fixed.*
+
+## Solution
+*What did you do to fix it? Remember gif's or video of frontend fixes.*
+
+## Additional Notes (optional)
+
+- Link to Tech Spec in Notion
+
+
+## Related PR's (optional)
+
+## New Packages, Environment Variables (optional)

package/.github/workflows/code-style.yml

@@ -0,0 +1,29 @@
+name: Check Prettier and ESLint conformance
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+jobs:
+  prettier:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v3
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+
+      - name: Installing dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Run Prettier checks
+        run: yarn prettier:check
+
+      - name: Run ESLint checks
+        run: yarn lint:check

package/.github/workflows/deploy-staging.yml

@@ -0,0 +1,34 @@
+# Publish a staging build to npm with tag "staging".
+# Push (or merge) to branch "staging" to publish. Consuming apps can then use
+#   "@adalo/metrics": "staging"
+# to test changes on staging before merging to main.
+name: Deploy Staging
+
+on:
+  push:
+    branches:
+      - staging
+
+jobs:
+  build-and-publish:
+    if: "!contains(github.event.head_commit.message, 'skip ci')"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Installing dependencies
+        run: yarn install --frozen-lockfile
+      - name: Build lib
+        run: yarn run build
+      - name: Set staging version
+        run: npm version 0.0.0-staging.${{ github.run_number }} --no-git-tag-version --allow-same-version
+      - name: Publish to NPM (tag staging)
+        run: npm publish --tag staging
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_AUTH_TOKEN }}

package/.github/workflows/deploy.yml

@@ -0,0 +1,29 @@
+name: Deploy Production
+
+on:
+  push:
+    branches:
+      - main
+
+jobs:
+  build:
+    if: "!contains(github.event.head_commit.message, 'skip ci')"
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0 # Fetch all commits across all branches. Default behaviour is efficient but breaks merge-release.
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+          registry-url: 'https://registry.npmjs.org'
+      - name: Installing dependencies
+        run: yarn install --frozen-lockfile
+      - name: Build lib
+        run: yarn run build
+      - name: Publish to NPM
+        uses: AdaloHQ/npm-publish@v1
+        env:
+          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
+          NODE_AUTH_TOKEN: ${{secrets.NPM_AUTH_TOKEN}}

package/.github/workflows/tests.yml

@@ -0,0 +1,17 @@
+name: CI
+
+on: pull_request
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Setup Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+      - name: Installing dependencies
+        run: yarn install --frozen-lockfile
+      - name: Running tests
+        run: yarn test

package/.idea/codeStyles/Project.xml

@@ -0,0 +1,101 @@
+<component name="ProjectCodeStyleConfiguration">
+  <code_scheme name="Project" version="173">
+    <option name="OTHER_INDENT_OPTIONS">
+      <value>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="TAB_SIZE" value="2" />
+      </value>
+    </option>
+    <HTMLCodeStyleSettings>
+      <option name="HTML_SPACE_INSIDE_EMPTY_TAG" value="true" />
+    </HTMLCodeStyleSettings>
+    <JSCodeStyleSettings version="0">
+      <option name="USE_SEMICOLON_AFTER_STATEMENT" value="false" />
+      <option name="FORCE_SEMICOLON_STYLE" value="true" />
+      <option name="SPACE_WITHIN_ARRAY_INITIALIZER_BRACKETS" value="true" />
+      <option name="SPACE_BEFORE_FUNCTION_LEFT_PARENTH" value="false" />
+      <option name="USE_DOUBLE_QUOTES" value="false" />
+      <option name="FORCE_QUOTE_STYlE" value="true" />
+      <option name="ENFORCE_TRAILING_COMMA" value="WhenMultiline" />
+      <option name="SPACES_WITHIN_OBJECT_LITERAL_BRACES" value="true" />
+      <option name="SPACES_WITHIN_IMPORTS" value="true" />
+      <option name="SPACES_WITHIN_INTERPOLATION_EXPRESSIONS" value="true" />
+    </JSCodeStyleSettings>
+    <TypeScriptCodeStyleSettings version="0">
+      <option name="USE_SEMICOLON_AFTER_STATEMENT" value="false" />
+      <option name="FORCE_SEMICOLON_STYLE" value="true" />
+      <option name="SPACE_BEFORE_FUNCTION_LEFT_PARENTH" value="false" />
+      <option name="USE_DOUBLE_QUOTES" value="false" />
+      <option name="FORCE_QUOTE_STYlE" value="true" />
+      <option name="ENFORCE_TRAILING_COMMA" value="WhenMultiline" />
+      <option name="SPACES_WITHIN_OBJECT_LITERAL_BRACES" value="true" />
+      <option name="SPACES_WITHIN_IMPORTS" value="true" />
+    </TypeScriptCodeStyleSettings>
+    <VueCodeStyleSettings>
+      <option name="INTERPOLATION_NEW_LINE_AFTER_START_DELIMITER" value="false" />
+      <option name="INTERPOLATION_NEW_LINE_BEFORE_END_DELIMITER" value="false" />
+    </VueCodeStyleSettings>
+    <codeStyleSettings language="CSS">
+      <indentOptions>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="CONTINUATION_INDENT_SIZE" value="4" />
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="Gherkin">
+      <indentOptions>
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="HTML">
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="JSON">
+      <indentOptions>
+        <option name="CONTINUATION_INDENT_SIZE" value="4" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="JavaScript">
+      <option name="BLOCK_COMMENT_ADD_SPACE" value="true" />
+      <option name="IF_BRACE_FORCE" value="1" />
+      <option name="DOWHILE_BRACE_FORCE" value="1" />
+      <option name="WHILE_BRACE_FORCE" value="1" />
+      <option name="FOR_BRACE_FORCE" value="1" />
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="LESS">
+      <indentOptions>
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="TypeScript">
+      <option name="BLOCK_COMMENT_ADD_SPACE" value="true" />
+      <option name="IF_BRACE_FORCE" value="1" />
+      <option name="DOWHILE_BRACE_FORCE" value="1" />
+      <option name="WHILE_BRACE_FORCE" value="1" />
+      <option name="FOR_BRACE_FORCE" value="1" />
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="INDENT_SIZE" value="2" />
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+        <option name="TAB_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+    <codeStyleSettings language="Vue">
+      <option name="SOFT_MARGINS" value="80" />
+      <indentOptions>
+        <option name="CONTINUATION_INDENT_SIZE" value="2" />
+      </indentOptions>
+    </codeStyleSettings>
+  </code_scheme>
+</component>

package/.idea/codeStyles/codeStyleConfig.xml

@@ -0,0 +1,5 @@
+<component name="ProjectCodeStyleConfiguration">
+  <state>
+    <option name="USE_PER_PROJECT_SETTINGS" value="true" />
+  </state>
+</component>

package/.idea/git_toolbox_prj.xml

@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="GitToolBoxProjectSettings">
+    <option name="commitMessageIssueKeyValidationOverride">
+      <BoolValueOverride>
+        <option name="enabled" value="true" />
+      </BoolValueOverride>
+    </option>
+    <option name="commitMessageValidationEnabledOverride">
+      <BoolValueOverride>
+        <option name="enabled" value="true" />
+      </BoolValueOverride>
+    </option>
+  </component>
+</project>

package/.idea/inspectionProfiles/Project_Default.xml

@@ -0,0 +1,6 @@
+<component name="InspectionProjectProfileManager">
+  <profile version="1.0">
+    <option name="myName" value="Project Default" />
+    <inspection_tool class="Eslint" enabled="true" level="WARNING" enabled_by_default="true" />
+  </profile>
+</component>

package/.idea/jsLibraryMappings.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="JavaScriptLibraryMappings">
+    <includedPredefinedLibrary name="Node.js Core" />
+  </component>
+</project>

package/.idea/prettier.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="PrettierConfiguration">
+    <option name="myConfigurationMode" value="AUTOMATIC" />
+  </component>
+</project>

package/.idea/vcs.xml

@@ -0,0 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<project version="4">
+  <component name="VcsDirectoryMappings">
+    <mapping directory="$PROJECT_DIR$" vcs="Git" />
+  </component>
+</project>

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "printWidth": 80,
+  "tabWidth": 2,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "semi": false,
+  "bracketSpacing": true,
+  "bracketSameLine": false,
+  "arrowParens": "avoid"
+}

package/README-health.md

@@ -0,0 +1,234 @@
+# Health Check Client
+
+Provides health check endpoints for external monitoring services like BetterStack.
+Uses a background worker to periodically check database connections and cache results in Redis,
+preventing HTTP requests from triggering database queries.
+
+## How It Works
+
+1. **Worker Process**: Runs as a separate process (defined in Procfile)
+   - Performs health checks every minute (configurable)
+   - Checks database connections (and optionally Redis)
+   - Stores results in Redis cache with 60-second TTL
+   - Creates its own Redis connection with name `{appName}:healthcheck-worker`
+
+2. **Web Processes**: Handle HTTP requests
+   - Read health check results from Redis cache only
+   - Never trigger database queries
+   - Return cached data or error if Redis unavailable
+   - Use existing system Redis client
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `BUILD_APP_NAME` | Application name for logging and Redis client naming | `unknown-app` |
+| `HOSTNAME` | Dyno/instance ID for logging | `unknown-dyno` |
+| `BUILD_DYNO_PROCESS_TYPE` | Process type for logging | `health-check-worker` |
+| `HEALTH_LOG_VALUES` | Enable logging of health check refresh status (`true`/`false`) | `false` |
+| `HEALTH_DB_MAX_CONNECT_LATENCY_MS` | Fail DB health if connection acquisition/connect time exceeds this (ms) | `1000` |
+| `REDIS_URL` | Redis connection URL for cache | - |
+| `DATABASE_URL` | Main PostgreSQL connection URL (for backend worker) | - |
+| `META_DB_URL` | Main PostgreSQL connection URL (for database worker) | - |
+
+## Usage
+
+### Backend Service
+
+**Endpoint Client** (`lib/healthCheck.ts`):
+```typescript
+import { createHealthCheckEndpointClient } from '@adalo/metrics'
+import { redisClient } from './redis'
+
+export const healthCheckClient = createHealthCheckEndpointClient({
+  redisClient,
+  includeRedisCheck: true,
+})
+```
+
+**Worker** (`health-check-worker.ts`):
+```typescript
+import { createHealthCheckWorker } from '@adalo/metrics'
+import { createNamedRedisClient } from './lib/redis'
+
+const healthCheckRedisClient = createNamedRedisClient('healthcheck-worker')
+
+const runHealthCheckWorker = createHealthCheckWorker({
+  databaseUrl: process.env.DATABASE_URL,
+  databaseName: 'backend',
+  redisClient: healthCheckRedisClient,
+  includeRedisCheck: true,
+})
+
+runHealthCheckWorker().catch(err => {
+  console.error('[HealthCheckWorker] Fatal error:', err)
+  process.exit(1)
+})
+```
+
+**Procfile**:
+```
+health-check-worker: node dist/health-check-worker.js
+```
+
+### Database Service
+
+**Endpoint Client** (`lib/healthCheck.ts`):
+```typescript
+import { createHealthCheckEndpointClient } from '@adalo/metrics'
+import { redisClient } from './cache/client'
+
+export const healthCheckClient = createHealthCheckEndpointClient({
+  redisClient,
+})
+```
+
+**Worker** (`workers/health-check-worker.ts`):
+```typescript
+import { createHealthCheckWorker } from '@adalo/metrics'
+import { getClusterDatabaseUrls } from '../utils/clusterUrls'
+import { createNamedRedisClient } from '../lib/cache/client'
+
+const healthCheckRedisClient = createNamedRedisClient('healthcheck-worker')
+
+const runHealthCheckWorker = createHealthCheckWorker({
+  databaseUrl: process.env.META_DB_URL,
+  databaseName: 'meta_db',
+  additionalDatabaseUrls: getClusterDatabaseUrls(),
+  redisClient: healthCheckRedisClient,
+})
+
+runHealthCheckWorker().catch(err => {
+  console.error('[HealthCheckWorker] Fatal error:', err)
+  process.exit(1)
+})
+```
+
+**Procfile**:
+```
+health-check-worker: node --enable-source-maps dist/workers/health-check-worker.js
+```
+
+## Endpoints
+
+### Default Endpoint
+
+By default, `registerHealthEndpoint()` registers at `/health`:
+
+```typescript
+healthCheckClient.registerHealthEndpoint(app)
+// Registers: GET /health
+```
+
+### Custom Endpoints
+
+You can also register custom endpoints that use the same cached data:
+
+```typescript
+// Backend: /healthcheck (old endpoint, still works)
+app.get('/healthcheck', healthCheckClient.healthHandler())
+
+// Database: /hc (old endpoint, still works)
+app.get('/hc', healthCheckClient.healthHandler())
+```
+
+## Response Format
+
+### Healthy Response
+```json
+{
+  "status": "ok",
+  "lastCheckAt": 1738143477926,
+  "resources": {
+    "DATABASE_URL": { "status": "ok", "connectMs": 9.2 },
+    "REDIS_URL": { "status": "ok" }
+  },
+  "isStale": false,
+  "config": { "checkIntervalMs": 30000, "staleThresholdMs": 180000, "checkTimeoutMs": 15000 }
+}
+```
+
+### Unhealthy Response (Redis Cache Unavailable)
+```json
+{
+  "status": "unhealthy",
+  "timestamp": "2026-01-23T08:27:57.926Z",
+  "checks": {
+    "redis": {
+      "status": "unhealthy",
+      "error": "Redis cache read failed: connection refused"
+    }
+  },
+  "errors": ["Redis cache read failed: connection refused"]
+}
+```
+
+### Unhealthy Response (Database Issue)
+```json
+{
+  "status": "error",
+  "lastCheckAt": 1738143477926,
+  "resources": {
+    "DATABASE_URL": { "status": "error", "error": "connection timeout", "connectMs": 5000 }
+  },
+  "isStale": false,
+  "config": { "checkIntervalMs": 30000, "staleThresholdMs": 180000, "checkTimeoutMs": 15000 }
+}
+```
+
+## Status Codes
+
+- `200` - healthy or degraded
+- `503` - unhealthy (at least one component failed)
+
+## Configuration Options
+
+### Worker Options
+
+```typescript
+createHealthCheckWorker({
+  databaseUrl: string,              // Required: Main database URL
+  databaseName: string,              // Required: Database name
+  redisClient: any,                  // Required: Redis client instance (created with createNamedRedisClient('healthcheck-worker'))
+  additionalDatabaseUrls?: object,   // Optional: Additional clusters (database service)
+  includeRedisCheck?: boolean,       // Optional: Include Redis in health check (default: false)
+  refreshIntervalMs?: number,         // Optional: Refresh interval (default: 30000ms)
+  appName?: string,                  // Optional: App name (defaults to BUILD_APP_NAME)
+})
+```
+
+### Endpoint Client Options
+
+```typescript
+createHealthCheckEndpointClient({
+  redisClient: any,                  // Required: Existing Redis client from system
+  includeRedisCheck?: boolean,       // Optional: Include Redis in response (default: false)
+})
+```
+
+## Logging Format
+
+Worker logs follow the same format as metrics:
+
+```
+[health-check-worker] [app-name] [dyno-id] [HealthCheck] Starting health check worker...
+[health-check-worker] [app-name] [dyno-id] [HealthCheck] Refresh interval: 60000ms
+```
+
+When `HEALTH_LOG_VALUES=true`, additional logs are printed:
+
+```
+[health-check-worker] [app-name] [dyno-id] [HealthCheck] Initial health check completed
+[health-check-worker] [app-name] [dyno-id] [HealthCheck] Health check refreshed at 2026-01-23T08:27:57.926Z, status: healthy
+```
+
+Error logs are always printed regardless of `HEALTH_LOG_VALUES` setting.
+
+## Benefits
+
+- **No Concurrent DB Queries**: Only worker queries database, endpoints read from cache
+- **Same Data Per Minute**: All requests get the same cached result within the TTL period
+- **Redis Optional**: Works even if Redis is disabled (falls back to in-memory cache per process)
+- **Graceful Degradation**: Returns proper error format if Redis unavailable
+- **Multi-Process Support**: Shared cache across all web process instances via Redis
+