@intranefr/superbackend 1.4.4 → 1.5.1

package/src/services/pagesContext.service.js

@@ -0,0 +1,331 @@
+const crypto = require('crypto');
+const mongoose = require('mongoose');
+
+const cacheLayer = require('./cacheLayer.service');
+const globalSettingsService = require('./globalSettings.service');
+
+function sha1(text) {
+  return crypto.createHash('sha1').update(String(text || ''), 'utf8').digest('hex');
+}
+
+function parseDurationToMs(input) {
+  if (input === null || input === undefined) return null;
+  if (typeof input === 'number' && Number.isFinite(input)) return input;
+
+  const s = String(input).trim().toLowerCase();
+  if (!s) return null;
+
+  const m = s.match(/^([0-9]+(?:\.[0-9]+)?)\s*(ms|s|m)$/);
+  if (!m) return null;
+
+  const n = Number(m[1]);
+  const unit = m[2];
+  if (!Number.isFinite(n)) return null;
+
+  if (unit === 'ms') return Math.round(n);
+  if (unit === 's') return Math.round(n * 1000);
+  if (unit === 'm') return Math.round(n * 60 * 1000);
+  return null;
+}
+
+async function getDefaultTimeoutMs() {
+  const fromSetting = await globalSettingsService.getSettingValue('PAGES_CONTEXT_BLOCK_TIMEOUT', null).catch(() => null);
+  const fromEnv = process.env.PAGES_CONTEXT_BLOCK_TIMEOUT;
+  const v = fromSetting !== null && fromSetting !== undefined ? fromSetting : (fromEnv !== undefined ? fromEnv : '30s');
+  const ms = parseDurationToMs(v);
+  return ms === null ? 30_000 : ms;
+}
+
+function getByPath(obj, path) {
+  const parts = String(path || '').split('.').filter(Boolean);
+  let cur = obj;
+  for (const p of parts) {
+    if (!cur || typeof cur !== 'object') return undefined;
+    cur = cur[p];
+  }
+  return cur;
+}
+
+function interpolateCtx(value, ctxRoot) {
+  if (value === null || value === undefined) return value;
+
+  if (Array.isArray(value)) {
+    return value.map((v) => interpolateCtx(v, ctxRoot));
+  }
+
+  if (typeof value === 'object') {
+    const keys = Object.keys(value);
+    if (keys.length === 1 && keys[0] === '$ctx') {
+      return getByPath(ctxRoot, value.$ctx);
+    }
+
+    const out = {};
+    for (const k of keys) {
+      out[k] = interpolateCtx(value[k], ctxRoot);
+    }
+    return out;
+  }
+
+  return value;
+}
+
+function buildHelpers() {
+  const sb = globalThis.superbackend || globalThis.saasbackend || null;
+  const services = (sb && sb.services) ? sb.services : {};
+  const models = (sb && sb.models) ? sb.models : {};
+
+  const denyServices = new Set([
+    'globalSettings',
+    'migration',
+    'workflow',
+  ]);
+
+  const safeServices = {};
+  for (const [k, v] of Object.entries(services || {})) {
+    if (denyServices.has(k)) continue;
+    safeServices[k] = v;
+  }
+
+  return {
+    services: safeServices,
+    models,
+    mongoose,
+  };
+}
+
+function buildAuthContext(req) {
+  const user = req?.user ? req.user : null;
+  if (!user) return null;
+  return {
+    userId: user._id ? String(user._id) : null,
+    role: user.role || null,
+  };
+}
+
+function buildSessionContext(req) {
+  const session = req?.session || null;
+  if (!session || typeof session !== 'object') return null;
+
+  const safe = {};
+  for (const [k, v] of Object.entries(session)) {
+    if (k.toLowerCase().includes('token')) continue;
+    if (k.toLowerCase().includes('secret')) continue;
+    safe[k] = v;
+  }
+  return safe;
+}
+
+async function withOptionalTimeout(promise, { enabled, timeoutMs }) {
+  if (!enabled) return promise;
+
+  const ms = Number(timeoutMs);
+  if (!Number.isFinite(ms) || ms <= 0) return promise;
+
+  let t;
+  const timeoutPromise = new Promise((_, reject) => {
+    t = setTimeout(() => {
+      const err = new Error('Context block timed out');
+      err.code = 'TIMEOUT';
+      reject(err);
+    }, ms);
+  });
+
+  try {
+    return await Promise.race([promise, timeoutPromise]);
+  } finally {
+    if (t) clearTimeout(t);
+  }
+}
+
+async function runDbQueryBlock(block, pageContext) {
+  const props = block?.props || {};
+
+  const modelName = String(props.model || '').trim();
+  if (!modelName) throw Object.assign(new Error('db.query requires props.model'), { code: 'VALIDATION' });
+
+  const op = String(props.op || (props.mode === 'one' ? 'findOne' : 'find')).trim();
+  const assignTo = String(props.assignTo || '').trim();
+  if (!assignTo) throw Object.assign(new Error('db.query requires props.assignTo'), { code: 'VALIDATION' });
+
+  const Model = mongoose.models[modelName] || (mongoose.modelNames().includes(modelName) ? mongoose.model(modelName) : null);
+  if (!Model) throw Object.assign(new Error(`Unknown model: ${modelName}`), { code: 'VALIDATION' });
+
+  const ctxRoot = {
+    pageContext,
+    auth: pageContext.auth,
+    session: pageContext.session,
+    vars: pageContext.vars,
+    params: pageContext.params,
+    query: pageContext.query,
+  };
+
+  const filter = interpolateCtx(props.filter || {}, ctxRoot);
+  const sort = interpolateCtx(props.sort || undefined, ctxRoot);
+  const select = interpolateCtx(props.select || undefined, ctxRoot);
+  const limit = interpolateCtx(props.limit || undefined, ctxRoot);
+
+  let q;
+  if (op === 'findOne') {
+    q = Model.findOne(filter);
+  } else if (op === 'find') {
+    q = Model.find(filter);
+  } else if (op === 'countDocuments') {
+    q = Model.countDocuments(filter);
+  } else {
+    throw Object.assign(new Error(`Unsupported db.query op: ${op}`), { code: 'VALIDATION' });
+  }
+
+  if (select !== undefined && select !== null && typeof q.select === 'function') {
+    q = q.select(select);
+  }
+
+  if (sort && typeof q.sort === 'function') {
+    q = q.sort(sort);
+  }
+
+  if (op === 'find' && limit !== undefined && limit !== null && typeof q.limit === 'function') {
+    const n = parseInt(String(limit), 10);
+    if (Number.isFinite(n) && n > 0) q = q.limit(n);
+  }
+
+  if (typeof q.lean === 'function') q = q.lean();
+
+  const result = await q;
+  pageContext.vars[assignTo] = result;
+  return result;
+}
+
+async function runServiceInvokeBlock(block, pageContext) {
+  const props = block?.props || {};
+
+  const servicePath = String(props.servicePath || '').trim();
+  if (!servicePath) throw Object.assign(new Error('service.invoke requires props.servicePath'), { code: 'VALIDATION' });
+
+  const assignTo = String(props.assignTo || '').trim();
+  if (!assignTo) throw Object.assign(new Error('service.invoke requires props.assignTo'), { code: 'VALIDATION' });
+
+  const ctxRoot = {
+    pageContext,
+    auth: pageContext.auth,
+    session: pageContext.session,
+    vars: pageContext.vars,
+    params: pageContext.params,
+    query: pageContext.query,
+  };
+
+  const args = interpolateCtx(props.args || [], ctxRoot);
+
+  const fn = getByPath(pageContext.helpers, servicePath);
+  if (typeof fn !== 'function') {
+    throw Object.assign(new Error(`service.invoke target is not a function: ${servicePath}`), { code: 'VALIDATION' });
+  }
+
+  const result = await fn(...(Array.isArray(args) ? args : [args]));
+  pageContext.vars[assignTo] = result;
+  return result;
+}
+
+function defaultCacheKeyForBlock({ pageId, routePath, block }) {
+  return sha1(JSON.stringify({ pageId, routePath, block }));
+}
+
+async function runContextBlock(block, { pageId, routePath, pageContext }) {
+  const type = String(block?.type || '').trim();
+
+  const cache = block?.props?.cache || null;
+  const cacheEnabled = Boolean(cache?.enabled);
+  const namespace = cache?.namespace ? String(cache.namespace) : 'pages:ssr';
+  const ttlSeconds = cache?.ttlSeconds === undefined ? undefined : cache.ttlSeconds;
+
+  const timeoutEnabled = Boolean(block?.props?.timeout?.enabled);
+  const timeoutMsRaw = block?.props?.timeout?.ms || block?.props?.timeout?.value || null;
+  const defaultTimeoutMs = await getDefaultTimeoutMs();
+  const timeoutMs = parseDurationToMs(timeoutMsRaw) ?? defaultTimeoutMs;
+
+  const compute = async () => {
+    if (type === 'context.db_query') {
+      return runDbQueryBlock(block, pageContext);
+    }
+    if (type === 'context.service_invoke') {
+      return runServiceInvokeBlock(block, pageContext);
+    }
+    throw Object.assign(new Error(`Unknown context block type: ${type}`), { code: 'VALIDATION' });
+  };
+
+  const run = async () => withOptionalTimeout(compute(), { enabled: timeoutEnabled, timeoutMs });
+
+  if (!cacheEnabled) {
+    return run();
+  }
+
+  const key = cache?.key
+    ? String(interpolateCtx(cache.key, { pageContext, vars: pageContext.vars, params: pageContext.params, query: pageContext.query, auth: pageContext.auth, session: pageContext.session }))
+    : defaultCacheKeyForBlock({ pageId, routePath, block });
+
+  const cached = await cacheLayer.get(key, { namespace }).catch(() => null);
+  if (cached !== null && cached !== undefined) {
+    return cached;
+  }
+
+  const value = await run();
+  await cacheLayer.set(key, value, { namespace, ttlSeconds }).catch(() => {});
+  return value;
+}
+
+function splitBlocks(page) {
+  const blocks = Array.isArray(page?.blocks) ? page.blocks : [];
+  const contextBlocks = [];
+  const renderBlocks = [];
+
+  for (const b of blocks) {
+    const t = String(b?.type || '').trim();
+    if (t.startsWith('context.')) {
+      contextBlocks.push(b);
+    } else {
+      renderBlocks.push(b);
+    }
+  }
+
+  return { contextBlocks, renderBlocks };
+}
+
+async function resolvePageContext({ page, req, res, routePath, params = {}, mockContext = null }) {
+  const pageContext = {
+    vars: {},
+    helpers: buildHelpers(),
+    auth: buildAuthContext(req),
+    session: buildSessionContext(req),
+    params: params || {},
+    query: (req && req.query) ? req.query : {},
+    request: {
+      path: routePath || (req ? req.path : null),
+      method: req ? req.method : null,
+    },
+  };
+
+  if (mockContext && typeof mockContext === 'object') {
+    if (mockContext.auth !== undefined) pageContext.auth = mockContext.auth;
+    if (mockContext.session !== undefined) pageContext.session = mockContext.session;
+    if (mockContext.params !== undefined) pageContext.params = mockContext.params;
+    if (mockContext.query !== undefined) pageContext.query = mockContext.query;
+  }
+
+  const { contextBlocks, renderBlocks } = splitBlocks(page);
+
+  for (const block of contextBlocks) {
+    await runContextBlock(block, {
+      pageId: page?._id ? String(page._id) : null,
+      routePath: routePath || (req ? req.path : null),
+      pageContext,
+    });
+  }
+
+  return { pageContext, contextBlocks, renderBlocks };
+}
+
+module.exports = {
+  parseDurationToMs,
+  getDefaultTimeoutMs,
+  interpolateCtx,
+  resolvePageContext,
+};

package/src/services/pagesContextBlocksAi.service.js

@@ -0,0 +1,349 @@
+const llmService = require('./llm.service');
+const { resolveLlmProviderModel } = require('./llmDefaults.service');
+const { createAuditEvent } = require('./audit.service');
+
+const ALLOWED_BLOCK_TYPES = new Set(['context.db_query', 'context.service_invoke']);
+
+function parseJsonFromModelOutput(raw) {
+  const text = String(raw || '').trim();
+
+  try {
+    return JSON.parse(text);
+  } catch (_) {
+    const m = text.match(/```json\s*([\s\S]*?)\s*```/i) || text.match(/```\s*([\s\S]*?)\s*```/i);
+    if (m) {
+      return JSON.parse(String(m[1] || '').trim());
+    }
+
+    const idx = text.indexOf('{');
+    const last = text.lastIndexOf('}');
+    if (idx !== -1 && last !== -1 && last > idx) {
+      return JSON.parse(text.slice(idx, last + 1));
+    }
+
+    const err = new Error('AI response was not valid JSON');
+    err.code = 'AI_INVALID';
+    throw err;
+  }
+}
+
+function normalizeBlockType(v) {
+  return String(v || '').trim();
+}
+
+function validateProposalShape(obj) {
+  if (!obj || typeof obj !== 'object' || Array.isArray(obj)) {
+    const err = new Error('AI proposal must be a JSON object');
+    err.code = 'AI_INVALID';
+    throw err;
+  }
+
+  const type = normalizeBlockType(obj.type);
+  if (!ALLOWED_BLOCK_TYPES.has(type)) {
+    const err = new Error(`AI proposal type must be one of: ${Array.from(ALLOWED_BLOCK_TYPES).join(', ')}`);
+    err.code = 'AI_INVALID';
+    throw err;
+  }
+
+  const props = obj.props;
+  if (!props || typeof props !== 'object' || Array.isArray(props)) {
+    const err = new Error('AI proposal props must be an object');
+    err.code = 'AI_INVALID';
+    throw err;
+  }
+
+  if (props.cache !== undefined && props.cache !== null) {
+    if (typeof props.cache !== 'object' || Array.isArray(props.cache)) {
+      const err = new Error('AI proposal props.cache must be an object');
+      err.code = 'AI_INVALID';
+      throw err;
+    }
+    if (props.cache.ttlSeconds !== undefined && props.cache.ttlSeconds !== null) {
+      const n = Number(props.cache.ttlSeconds);
+      if (!Number.isFinite(n) || n < 0) {
+        const err = new Error('AI proposal props.cache.ttlSeconds must be a number >= 0');
+        err.code = 'AI_INVALID';
+        throw err;
+      }
+    }
+  }
+
+  if (props.timeout !== undefined && props.timeout !== null) {
+    if (typeof props.timeout !== 'object' || Array.isArray(props.timeout)) {
+      const err = new Error('AI proposal props.timeout must be an object');
+      err.code = 'AI_INVALID';
+      throw err;
+    }
+    if (props.timeout.value !== undefined && props.timeout.value !== null && typeof props.timeout.value !== 'string') {
+      const err = new Error('AI proposal props.timeout.value must be a string');
+      err.code = 'AI_INVALID';
+      throw err;
+    }
+  }
+
+  return { type, props };
+}
+
+function buildHelpersContextForPrompt() {
+  const sb = globalThis.superbackend || globalThis.saasbackend || null;
+  const services = (sb && sb.services) ? sb.services : {};
+  const models = (sb && sb.models) ? sb.models : {};
+
+  const denyServices = new Set(['globalSettings', 'migration', 'workflow']);
+
+  const serviceKeys = Object.keys(services || {}).filter((k) => !denyServices.has(k)).sort();
+  const modelKeys = Object.keys(models || {}).sort();
+
+  return {
+    denyServices: Array.from(denyServices),
+    serviceKeys,
+    modelKeys,
+  };
+}
+
+function capList(list, max) {
+  const arr = Array.isArray(list) ? list : [];
+  if (arr.length <= max) return arr;
+  return arr.slice(0, max);
+}
+
+function buildSystemPrompt({ helpersInfo }) {
+  const servicesPreview = capList(helpersInfo.serviceKeys, 80);
+  const modelsPreview = capList(helpersInfo.modelKeys, 80);
+
+  return [
+    'You are an assistant that outputs a single JSON object describing a Pages SSR Context Block.',
+    'Return ONLY JSON. No markdown, no extra keys, no explanation.',
+    '',
+    'Output schema:',
+    '{',
+    '  "type": "context.db_query|context.service_invoke",',
+    '  "props": { ... }',
+    '}',
+    '',
+    'Allowed type values: context.db_query, context.service_invoke',
+    '',
+    'Shared props patterns:',
+    '- "assignTo": string key for pageContext.vars (required)',
+    '- "cache": { "enabled": boolean, "namespace"?: string, "ttlSeconds"?: number, "key"?: any } (optional)',
+    '- "timeout": { "enabled": boolean, "value"?: "250ms"|"5s"|"1m" } (optional)',
+    '',
+    '$ctx interpolation:',
+    'You can reference runtime values inside props using a JSON object with a single key "$ctx".',
+    'Example: {"slug": {"$ctx": "params.slug"}}',
+    '',
+    'Allowed $ctx roots:',
+    '- params.* (repeat params like params.slug)',
+    '- query.* (req.query)',
+    '- auth.*',
+    '- session.*',
+    '- vars.* (results from previous context blocks)',
+    '- pageContext.*',
+    '',
+    'context.db_query props:',
+    '{',
+    '  "model": "MongooseModelName",',
+    '  "op": "find|findOne|countDocuments",',
+    '  "filter": { ... },',
+    '  "sort"?: { ... },',
+    '  "select"?: { ... },',
+    '  "limit"?: number,',
+    '  "assignTo": "post"',
+    '}',
+    '',
+    'context.service_invoke props:',
+    '{',
+    '  "servicePath": "services.someService.someFn" | "models.SomeModel.someStatic" | "mongoose.someFn",',
+    '  "args": [ ... ] | <any>,',
+    '  "assignTo": "result"',
+    '}',
+    '',
+    'Invokable helper namespaces:',
+    '- helpers.services.<serviceName>.*',
+    '- helpers.models.<ModelName>.*',
+    '- helpers.mongoose.*',
+    '',
+    `services available (preview): ${JSON.stringify(servicesPreview)}`,
+    `models available (preview): ${JSON.stringify(modelsPreview)}`,
+    `services denylist (cannot be referenced): ${JSON.stringify(helpersInfo.denyServices)}`,
+    '',
+    'Examples:',
+    '{"type":"context.db_query","props":{"model":"BlogPost","op":"findOne","filter":{"slug":{"$ctx":"params.slug"},"status":"published"},"assignTo":"post"}}',
+    '{"type":"context.db_query","props":{"model":"BlogPost","op":"find","filter":{"status":"published"},"sort":{"publishedAt":-1},"limit":10,"assignTo":"latestPosts","cache":{"enabled":true,"ttlSeconds":30,"key":{"$ctx":"params.slug"}}}}',
+    '{"type":"context.service_invoke","props":{"servicePath":"services.i18n.translate","args":[{"$ctx":"query.text"}],"assignTo":"t"}}',
+  ].join('\n');
+}
+
+function computeWarnings({ proposal }) {
+  const warnings = [];
+  const props = proposal?.props || {};
+
+  if (props.cache && props.cache.enabled && !Object.prototype.hasOwnProperty.call(props.cache, 'key')) {
+    warnings.push('Caching is enabled but props.cache.key is missing; key will be auto-derived (may be OK but can reduce cache hit rate).');
+  }
+
+  if (proposal?.type === 'context.db_query') {
+    const limit = props.limit;
+    const n = limit === undefined || limit === null ? null : Number(limit);
+    if (n !== null && Number.isFinite(n) && n > 200) {
+      warnings.push('db_query limit is > 200; consider lowering it to reduce SSR latency and payload size.');
+    }
+  }
+
+  if (proposal?.type === 'context.service_invoke') {
+    const sp = String(props.servicePath || '');
+    if (sp.startsWith('services.globalSettings') || sp.startsWith('services.migration') || sp.startsWith('services.workflow')) {
+      warnings.push('servicePath references a denylisted service namespace and will fail at runtime.');
+    }
+  }
+
+  return warnings;
+}
+
+async function resolveLlmDefaults({ systemKey, providerKey, model }) {
+  return resolveLlmProviderModel({ systemKey, providerKey, model });
+}
+
+async function generateContextBlock({ prompt, blockType, providerKey, model, actor }) {
+  const instruction = String(prompt || '').trim();
+  if (!instruction) {
+    const err = new Error('prompt is required');
+    err.code = 'VALIDATION';
+    throw err;
+  }
+
+  const type = normalizeBlockType(blockType);
+  if (!ALLOWED_BLOCK_TYPES.has(type)) {
+    const err = new Error(`blockType must be one of: ${Array.from(ALLOWED_BLOCK_TYPES).join(', ')}`);
+    err.code = 'VALIDATION';
+    throw err;
+  }
+
+  const helpersInfo = buildHelpersContextForPrompt();
+
+  const llmDefaults = await resolveLlmDefaults({
+    systemKey: 'pageBuilder.blocks.generate',
+    providerKey,
+    model,
+  });
+
+  const result = await llmService.callAdhoc(
+    {
+      providerKey: llmDefaults.providerKey,
+      model: llmDefaults.model,
+      messages: [
+        { role: 'system', content: buildSystemPrompt({ helpersInfo }) },
+        { role: 'user', content: `Block type: ${type}\nInstruction:\n${instruction}` },
+      ],
+      promptKeyForAudit: 'pages.contextBlocks.ai.generate',
+    },
+    { temperature: 0.2 },
+  );
+
+  const raw = String(result.content || '');
+  const json = parseJsonFromModelOutput(raw);
+  const proposal = validateProposalShape(json);
+
+  if (proposal.type !== type) {
+    const err = new Error('AI proposal type must match requested blockType');
+    err.code = 'AI_INVALID';
+    throw err;
+  }
+
+  const warnings = computeWarnings({ proposal });
+
+  await createAuditEvent({
+    ...(actor || { actorType: 'system', actorId: null }),
+    action: 'pages.contextBlocks.ai.generate',
+    entityType: 'PagesContextBlock',
+    entityId: proposal.type,
+    before: null,
+    after: { type: proposal.type },
+    meta: {
+      providerKey: llmDefaults.providerKey,
+      model: llmDefaults.model,
+      responsePreview: raw.slice(0, 4000),
+      warnings,
+    },
+  });
+
+  return {
+    proposal,
+    providerKey: llmDefaults.providerKey,
+    model: llmDefaults.model,
+    warnings,
+  };
+}
+
+async function proposeContextBlockEdit({ prompt, currentBlock, providerKey, model, actor }) {
+  const instruction = String(prompt || '').trim();
+  if (!instruction) {
+    const err = new Error('prompt is required');
+    err.code = 'VALIDATION';
+    throw err;
+  }
+
+  const current = validateProposalShape(currentBlock);
+
+  const helpersInfo = buildHelpersContextForPrompt();
+
+  const llmDefaults = await resolveLlmDefaults({
+    systemKey: 'pageBuilder.blocks.propose',
+    providerKey,
+    model,
+  });
+
+  const result = await llmService.callAdhoc(
+    {
+      providerKey: llmDefaults.providerKey,
+      model: llmDefaults.model,
+      messages: [
+        { role: 'system', content: buildSystemPrompt({ helpersInfo }) },
+        { role: 'user', content: `Instruction:\n${instruction}` },
+        { role: 'user', content: `Current block:\n${JSON.stringify(current, null, 2)}` },
+      ],
+      promptKeyForAudit: 'pages.contextBlocks.ai.propose',
+    },
+    { temperature: 0.2 },
+  );
+
+  const raw = String(result.content || '');
+  const json = parseJsonFromModelOutput(raw);
+  const proposal = validateProposalShape(json);
+
+  if (proposal.type !== current.type) {
+    const err = new Error('AI proposal type must match currentBlock type');
+    err.code = 'AI_INVALID';
+    throw err;
+  }
+
+  const warnings = computeWarnings({ proposal });
+
+  await createAuditEvent({
+    ...(actor || { actorType: 'system', actorId: null }),
+    action: 'pages.contextBlocks.ai.propose',
+    entityType: 'PagesContextBlock',
+    entityId: proposal.type,
+    before: { type: current.type },
+    after: { type: proposal.type },
+    meta: {
+      providerKey: llmDefaults.providerKey,
+      model: llmDefaults.model,
+      responsePreview: raw.slice(0, 4000),
+      warnings,
+    },
+  });
+
+  return {
+    currentBlock: current,
+    proposal,
+    providerKey: llmDefaults.providerKey,
+    model: llmDefaults.model,
+    warnings,
+  };
+}
+
+module.exports = {
+  generateContextBlock,
+  proposeContextBlockEdit,
+};