@ossy/platform 3.12.0 → 3.13.0

package/README.md

@@ -11,12 +11,13 @@ At startup `@ossy/platform`:
 3. Registers and runs all **startup hooks** (`*.startup.js`) in order.
 4. Connects all **integrations** (`*.integration.js`) by calling `connect({ env })`.
 5. Registers all **tasks** (`*.task.js`) with `TaskService` and starts the cron scheduler.
-6. Registers all **schemas** (`*.schema.js`) with `registerSchema`.
-7. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
-8. Registers all **actions** (`*.action.js`) with `ActionService`.
-9. Mounts **MCP** at `POST /mcp` and serves `GET /capabilities.json`.
-10. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
-11. Auto-mounts every action at `POST /actions` (`{ action, payload }`).
+6. When `MAXMIND_LICENSE_KEY` is set, downloads GeoLite2-Country to `GEOLITE2_COUNTRY_MMDB` (default `/tmp/GeoLite2-Country.mmdb`) so Host location projections can resolve country. Missing key or a failed download does not prevent startup (#804).
+7. Registers all **schemas** (`*.schema.js`) with `registerSchema`.
+8. Rebuilds all **aggregates** (`*.aggregate.js`) from the event store.
+9. Registers all **actions** (`*.action.js`) with `ActionService`.
+10. Mounts **MCP** at `POST /mcp` and serves `GET /capabilities.json`.
+11. Starts an Express server that routes requests to pages (`*.page.jsx`) and API handlers (`*.api.js`).
+12. Auto-mounts every action at `POST /actions` (`{ action, payload }`).
 
 Page SSR fills the `app:content` slot (see `PlatformShell` and `resolve-app-slots` in `@ossy/app`). App chrome uses namespaced keys such as `app:header` mapped from `export const slots` in `*.layout.jsx`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ossy/platform",
-  "version": "3.12.0",
+  "version": "3.13.0",
   "description": "Ossy application server runtime",
   "repository": {
     "type": "git",
@@ -76,5 +76,5 @@
     "Dockerfile",
     "docker-healthcheck.js"
   ],
-  "gitHead": "c2650803219ad1831559b512848358d9550ffad2"
+  "gitHead": "7a02d1e056b731aa36f72e3f8d6df941101dbd50"
 }

package/src/geoip/ensure-geolite2-country.js

@@ -0,0 +1,119 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { createLogger } from '@ossy/observability'
+import { extractMmdbFromTarGz } from './extract-mmdb-from-tar-gz.js'
+import {
+  GEOLITE2_COUNTRY_DOWNLOAD_TIMEOUT_MS,
+  GEOLITE2_COUNTRY_MMDB_PATH,
+} from './geolite2-country-path.js'
+
+const log = createLogger('@ossy/platform/geoip')
+
+const LEGACY_DOWNLOAD_URL = 'https://download.maxmind.com/app/geoip_download'
+const PERMALINK_DOWNLOAD_URL = 'https://download.maxmind.com/geoip/databases/GeoLite2-Country/download?suffix=tar.gz'
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string}
+ */
+export function resolveGeoLite2CountryPath (env = process.env) {
+  const raw = env.GEOLITE2_COUNTRY_MMDB ?? env.OSSY_GEOLITE2_COUNTRY_MMDB ?? ''
+  const trimmed = String(raw).trim()
+  return trimmed || GEOLITE2_COUNTRY_MMDB_PATH
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string | null}
+ */
+export function resolveMaxMindLicenseKey (env = process.env) {
+  const raw = env.MAXMIND_LICENSE_KEY ?? env.OSSY_MAXMIND_LICENSE_KEY ?? ''
+  const key = String(raw).trim()
+  return key || null
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string | null}
+ */
+export function resolveMaxMindAccountId (env = process.env) {
+  const raw = env.MAXMIND_ACCOUNT_ID ?? env.OSSY_MAXMIND_ACCOUNT_ID ?? ''
+  const id = String(raw).trim()
+  return id || null
+}
+
+/**
+ * @param {{ licenseKey: string, accountId?: string | null }} options
+ * @returns {{ url: string, headers: Record<string, string> }}
+ */
+export function maxMindDownloadRequest ({ licenseKey, accountId }) {
+  if (accountId) {
+    const basic = Buffer.from(`${accountId}:${licenseKey}`, 'utf8').toString('base64')
+    return {
+      url: PERMALINK_DOWNLOAD_URL,
+      headers: { Authorization: `Basic ${basic}` },
+    }
+  }
+  const url = `${LEGACY_DOWNLOAD_URL}?edition_id=GeoLite2-Country&license_key=${encodeURIComponent(licenseKey)}&suffix=tar.gz`
+  return { url, headers: {} }
+}
+
+/**
+ * Download GeoLite2-Country when `MAXMIND_LICENSE_KEY` is set.
+ *
+ * Shared by every `@ossy/platform` `startServer` image (ossy.se, plexus-sanitas,
+ * future `services[]` sites). Missing key / failed download is non-fatal:
+ * the process starts and location tiles omit `countryCode` (#804).
+ *
+ * @param {{
+ *   env?: NodeJS.ProcessEnv,
+ *   fetchImpl?: typeof fetch,
+ * }} [options]
+ * @returns {Promise<string | null>} destination path when a readable `.mmdb` is in place
+ */
+export async function ensureGeoLite2Country (options = {}) {
+  const env = options.env ?? process.env
+  const fetchImpl = options.fetchImpl ?? fetch
+  const dest = resolveGeoLite2CountryPath(env)
+
+  if (fs.existsSync(dest)) {
+    env.GEOLITE2_COUNTRY_MMDB = dest
+    log.info(`GeoLite2-Country already present at ${dest}`)
+    return dest
+  }
+
+  const licenseKey = resolveMaxMindLicenseKey(env)
+  if (!licenseKey) {
+    log.info('MAXMIND_LICENSE_KEY unset — skipping GeoLite2-Country download; location tiles will omit countryCode')
+    return null
+  }
+
+  const accountId = resolveMaxMindAccountId(env)
+  const { url, headers } = maxMindDownloadRequest({ licenseKey, accountId })
+
+  try {
+    log.info('Downloading GeoLite2-Country from MaxMind')
+    const response = await fetchImpl(url, {
+      headers,
+      signal: AbortSignal.timeout(GEOLITE2_COUNTRY_DOWNLOAD_TIMEOUT_MS),
+    })
+    if (!response.ok) {
+      throw new Error(`MaxMind download HTTP ${response.status}`)
+    }
+    const gzipped = Buffer.from(await response.arrayBuffer())
+    const mmdb = extractMmdbFromTarGz(gzipped)
+
+    fs.mkdirSync(path.dirname(dest), { recursive: true })
+    const staging = `${dest}.download`
+    fs.writeFileSync(staging, mmdb)
+    fs.renameSync(staging, dest)
+    env.GEOLITE2_COUNTRY_MMDB = dest
+    log.info(`Wrote GeoLite2-Country to ${dest}`)
+    return dest
+  } catch (err) {
+    log.warn('GeoLite2-Country download failed — location tiles will omit countryCode', {
+      error: err instanceof Error ? err.message : String(err),
+    })
+    return null
+  }
+}

package/src/geoip/ensure-geolite2-country.spec.js

@@ -0,0 +1,140 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+import { afterEach, describe, expect, it } from '@jest/globals'
+import {
+  ensureGeoLite2Country,
+  maxMindDownloadRequest,
+  resolveGeoLite2CountryPath,
+  resolveMaxMindLicenseKey,
+} from './ensure-geolite2-country.js'
+import { GEOLITE2_COUNTRY_MMDB_PATH } from './geolite2-country-path.js'
+import { makeUstarTarGz } from './tar-fixture.js'
+
+const originalGeo = process.env.GEOLITE2_COUNTRY_MMDB
+const originalOssyGeo = process.env.OSSY_GEOLITE2_COUNTRY_MMDB
+const originalKey = process.env.MAXMIND_LICENSE_KEY
+const originalOssyKey = process.env.OSSY_MAXMIND_LICENSE_KEY
+const originalAccount = process.env.MAXMIND_ACCOUNT_ID
+
+function restoreEnv () {
+  restore('GEOLITE2_COUNTRY_MMDB', originalGeo)
+  restore('OSSY_GEOLITE2_COUNTRY_MMDB', originalOssyGeo)
+  restore('MAXMIND_LICENSE_KEY', originalKey)
+  restore('OSSY_MAXMIND_LICENSE_KEY', originalOssyKey)
+  restore('MAXMIND_ACCOUNT_ID', originalAccount)
+}
+
+function restore (key, previous) {
+  if (previous == null) delete process.env[key]
+  else process.env[key] = previous
+}
+
+describe('resolveGeoLite2CountryPath', () => {
+  afterEach(restoreEnv)
+
+  it('defaults to the well-known container path', () => {
+    expect(resolveGeoLite2CountryPath({})).toBe(GEOLITE2_COUNTRY_MMDB_PATH)
+  })
+
+  it('prefers GEOLITE2_COUNTRY_MMDB', () => {
+    expect(resolveGeoLite2CountryPath({ GEOLITE2_COUNTRY_MMDB: '/var/lib/GeoLite2-Country.mmdb' }))
+      .toBe('/var/lib/GeoLite2-Country.mmdb')
+  })
+})
+
+describe('resolveMaxMindLicenseKey', () => {
+  it('returns null when unset', () => {
+    expect(resolveMaxMindLicenseKey({})).toBeNull()
+  })
+
+  it('trims OSSY_MAXMIND_LICENSE_KEY', () => {
+    expect(resolveMaxMindLicenseKey({ OSSY_MAXMIND_LICENSE_KEY: '  abc  ' })).toBe('abc')
+  })
+})
+
+describe('maxMindDownloadRequest', () => {
+  it('uses the legacy query URL without an account id', () => {
+    const request = maxMindDownloadRequest({ licenseKey: 'secret-key' })
+    expect(request.url).toContain('edition_id=GeoLite2-Country')
+    expect(request.url).toContain('license_key=secret-key')
+    expect(request.headers.Authorization).toBeUndefined()
+  })
+
+  it('uses basic auth permalink when account id is set', () => {
+    const request = maxMindDownloadRequest({ licenseKey: 'secret-key', accountId: '123456' })
+    expect(request.url).toBe('https://download.maxmind.com/geoip/databases/GeoLite2-Country/download?suffix=tar.gz')
+    expect(request.headers.Authorization).toBe(`Basic ${Buffer.from('123456:secret-key').toString('base64')}`)
+  })
+})
+
+describe('ensureGeoLite2Country', () => {
+  afterEach(restoreEnv)
+
+  it('skips download when the license key is missing', async () => {
+    const env = {}
+    let called = false
+    const dest = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => {
+        called = true
+        return { ok: false, status: 500, arrayBuffer: async () => new ArrayBuffer(0) }
+      },
+    })
+    expect(dest).toBeNull()
+    expect(called).toBe(false)
+  })
+
+  it('returns the existing file without fetching', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'geolite2-'))
+    const dest = path.join(dir, 'GeoLite2-Country.mmdb')
+    fs.writeFileSync(dest, 'already-there')
+    const env = { GEOLITE2_COUNTRY_MMDB: dest, MAXMIND_LICENSE_KEY: 'secret-key' }
+    let called = false
+    const result = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => {
+        called = true
+        return { ok: true, status: 200, arrayBuffer: async () => new ArrayBuffer(0) }
+      },
+    })
+    expect(result).toBe(dest)
+    expect(called).toBe(false)
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('writes the extracted mmdb and sets GEOLITE2_COUNTRY_MMDB', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'geolite2-'))
+    const dest = path.join(dir, 'GeoLite2-Country.mmdb')
+    const payload = Buffer.from('country-mmdb')
+    const archive = makeUstarTarGz('GeoLite2-Country_20240101/GeoLite2-Country.mmdb', payload)
+    const env = { GEOLITE2_COUNTRY_MMDB: dest, MAXMIND_LICENSE_KEY: 'secret-key' }
+
+    const result = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => ({
+        ok: true,
+        status: 200,
+        arrayBuffer: async () => archive,
+      }),
+    })
+
+    expect(result).toBe(dest)
+    expect(env.GEOLITE2_COUNTRY_MMDB).toBe(dest)
+    expect(fs.readFileSync(dest).equals(payload)).toBe(true)
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+
+  it('does not throw when MaxMind returns an error', async () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'geolite2-'))
+    const dest = path.join(dir, 'GeoLite2-Country.mmdb')
+    const env = { GEOLITE2_COUNTRY_MMDB: dest, MAXMIND_LICENSE_KEY: 'secret-key' }
+    const result = await ensureGeoLite2Country({
+      env,
+      fetchImpl: async () => ({ ok: false, status: 401, arrayBuffer: async () => new ArrayBuffer(0) }),
+    })
+    expect(result).toBeNull()
+    expect(fs.existsSync(dest)).toBe(false)
+    fs.rmSync(dir, { recursive: true, force: true })
+  })
+})

package/src/geoip/extract-mmdb-from-tar-gz.js

@@ -0,0 +1,68 @@
+import { gunzipSync } from 'node:zlib'
+
+const BLOCK = 512
+const MAX_ARCHIVE_BYTES = 50 * 1024 * 1024
+const MAX_MMDB_BYTES = 20 * 1024 * 1024
+
+/**
+ * @param {Buffer} header
+ * @param {number} start
+ * @param {number} len
+ * @returns {number}
+ */
+function readOctal (header, start, len) {
+  const raw = header.subarray(start, start + len).toString('utf8').replace(/\0/g, '').trim()
+  if (!raw) return 0
+  const parsed = Number.parseInt(raw, 8)
+  return Number.isFinite(parsed) ? parsed : 0
+}
+
+/**
+ * @param {Buffer} header
+ * @returns {string}
+ */
+function headerName (header) {
+  const name = header.subarray(0, 100).toString('utf8').replace(/\0/g, '').trim()
+  const prefix = header.subarray(345, 345 + 155).toString('utf8').replace(/\0/g, '').trim()
+  return prefix ? `${prefix}/${name}` : name
+}
+
+/**
+ * Extract the first `.mmdb` member from a MaxMind GeoLite2 `.tar.gz`.
+ * Writes none of the tar paths — callers choose the destination (#804).
+ *
+ * @param {Buffer} gzipped
+ * @returns {Buffer}
+ */
+export function extractMmdbFromTarGz (gzipped) {
+  if (!Buffer.isBuffer(gzipped) || gzipped.length < 20) {
+    throw new Error('GeoLite2 archive is empty or invalid')
+  }
+  if (gzipped.length > MAX_ARCHIVE_BYTES) {
+    throw new Error('GeoLite2 archive is too large')
+  }
+
+  const tar = gunzipSync(gzipped)
+  let offset = 0
+  while (offset + BLOCK <= tar.length) {
+    const header = tar.subarray(offset, offset + BLOCK)
+    if (header.every((byte) => byte === 0)) break
+
+    const size = readOctal(header, 124, 12)
+    const typeflag = String.fromCharCode(header[156] || 0)
+    const name = headerName(header)
+    offset += BLOCK
+    const padded = Math.ceil(size / BLOCK) * BLOCK
+    const content = tar.subarray(offset, Math.min(offset + size, tar.length))
+    offset += padded
+
+    const isFile = typeflag === '0' || typeflag === '\0' || typeflag === ''
+    if (!isFile || !name.toLowerCase().endsWith('.mmdb')) continue
+    if (content.length > MAX_MMDB_BYTES) {
+      throw new Error('GeoLite2 mmdb member is too large')
+    }
+    return Buffer.from(content)
+  }
+
+  throw new Error('No .mmdb file in GeoLite2 archive')
+}

package/src/geoip/extract-mmdb-from-tar-gz.spec.js

@@ -0,0 +1,20 @@
+import { extractMmdbFromTarGz } from './extract-mmdb-from-tar-gz.js'
+import { makeUstarTarGz } from './tar-fixture.js'
+
+describe('extractMmdbFromTarGz', () => {
+  it('returns the first .mmdb member', () => {
+    const payload = Buffer.from('fake-mmdb-bytes')
+    const archive = makeUstarTarGz('GeoLite2-Country_20240101/GeoLite2-Country.mmdb', payload)
+    expect(extractMmdbFromTarGz(archive).equals(payload)).toBe(true)
+  })
+
+  it('skips non-mmdb members', () => {
+    const readme = Buffer.from('not the database')
+    const archive = makeUstarTarGz('GeoLite2-Country_20240101/COPYRIGHT.txt', readme)
+    expect(() => extractMmdbFromTarGz(archive)).toThrow(/No \.mmdb file/)
+  })
+
+  it('rejects empty input', () => {
+    expect(() => extractMmdbFromTarGz(Buffer.alloc(0))).toThrow(/empty or invalid/)
+  })
+})

package/src/geoip/geolite2-country-path.js

@@ -0,0 +1,10 @@
+/**
+ * Well-known GeoLite2-Country path on platform containers (#804).
+ *
+ * Keep in sync with `@ossy/deployment-tools` `GEOLITE2_COUNTRY_MMDB_PATH`
+ * (ECS task-definition env). Writable on Fargate ephemeral disk.
+ */
+export const GEOLITE2_COUNTRY_MMDB_PATH = '/tmp/GeoLite2-Country.mmdb'
+
+/** Abort hung MaxMind downloads before ECS health startPeriod (60s). */
+export const GEOLITE2_COUNTRY_DOWNLOAD_TIMEOUT_MS = 30_000

package/src/geoip/tar-fixture.js

@@ -0,0 +1,31 @@
+import { gzipSync } from 'node:zlib'
+
+const BLOCK = 512
+
+/**
+ * Build a gzipped ustar archive with a single file (test fixture).
+ *
+ * @param {string} name
+ * @param {Buffer | string} content
+ * @returns {Buffer}
+ */
+export function makeUstarTarGz (name, content) {
+  const data = Buffer.isBuffer(content) ? content : Buffer.from(content)
+  const header = Buffer.alloc(BLOCK)
+  header.write(name, 0, 100, 'utf8')
+  header.write('0000644\0', 100, 8, 'utf8')
+  header.write('0000000\0', 108, 8, 'utf8')
+  header.write('0000000\0', 116, 8, 'utf8')
+  header.write(`${data.length.toString(8).padStart(11, '0')}\0`, 124, 12, 'utf8')
+  header.write('00000000000\0', 136, 12, 'utf8')
+  header.write('        ', 148, 8, 'utf8')
+  header[156] = 0x30
+  header.write('ustar\0', 257, 6, 'utf8')
+  header.write('00', 263, 2, 'utf8')
+  let sum = 0
+  for (const byte of header) sum += byte
+  header.write(`${sum.toString(8).padStart(6, '0')}\0 `, 148, 8, 'utf8')
+  const padded = Buffer.alloc(Math.ceil(data.length / BLOCK) * BLOCK)
+  data.copy(padded)
+  return gzipSync(Buffer.concat([header, padded, Buffer.alloc(1024)]))
+}

package/src/server.js

@@ -28,6 +28,7 @@ import {
 } from './entitlements/action-entitlement.js'
 import { closePushSseConnections, mountPushSse } from './push/mount-push-sse.js'
 import { mountHealthEndpoint } from './health.js'
+import { ensureGeoLite2Country } from './geoip/ensure-geolite2-country.js'
 import {
   createSlowRequestLogger,
   createTimedOperation,
@@ -289,6 +290,10 @@ export async function startServer (options = {}) {
 
   TaskService.startScheduler()
 
+  // GeoLite2-Country for Host location projections (#804). Shared by every
+  // startServer image (ossy.se, plexus-sanitas, …). Missing key is non-fatal.
+  await ensureGeoLite2Country()
+
   if (process.env.DB_URL) {
     await ensureEventStoreIndexes().catch((err) => {
       log.error('Failed to ensure MongoDB indexes — aggregate reads may be very slow', undefined, err)