@forklaunch/core 2.1.1 → 3.0.0

package/bin/gateway-mock/routes/email.mjs

@@ -0,0 +1,233 @@
+/**
+ * Email: the platform's SES-backed email gateway (createEmailClient).
+ *
+ * Messages are recorded, never sent. Outcomes follow the SES mailbox
+ * simulator's spirit with addresses anyone can type:
+ *   - `bounce@<any>` or any address at `bounce.test`: a permanent bounce
+ *     (`email.bounced`), and the address joins the instance's suppression
+ *     list — GET /email/suppressions/:address answers true and a later send
+ *     to it is refused with 422;
+ *   - `complaint@<any>`: delivered, then a complaint (`email.delivered`,
+ *     `email.complained`), and the address is suppressed;
+ *   - anything else: `email.delivered`.
+ * Suppression is applied when the send is accepted; events are delivered
+ * just after the send answers, as SES reports them after accepting.
+ *
+ * Refusals, as the platform answers them: 400 for a malformed request, 422
+ * for a suppressed recipient, 429 (with retry-after) past the daily quota.
+ * The quota counts recipients, as SES does.
+ *
+ * Vendor route (unauthenticated): GET /__mock/email/messages[?to=address]
+ * lists what was "sent", with its from address and configuration set.
+ *
+ *   MOCK_EMAIL_DAILY_QUOTA     recipients per UTC day, default 200
+ *   MOCK_EMAIL_SENDING_DOMAIN  default mail.forklaunch.test; the from address
+ *                              is no-reply@<instance id>.<this>
+ *   MOCK_EMAIL_EVENT_DELAY_MS  wait before delivering events, default 0
+ */
+import { randomUUID } from 'node:crypto';
+
+const env = process.env;
+const DAILY_QUOTA = Number(env.MOCK_EMAIL_DAILY_QUOTA ?? 200);
+const SENDING_DOMAIN = env.MOCK_EMAIL_SENDING_DOMAIN ?? 'mail.forklaunch.test';
+const EVENT_DELAY_MS = Number(env.MOCK_EMAIL_EVENT_DELAY_MS ?? 0);
+
+const LIMITS = {
+  maxRecipients: 50,
+  maxSubjectLength: 998,
+  maxBodyBytes: 512 * 1024,
+  maxTags: 10
+};
+const ADDRESS =
+  /^[^\s@<>()[\]\\,;:"]+@[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)+$/;
+const TAG_PART = /^[A-Za-z0-9_-]{1,256}$/;
+
+const isAddress = (a) =>
+  typeof a === 'string' && a.length <= 254 && ADDRESS.test(a);
+const today = () => new Date().toISOString().slice(0, 10);
+const secondsToMidnight = () => {
+  const now = new Date();
+  const next = Date.UTC(
+    now.getUTCFullYear(),
+    now.getUTCMonth(),
+    now.getUTCDate() + 1
+  );
+  return Math.max(1, Math.ceil((next - now.getTime()) / 1000));
+};
+
+function outcome(address) {
+  const [local, domain] = address.toLowerCase().split('@');
+  if (local === 'bounce' || domain === 'bounce.test') return 'bounce';
+  if (local === 'complaint') return 'complaint';
+  return 'deliver';
+}
+
+function init(state) {
+  state.messages ??= [];
+  state.suppressed ??= new Map();
+  state.day ??= today();
+  state.sent ??= 0;
+  if (state.day !== today()) {
+    state.day = today();
+    state.sent = 0;
+  }
+  return state;
+}
+
+/** The gateway's validation: a message, or the reason it is refused. */
+function validate(body) {
+  const list = (v) =>
+    v === undefined ? undefined : Array.isArray(v) ? v : [v];
+  const to = list(body.to);
+  const replyTo = list(body.replyTo);
+  if (!to || to.length === 0) return 'to is required';
+  if (to.length > LIMITS.maxRecipients)
+    return `to has ${to.length} addresses; the limit is ${LIMITS.maxRecipients}`;
+  for (const a of [...to, ...(replyTo ?? [])]) {
+    if (!isAddress(a))
+      return `'${String(a).slice(0, 80)}' is not an email address`;
+  }
+  if (typeof body.subject !== 'string' || !body.subject.trim())
+    return 'subject is required';
+  if (/[\r\n]/.test(body.subject)) return 'subject must be one line';
+  if (body.subject.length > LIMITS.maxSubjectLength)
+    return 'subject is too long';
+  if (!body.text && !body.html) return 'text or html is required';
+  const bytes =
+    Buffer.byteLength(String(body.text ?? '')) +
+    Buffer.byteLength(String(body.html ?? ''));
+  if (bytes > LIMITS.maxBodyBytes)
+    return `body is ${bytes} bytes; the limit is ${LIMITS.maxBodyBytes}`;
+  const tags = body.tags ?? {};
+  if (typeof tags !== 'object' || Array.isArray(tags))
+    return 'tags must be an object';
+  if (Object.keys(tags).length > LIMITS.maxTags)
+    return `the limit is ${LIMITS.maxTags} tags`;
+  for (const [name, value] of Object.entries(tags)) {
+    if (!TAG_PART.test(name) || !TAG_PART.test(String(value)))
+      return `tag '${name}' is malformed`;
+    if (name.startsWith('fl-') || name.startsWith('ses:'))
+      return `tag '${name}' is reserved`;
+  }
+  return { to, replyTo, tags };
+}
+
+export default {
+  feature: 'email',
+  routes: [
+    {
+      method: 'POST',
+      path: '/email/send',
+      handler: (ctx) => {
+        const state = init(ctx.state);
+        const checked = validate(ctx.body);
+        if (typeof checked === 'string') return ctx.send(400, checked);
+        const { to, replyTo, tags } = checked;
+        const refused = to.filter((a) => state.suppressed.has(a.toLowerCase()));
+        if (refused.length) {
+          return ctx.send(
+            422,
+            `Suppressed after a bounce or complaint: ${refused.join(', ')}`
+          );
+        }
+        if (state.sent + to.length > DAILY_QUOTA) {
+          return ctx.send(
+            429,
+            `Daily email quota of ${DAILY_QUOTA} recipients is spent`,
+            { 'retry-after': String(secondsToMidnight()) }
+          );
+        }
+        state.sent += to.length;
+        const messageId = `mock-${randomUUID()}`;
+        const configurationSet = `fl-${ctx.instanceId}`;
+        state.messages.push({
+          messageId,
+          instanceId: ctx.instanceId,
+          configurationSet,
+          from: `no-reply@${ctx.instanceId}.${SENDING_DOMAIN}`,
+          to,
+          replyTo,
+          subject: ctx.body.subject,
+          text: ctx.body.text,
+          html: ctx.body.html,
+          tags,
+          at: new Date().toISOString()
+        });
+
+        // What SES will report, decided now so a follow-up call sees it.
+        const events = [];
+        const delivered = to.filter((a) => outcome(a) !== 'bounce');
+        const bounced = to.filter((a) => outcome(a) === 'bounce');
+        const complained = to.filter((a) => outcome(a) === 'complaint');
+        for (const a of bounced)
+          state.suppressed.set(a.toLowerCase(), 'bounce');
+        for (const a of complained)
+          state.suppressed.set(a.toLowerCase(), 'complaint');
+        const base = {
+          messageId,
+          ...(Object.keys(tags).length ? { tags } : {})
+        };
+        if (delivered.length)
+          events.push(['email.delivered', { ...base, recipients: delivered }]);
+        if (bounced.length) {
+          events.push([
+            'email.bounced',
+            {
+              ...base,
+              recipients: bounced,
+              bounceType: 'Permanent',
+              bounceSubType: 'General',
+              permanent: true
+            }
+          ]);
+        }
+        if (complained.length) {
+          events.push([
+            'email.complained',
+            { ...base, recipients: complained, feedbackType: 'abuse' }
+          ]);
+        }
+
+        ctx.send(200, { messageId });
+        setTimeout(async () => {
+          for (const [type, data] of events) await ctx.emit(type, data);
+        }, EVENT_DELAY_MS);
+      }
+    },
+    {
+      method: 'GET',
+      path: /^\/email\/suppressions\/(?<address>[^/]+)$/,
+      handler: (ctx) => {
+        const state = init(ctx.state);
+        const address = decodeURIComponent(ctx.params.address).toLowerCase();
+        if (!isAddress(address)) return ctx.send(400, 'Not an email address');
+        const reason = state.suppressed.get(address);
+        return ctx.send(200, {
+          address,
+          suppressed: Boolean(reason),
+          ...(reason ? { reason } : {})
+        });
+      }
+    }
+  ],
+  vendorRoutes: [
+    {
+      method: 'GET',
+      path: '/__mock/email/messages',
+      handler: (ctx) => {
+        const state = init(ctx.state);
+        const to = new URL(ctx.req.url ?? '/', 'http://mock').searchParams.get(
+          'to'
+        );
+        return ctx.send(
+          200,
+          to
+            ? state.messages.filter((m) =>
+                m.to.some((a) => a.toLowerCase() === to.toLowerCase())
+              )
+            : state.messages
+        );
+      }
+    }
+  ]
+};

package/bin/gateway-mock/routes/models.mjs

@@ -0,0 +1,192 @@
+/**
+ * Models: the model gateway (createModelGatewayClient) and, for platform
+ * developers, the Azure AI Foundry / Entra APIs behind it.
+ *
+ * Answers are `[mock <model>] <the last user message>`; token counts are
+ * words, so budgets move predictably.
+ *
+ *   MOCK_MODELS          comma-separated aliases, default sol,terra,luna
+ *   MOCK_MONTHLY_TOKENS  default 2000000
+ *   MOCK_FAIL_EVERY      answer 503 to every Nth completion (default off)
+ */
+import { randomUUID } from 'node:crypto';
+
+const env = process.env;
+const MODELS = (env.MOCK_MODELS ?? 'sol,terra,luna')
+  .split(',')
+  .map((m) => m.trim())
+  .filter(Boolean);
+const BUDGET = Number(env.MOCK_MONTHLY_TOKENS ?? 2_000_000);
+const FAIL_EVERY = Number(env.MOCK_FAIL_EVERY ?? 0);
+
+let tokensUsed = 0;
+let completions = 0;
+
+const words = (text) =>
+  String(text ?? '')
+    .split(/\s+/)
+    .filter(Boolean).length;
+
+function lastUserText(messages) {
+  const user = [...(messages ?? [])].reverse().find((m) => m?.role === 'user');
+  if (!user) return '';
+  if (typeof user.content === 'string') return user.content;
+  if (Array.isArray(user.content)) {
+    return user.content
+      .map((part) => (typeof part?.text === 'string' ? part.text : ''))
+      .join(' ');
+  }
+  return '';
+}
+
+function answer(body) {
+  const model = String(body.model ?? 'mock');
+  const content = `[mock ${model}] ${lastUserText(body.messages)}`.slice(0, 2000);
+  const usage = {
+    prompt_tokens: (body.messages ?? []).reduce(
+      (n, m) => n + words(typeof m?.content === 'string' ? m.content : ''),
+      0
+    ),
+    completion_tokens: words(content)
+  };
+  usage.total_tokens = usage.prompt_tokens + usage.completion_tokens;
+  return { model, content, usage };
+}
+
+function completion(body) {
+  const { model, content, usage } = answer(body);
+  return {
+    id: `chatcmpl-mock-${randomUUID()}`,
+    object: 'chat.completion',
+    created: Math.floor(Date.now() / 1000),
+    model,
+    choices: [
+      { index: 0, message: { role: 'assistant', content }, finish_reason: 'stop' }
+    ],
+    usage
+  };
+}
+
+function chunks(body) {
+  const { model, content, usage } = answer(body);
+  const base = {
+    id: `chatcmpl-mock-${randomUUID()}`,
+    object: 'chat.completion.chunk',
+    created: Math.floor(Date.now() / 1000),
+    model
+  };
+  const out = [{ ...base, choices: [{ index: 0, delta: { role: 'assistant' } }] }];
+  for (const word of content.split(/(?<= )/)) {
+    out.push({ ...base, choices: [{ index: 0, delta: { content: word } }] });
+  }
+  out.push({ ...base, choices: [{ index: 0, delta: {}, finish_reason: 'stop' }] });
+  if (body.stream_options?.include_usage !== false) {
+    out.push({ ...base, choices: [], usage });
+  }
+  out.push('[DONE]');
+  return out;
+}
+
+function failed(ctx) {
+  completions += 1;
+  if (FAIL_EVERY > 0 && completions % FAIL_EVERY === 0) {
+    ctx.send(503, 'Mock outage (MOCK_FAIL_EVERY)');
+    return true;
+  }
+  return false;
+}
+
+function completionRoute(streaming) {
+  return (ctx) => {
+    const { body } = ctx;
+    if (!MODELS.includes(body.model)) {
+      return ctx.send(403, `'${body.model}' is not enabled; allowed: ${MODELS.join(', ')}`);
+    }
+    if (!Array.isArray(body.messages) || body.messages.length === 0) {
+      return ctx.send(400, 'messages must be a non-empty array');
+    }
+    if (tokensUsed >= BUDGET) {
+      return ctx.send(429, `Monthly token budget of ${BUDGET} is spent`, {
+        'retry-after': '3600'
+      });
+    }
+    if (failed(ctx)) return;
+    tokensUsed += answer(body).usage.total_tokens;
+    const headers = {
+      'x-forklaunch-model': String(body.model),
+      'x-forklaunch-tokens-remaining': String(Math.max(0, BUDGET - tokensUsed))
+    };
+    if (streaming) return ctx.stream(chunks(body), headers, true);
+    if (body.stream === true) {
+      return ctx.send(
+        400,
+        'For streaming, POST /instance-gateway/models/chat/completions/stream'
+      );
+    }
+    return ctx.send(200, completion(body), headers);
+  };
+}
+
+export default {
+  feature: 'models',
+  reset() {
+    tokensUsed = 0;
+    completions = 0;
+  },
+  routes: [
+    {
+      method: 'GET',
+      path: '/models',
+      handler: (ctx) =>
+        ctx.send(200, {
+          models: MODELS.map((id) => ({ id, baa: true })),
+          monthlyTokenBudget: BUDGET,
+          tokensUsedThisMonth: tokensUsed,
+          requestsPerMinute: 600
+        })
+    },
+    { method: 'POST', path: '/models/chat/completions', handler: completionRoute(false) },
+    {
+      method: 'POST',
+      path: '/models/chat/completions/stream',
+      handler: completionRoute(true)
+    }
+  ],
+  vendorRoutes: [
+    // The Foundry (Azure OpenAI v1) API.
+    {
+      method: 'POST',
+      path: /\/v1\/chat\/completions$/,
+      handler: (ctx) => {
+        if (!ctx.req.headers.authorization?.startsWith('Bearer ')) {
+          return ctx.send(401, { error: { message: 'Missing bearer credential' } });
+        }
+        if (failed(ctx)) return;
+        return ctx.body.stream === true
+          ? ctx.stream(chunks(ctx.body))
+          : ctx.send(200, completion(ctx.body));
+      }
+    },
+    // An Entra token endpoint.
+    {
+      method: 'POST',
+      path: /\/oauth2\/v2\.0\/token$/,
+      handler: (ctx) => {
+        const form = new URLSearchParams(ctx.raw);
+        if (
+          !form.get('client_id') ||
+          !(form.get('client_secret') || form.get('client_assertion'))
+        ) {
+          return ctx.send(401, {
+            error_description: 'AADSTS7000215: mock requires a secret or an assertion'
+          });
+        }
+        return ctx.send(200, {
+          token_type: 'Bearer',
+          expires_in: 3600,
+          access_token: `mock-entra-token-${randomUUID()}`
+        });
+      }
+    }
+  ]
+};