@x12i/core-service

Thin HTTP compliance kit for x12i / exellix services.

Depends on:

• @x12i/ports-manager — zone ports
• @x12i/api-live-view — /_live

Rule: any process that binds an HTTP port should use this package.

Install

npm install @x12i/core-service

Peer (Fastify adapter): fastify@^5 · optional @fastify/cors.

Compliance contract

1. Port from zone map (env override OK; avoid/quarantine enforced)
2. GET /health → { ok, service, … }
3. /_live (+ traffic APIs)
4. x-correlation-id on request/response
5. Startup banner: origin · health · live

Fastify

import Fastify from "fastify";
import { attachCoreFastify } from "@x12i/core-service/fastify";

const app = Fastify();
const core = await attachCoreFastify(app, {
  identity: {
    id: "@x12i/my-service",
    title: "My Service",
    zoneId: "memorix",
    portKey: "service",
    portEnv: "MEMORIX_SERVICE_PORT",
    docsPath: "/api/openapi.json",
  },
  getHealth: async () => ({ ok: true, service: "@x12i/my-service" }),
});

await app.listen({ port: core.port, host: "127.0.0.1" });

Node http

import http from "node:http";
import { createCoreNodeHttp, listenAndAnnounce } from "@x12i/core-service";

const core = createCoreNodeHttp({
  identity: {
    id: "ops-source",
    title: "Ops Source",
    zoneId: "memorix",
    portKey: "opsSource",
    portEnv: "OPS_SOURCE_PORT",
    docsPath: "/openapi.json",
  },
});

const server = http.createServer(async (req, res) => {
  if (await core.tryHandleCore(req, res)) return;
  core.withInboundTiming(req, res, "/", req.method ?? "GET", () => {
    res.writeHead(200, { "content-type": "application/json" });
    res.end(JSON.stringify({ ok: true }));
  });
});

await listenAndAnnounce({
  server,
  port: core.port,
  label: "ops-source",
  docsPath: "/openapi.json",
});

Ports helper

import { resolveServicePorts } from "@x12i/core-service";

const p = resolveServicePorts({
  zoneId: "narrix",
  portKey: "api",
  portEnv: "NARRIX_PORT",
});
p.assertApiPort(); // even + in-zone + not avoided

License

exellix-license