@siax/version-endpoint (0.1.0)
Installation
@siax:registry=https://git.cloud.siax.io/api/packages/sax3l/npm/npm install @siax/version-endpoint@0.1.0"@siax/version-endpoint": "0.1.0"About this package
@siax/version-endpoint
The shared /version convention (P007, standard/release/RELEASE_CHAIN_SPEC.md).
Zero dependencies. Fastify is a peer, not a dependency.
Why this exists
Every SIAX Cloud OS service already has a /v1/<os>/health liveness route.
None had a /version route before P007 — package.json's version field
is a static, never-bumped placeholder in every service checked (0.0.0,
0.1.0), unrelated to what commit is actually running. siax doctor production's PROD-VERSION/PROD-SHA-CHAIN-CONSISTENCY checks need a REAL
answer to "what SHA is this specific running process built from" — this
package is that answer.
Usage
Fastify (st0re, n0d)
import { registerVersionRoute } from '@siax/version-endpoint/fastify';
registerVersionRoute(app, {
serviceName: '@siax/st0re', // matches the `service` field /health already reports
path: '/v1/st0re/version',
});
Next.js App Router (cl0ud)
// apps/console/app/api/version/route.ts
import { NextResponse } from 'next/server';
import { buildVersionPayload } from '@siax/version-endpoint';
export const runtime = 'nodejs';
export const dynamic = 'force-dynamic';
export async function GET() {
return NextResponse.json(buildVersionPayload({ serviceName: '@siax/cl0ud' }), {
headers: { 'Cache-Control': 'no-store' },
});
}
Plain Node http
import { versionHandler } from '@siax/version-endpoint';
server.on('request', (req, res) => {
if (req.url === '/version') return versionHandler({ serviceName: 'my-service' })(req, res);
});
Where sha/builtAt actually come from
GIT_SHA and BUILD_TIME environment variables, baked into the image as
ENV (not just a build-time ARG) by the Dockerfile:
ARG GIT_SHA=unknown
ENV GIT_SHA=$GIT_SHA
ARG BUILD_TIME=unknown
ENV BUILD_TIME=$BUILD_TIME
docker build \
--build-arg GIT_SHA="$(git rev-parse HEAD)" \
--build-arg BUILD_TIME="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
-t <image> .
Never set from a package version, never inferred from a local .git
directory at runtime (a production container has no .git) — only from
what the image was actually told at build time. Missing/malformed →
"unknown", never a guess.
Tests
node --test test/*.test.mjs # 5 tests