arcway 0.4.20 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcway",
-  "version": "0.4.20",
+  "version": "0.5.0",
   "description": "A convention-based framework for building modular monoliths with strict domain boundaries.",
   "license": "MIT",
   "type": "module",

package/server/bin/cli.js

@@ -13,6 +13,7 @@ import registerSchema from './commands/schema.js';
 import registerMigrate from './commands/migrate.js';
 import registerBootstrap from './commands/bootstrap.js';
 import registerVault from './commands/vault.js';
+import registerEnv from './commands/env.js';
 
 function getPackageVersion() {
   try {
@@ -40,6 +41,7 @@ function createProgram() {
   registerMigrate(program);
   registerBootstrap(program);
   registerVault(program);
+  registerEnv(program);
   return program;
 }
 

package/server/bin/commands/env.js

@@ -0,0 +1,30 @@
+import { makeConfig } from '#server/config/loader.js';
+import { loadEnvFiles } from '#server/env.js';
+
+async function runEnvCheck(options = {}) {
+  const rootDir = process.cwd();
+  const mode =
+    options.mode ?? (process.env.NODE_ENV === 'production' ? 'production' : 'development');
+  loadEnvFiles(rootDir, mode);
+  await makeConfig(rootDir, { mode });
+  console.log(`Environment is valid for ${mode}.`);
+}
+
+function register(program) {
+  const env = program.command('env').description('Environment declaration utilities');
+  env
+    .command('check')
+    .description('Validate declared environment variables without starting the application')
+    .option('--mode <mode>', 'configuration mode')
+    .action(async (options) => {
+      try {
+        await runEnvCheck(options);
+      } catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+      }
+    });
+}
+
+export { runEnvCheck };
+export default register;

package/server/bin/solo.js

@@ -1,4 +1,9 @@
 #!/usr/bin/env node
 import { createProgram } from './cli.js';
 const program = createProgram();
-program.parse(process.argv);
+try {
+  await program.parseAsync(process.argv);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+}

package/server/boot/index.js

@@ -56,6 +56,8 @@ async function boot(options) {
   // the init hook (e.g. wrapping `appContext.db`) persist for process lifetime
   // because downstream consumers read properties off this reference at use time.
   const appContext = {
+    config,
+    env: config.env,
     db,
     redis,
     events,
@@ -112,6 +114,7 @@ async function boot(options) {
     workerPool,
     plugins,
     appConfig: config,
+    env: config.env,
   });
   await jobRunner.init();
 
@@ -140,6 +143,7 @@ async function boot(options) {
   const healthDeps = {
     db,
     redisClients: [{ name: 'redis', client: redis?.client }],
+    mail,
   };
   const callbackHandlers = await discoverRootCallbacks(rootDir);
   const pluginCallbacks = (await plugins.discoverCallbacks?.()) ?? new Map();

package/server/config/loader.js

@@ -20,6 +20,7 @@ import resolveMcp from './modules/mcp.js';
 import resolveWebsocket from './modules/websocket.js';
 import resolveSeeds from './modules/seeds.js';
 import resolvePlugins from './modules/plugins.js';
+import resolveEnv from './modules/env.js';
 
 function deepMerge(target, source) {
   const result = { ...target };
@@ -40,6 +41,7 @@ function deepMerge(target, source) {
 }
 
 const modules = [
+  resolveEnv,
   resolveServer,
   resolveApi,
   resolveDatabase,

package/server/config/modules/env.js

@@ -0,0 +1,68 @@
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function describe(name, declaration, issue) {
+  return declaration?.description
+    ? `${name}: ${declaration.description} — ${issue}`
+    : `${name}: ${issue}`;
+}
+
+function resolve(config, { mode } = {}) {
+  if (config.env === undefined) return { ...config, env: Object.freeze({}) };
+  if (!isPlainObject(config.env)) {
+    throw new Error('Invalid environment configuration:\nenv: must be an object');
+  }
+
+  const errors = [];
+  const resolved = {};
+  for (const [name, declaration] of Object.entries(config.env)) {
+    if (!isPlainObject(declaration)) {
+      errors.push(`${name}: declaration must be an object`);
+      continue;
+    }
+
+    const { required, default: defaultValue, values, description } = declaration;
+    const requiredValid =
+      required === undefined ||
+      typeof required === 'boolean' ||
+      (Array.isArray(required) && required.every((value) => typeof value === 'string'));
+    if (!requiredValid)
+      errors.push(
+        describe(name, declaration, 'required must be true, false, or an array of modes'),
+      );
+    if (description !== undefined && typeof description !== 'string') {
+      errors.push(`${name}: description must be a string`);
+    }
+    if (
+      values !== undefined &&
+      (!Array.isArray(values) || !values.every((value) => typeof value === 'string'))
+    ) {
+      errors.push(describe(name, declaration, 'values must be an array of strings'));
+    }
+
+    const isRequired = required === true || (Array.isArray(required) && required.includes(mode));
+    if (required && defaultValue !== undefined) {
+      errors.push(describe(name, declaration, 'required variables cannot declare a default'));
+    }
+
+    let value = process.env[name];
+    if (value === undefined && !required && defaultValue !== undefined) {
+      value = String(defaultValue);
+      process.env[name] = value;
+    }
+    if (value === undefined && isRequired) {
+      errors.push(describe(name, declaration, 'is required'));
+    } else if (value !== undefined && Array.isArray(values) && !values.includes(value)) {
+      errors.push(describe(name, declaration, `has invalid value ${JSON.stringify(value)}`));
+    }
+    resolved[name] = value;
+  }
+
+  if (errors.length > 0) {
+    throw new Error(`Invalid environment configuration:\n${errors.join('\n')}`);
+  }
+  return { ...config, env: Object.freeze(resolved) };
+}
+
+export default resolve;

package/server/config/modules/mail.js

@@ -4,6 +4,8 @@ import { normalizePort } from '../port.js';
 const DEFAULTS = {
   driver: 'console',
   enabled: true,
+  maxAttempts: 5,
+  backoffMs: [60e3, 300e3, 1800e3, 7200e3, 21600e3],
 };
 
 function resolve(config) {

package/server/context.js

@@ -140,6 +140,8 @@ function buildContext(appContext, extras) {
         }
       : null;
   const ctx = {
+    config: appContext.config,
+    env: appContext.env,
     db: tracked.db,
     log: appContext.log,
     events: appContext.events,

package/server/health.js

@@ -28,6 +28,15 @@ async function checkHealth(deps) {
       }
     }
   }
+  if (deps.mail?.enabled) {
+    try {
+      const stats = await deps.mail.stats();
+      const failed = stats.failed ?? 0;
+      components.mail = { status: failed > 0 ? 'error' : 'ok', failed };
+    } catch (err) {
+      components.mail = { status: 'error', failed: null, error: toErrorMessage(err) };
+    }
+  }
   const allOk = Object.values(components).every((c) => c.status === 'ok');
   return { status: allOk ? 'ok' : 'degraded', components };
 }

package/server/jobs/runner.js

@@ -66,6 +66,7 @@ class JobRunner {
       workerPool,
       plugins,
       appConfig,
+      env,
     } = {},
   ) {
     this._config = config;
@@ -88,6 +89,8 @@ class JobRunner {
       vault,
       callbacks,
       plugins,
+      config: this._appConfig,
+      env,
     };
   }
 

package/server/jobs/worker-entry.js

@@ -79,7 +79,14 @@ async function runTask(task) {
       secret: resolvedConfig?.vault?.values?.callback,
     });
     const ctx = buildContext(
-      { ...services, meta: workerData?.meta, vault: resolvedConfig?.vault, callbacks },
+      {
+        ...services,
+        config: resolvedConfig,
+        env: resolvedConfig?.env,
+        meta: workerData?.meta,
+        vault: resolvedConfig?.vault,
+        callbacks,
+      },
       { payload },
     );
     return fn(ctx);

package/server/mail/index.js

@@ -3,6 +3,7 @@ import { addSystemJobEntry } from '../system-jobs/index.js';
 import ConsoleMailDriver from './drivers/console.js';
 import SmtpMailDriver from './drivers/smtp.js';
 import { initInboundMail } from './inbound.js';
+import { toErrorMessage } from '../helpers.js';
 
 const MAIL_JOB_NAME = 'send-mail';
 const MAIL_JOB_QUALIFIED = `${SYSTEM_JOB_DOMAIN}/${MAIL_JOB_NAME}`;
@@ -25,7 +26,7 @@ class Mail {
 
     if (this._enabled) {
       this._driver = createDriver(config);
-      registerSendJob(this._driver, queue, config.throughput);
+      registerSendJob(this._driver, queue, config, log);
       log?.info(`Mail driver: ${config.driver}`);
     } else if (config) {
       log?.info('Mail: disabled');
@@ -69,6 +70,23 @@ class Mail {
     await initInboundMail(this._db, this._config.inbound, this._log, onEmail);
     this._log?.info(`Mail inbound: ${this._config.inbound.driver}`);
   }
+
+  async pending(options) {
+    return this._queue?.list(MAIL_TOPIC, { ...options, status: 'available' }) ?? [];
+  }
+
+  async failed(options) {
+    return this._queue?.list(MAIL_TOPIC, { ...options, status: 'failed' }) ?? [];
+  }
+
+  async retry(ids) {
+    if (!this._queue) throw new Error('Cannot retry mail: queue is not available.');
+    await this._queue.retry(ids);
+  }
+
+  async stats() {
+    return this._queue?.count(MAIL_TOPIC) ?? {};
+  }
 }
 
 function createDriver(config) {
@@ -86,7 +104,16 @@ function createDriver(config) {
   }
 }
 
-function registerSendJob(driver, queue, throughput) {
+function recipientDomain(to) {
+  const recipient = Array.isArray(to) ? to[0] : to;
+  return typeof recipient === 'string' && recipient.includes('@')
+    ? recipient.slice(recipient.lastIndexOf('@') + 1).toLowerCase()
+    : 'unknown';
+}
+
+function registerSendJob(driver, queue, config, log) {
+  const maxAttempts = config.maxAttempts ?? 5;
+  const backoffMs = config.backoffMs ?? [60e3, 300e3, 1800e3, 7200e3, 21600e3];
   addSystemJobEntry({
     definition: {
       name: MAIL_JOB_NAME,
@@ -96,11 +123,28 @@ function registerSendJob(driver, queue, throughput) {
         if (!queue) return;
         const items = await queue.pop(MAIL_TOPIC, 10);
         for (const item of items) {
-          await driver.send(item.data);
-          await queue.remove([item.id]);
+          try {
+            await driver.send(item.data);
+            await queue.remove([item.id]);
+          } catch (error) {
+            const message = toErrorMessage(error);
+            const details = {
+              messageId: item.id,
+              recipientDomain: recipientDomain(item.data.to),
+              attempt: item.attempts,
+              error: message,
+            };
+            log?.error('Queued mail delivery failed', details);
+            if (item.attempts >= maxAttempts) {
+              await queue.fail([item.id], { error: message });
+            } else {
+              const retryInMs = backoffMs[Math.min(item.attempts - 1, backoffMs.length - 1)];
+              await queue.release([item.id], { error: message, retryInMs });
+            }
+          }
         }
       },
-      throughput,
+      throughput: config.throughput,
     },
     shouldRegister: (config) => !!config.mail,
     description: 'Send queued outbound email',

package/server/queue/drivers/knex.js

@@ -21,10 +21,30 @@ class KnexQueueDriver {
         table.string('topic').notNullable().index();
         table.text('payload').notNullable();
         table.string('status').notNullable().defaultTo('available');
+        table.integer('attempts').notNullable().defaultTo(0);
+        table.timestamp('available_at').notNullable().defaultTo(this.db.fn.now());
+        table.text('last_error').nullable();
         table.timestamp('locked_at').nullable();
         table.timestamp('created_at').defaultTo(this.db.fn.now());
       });
+      return;
     }
+    const additions = [
+      ['attempts', (table) => table.integer('attempts').notNullable().defaultTo(0)],
+      // SQLite cannot add a column with a non-constant CURRENT_TIMESTAMP
+      // default. Backfill it below after adding a nullable column; newly
+      // created tables still get the non-null default above.
+      ['available_at', (table) => table.timestamp('available_at').nullable()],
+      ['last_error', (table) => table.text('last_error').nullable()],
+    ];
+    for (const [column, add] of additions) {
+      if (!(await this.db.schema.hasColumn(this.tableName, column))) {
+        await this.db.schema.alterTable(this.tableName, add);
+      }
+    }
+    await this.db(this.tableName)
+      .whereNull('available_at')
+      .update({ available_at: this.db.fn.now() });
   }
   async push(namespace, topic, payload) {
     await this.db(this.tableName).insert({
@@ -32,6 +52,8 @@ class KnexQueueDriver {
       topic,
       payload,
       status: 'available',
+      attempts: 0,
+      available_at: toDatabaseTimestamp(this.db, Date.now()),
     });
   }
   async pushBulk(namespace, topic, payloads) {
@@ -40,6 +62,8 @@ class KnexQueueDriver {
       topic,
       payload,
       status: 'available',
+      attempts: 0,
+      available_at: toDatabaseTimestamp(this.db, Date.now()),
     }));
     await this.db(this.tableName).insert(rows);
   }
@@ -51,13 +75,15 @@ class KnexQueueDriver {
         .where('namespace', namespace)
         .andWhere('topic', topic)
         .andWhere(function () {
-          this.where('status', 'available').orWhere(function () {
+          this.where(function () {
+            this.where('status', 'available').andWhere('available_at', '<=', now);
+          }).orWhere(function () {
             this.where('status', 'locked').andWhere('locked_at', '<', cutoff);
           });
         })
         .orderBy('id', 'asc')
         .limit(count)
-        .select('id', 'payload');
+        .select('id', 'payload', 'attempts', 'last_error');
       const client = trx.client.config.client;
       if (client === 'mysql' || client === 'mysql2' || client === 'pg') {
         readyQuery = readyQuery.forUpdate().skipLocked();
@@ -70,13 +96,69 @@ class KnexQueueDriver {
           'id',
           rows.map((row) => row.id),
         )
-        .update({ status: 'locked', locked_at: now });
-      return rows.map((row) => ({ id: row.id, payload: row.payload }));
+        .update({
+          status: 'locked',
+          locked_at: now,
+          attempts: trx.raw('?? + 1', ['attempts']),
+        });
+      return rows.map((row) => ({
+        id: row.id,
+        payload: row.payload,
+        attempts: Number(row.attempts) + 1,
+        lastError: row.last_error,
+      }));
     });
   }
   async remove(namespace, ids) {
     if (ids.length === 0) return;
     await this.db(this.tableName).where('namespace', namespace).whereIn('id', ids).delete();
   }
+  async release(namespace, ids, { error, retryInMs = 0 } = {}) {
+    if (ids.length === 0) return;
+    await this.db(this.tableName)
+      .where({ namespace })
+      .whereIn('id', ids)
+      .update({
+        status: 'available',
+        locked_at: null,
+        available_at: toDatabaseTimestamp(this.db, Date.now() + retryInMs),
+        last_error: error ?? null,
+      });
+  }
+  async fail(namespace, ids, { error } = {}) {
+    if (ids.length === 0) return;
+    await this.db(this.tableName)
+      .where({ namespace })
+      .whereIn('id', ids)
+      .update({ status: 'failed', locked_at: null, last_error: error ?? null });
+  }
+  async retry(namespace, ids) {
+    if (ids.length === 0) return;
+    await this.db(this.tableName)
+      .where({ namespace, status: 'failed' })
+      .whereIn('id', ids)
+      .update({
+        status: 'available',
+        attempts: 0,
+        available_at: toDatabaseTimestamp(this.db, Date.now()),
+        last_error: null,
+      });
+  }
+  async list(namespace, topic, { status, limit = 100 } = {}) {
+    const query = this.db(this.tableName)
+      .where({ namespace, topic })
+      .orderBy('id', 'asc')
+      .limit(limit);
+    if (status) query.andWhere({ status });
+    return query.select('id', 'payload', 'status', 'attempts', 'available_at', 'last_error');
+  }
+  async count(namespace, topic) {
+    const rows = await this.db(this.tableName)
+      .where({ namespace, topic })
+      .groupBy('status')
+      .select('status')
+      .count({ count: '*' });
+    return Object.fromEntries(rows.map((row) => [row.status, Number(row.count)]));
+  }
 }
 export default KnexQueueDriver;

package/server/queue/drivers/redis.js

@@ -1,19 +1,26 @@
 import { REDIS_SCAN_COUNT } from '../../constants.js';
+
 const REQUEUE_EXPIRED_LUA = `
   local expired = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1])
-  for i, member in ipairs(expired) do
-    redis.call('LPUSH', KEYS[2], member)
+  for _, member in ipairs(expired) do
+    redis.call('ZADD', KEYS[2], ARGV[1], member)
     redis.call('ZREM', KEYS[1], member)
   end
   return #expired
 `;
+
 const POP_AND_LOCK_LUA = `
-  local raw = redis.call('LPOP', KEYS[1])
-  if raw then
-    redis.call('ZADD', KEYS[2], ARGV[1], raw)
-  end
-  return raw
+  local rows = redis.call('ZRANGEBYSCORE', KEYS[1], '-inf', ARGV[1], 'LIMIT', 0, 1)
+  if #rows == 0 then return nil end
+  local raw = rows[1]
+  redis.call('ZREM', KEYS[1], raw)
+  local item = cjson.decode(raw)
+  item.attempts = (item.attempts or 0) + 1
+  local updated = cjson.encode(item)
+  redis.call('ZADD', KEYS[2], ARGV[1], updated)
+  return updated
 `;
+
 class RedisQueueDriver {
   client;
   prefix;
@@ -21,66 +28,167 @@ class RedisQueueDriver {
     this.client = client;
     this.prefix = `${keyPrefix}queue:`;
   }
-  listKey(namespace, topic) {
-    return `${this.prefix}${namespace}:${topic}`;
+  availableKey(namespace, topic) {
+    return `${this.prefix}${namespace}:${topic}:available`;
   }
   lockedKey(namespace, topic) {
     return `${this.prefix}${namespace}:${topic}:locked`;
   }
+  failedKey(namespace, topic) {
+    return `${this.prefix}${namespace}:${topic}:failed`;
+  }
   idKey() {
     return `${this.prefix}id`;
   }
   async init() {}
 
+  item(id, payload, availableAt = Date.now()) {
+    return JSON.stringify({ id, payload, attempts: 0, availableAt, lastError: null });
+  }
   async push(namespace, topic, payload) {
     const id = await this.client.incr(this.idKey());
-    const item = JSON.stringify({ id, payload });
-    await this.client.rpush(this.listKey(namespace, topic), item);
+    const availableAt = Date.now();
+    await this.client.zadd(
+      this.availableKey(namespace, topic),
+      availableAt,
+      this.item(id, payload, availableAt),
+    );
   }
   async pushBulk(namespace, topic, payloads) {
-    const listKey = this.listKey(namespace, topic);
-    const idKey = this.idKey();
-    const startId = await this.client.incrby(idKey, payloads.length);
-    const items = payloads.map((payload, i) => {
-      const id = startId - payloads.length + 1 + i;
-      return JSON.stringify({ id, payload });
-    });
-    await this.client.rpush(listKey, ...items);
+    if (payloads.length === 0) return;
+    const startId = await this.client.incrby(this.idKey(), payloads.length);
+    const availableAt = Date.now();
+    const values = payloads.flatMap((payload, index) => [
+      availableAt,
+      this.item(startId - payloads.length + 1 + index, payload, availableAt),
+    ]);
+    await this.client.zadd(this.availableKey(namespace, topic), ...values);
   }
   async pop(namespace, topic, count, lockCooldownMs) {
     const results = [];
-    const listKey = this.listKey(namespace, topic);
+    const availableKey = this.availableKey(namespace, topic);
     const lockedKey = this.lockedKey(namespace, topic);
     const now = Date.now();
-    const cutoff = now - lockCooldownMs;
-    await this.client.eval(REQUEUE_EXPIRED_LUA, 2, lockedKey, listKey, cutoff.toString());
-    for (let i = 0; i < count; i++) {
-      const raw = await this.client.eval(POP_AND_LOCK_LUA, 2, listKey, lockedKey, now.toString());
+    await this.client.eval(
+      REQUEUE_EXPIRED_LUA,
+      2,
+      lockedKey,
+      availableKey,
+      String(now - lockCooldownMs),
+    );
+    for (let index = 0; index < count; index++) {
+      const raw = await this.client.eval(POP_AND_LOCK_LUA, 2, availableKey, lockedKey, String(now));
       if (!raw) break;
-      const parsed = JSON.parse(raw);
-      results.push({ id: parsed.id, payload: parsed.payload });
+      const item = JSON.parse(raw);
+      results.push(item);
     }
     return results;
   }
+  async findLocked(namespace, ids) {
+    const idSet = new Set(ids.map(Number));
+    const keys = await this.scanKeys(`${this.prefix}${namespace}:*:locked`);
+    const matches = [];
+    for (const key of keys) {
+      const members = await this.client.zrange(key, 0, -1);
+      for (const raw of members) {
+        const item = JSON.parse(raw);
+        if (idSet.has(Number(item.id))) matches.push({ key, raw, item });
+      }
+    }
+    return matches;
+  }
   async remove(namespace, ids) {
     if (ids.length === 0) return;
-    const idSet = new Set(ids);
-    const pattern = `${this.prefix}${namespace}:*:locked`;
-    const keys = await this.scanKeys(pattern);
-    for (const lockedKey of keys) {
-      const members = await this.client.zrange(lockedKey, 0, -1);
-      for (const member of members) {
-        try {
-          const parsed = JSON.parse(member);
-          if (idSet.has(parsed.id)) {
-            await this.client.zrem(lockedKey, member);
-          }
-        } catch {
-            // Malformed locked member — skip removal
-          }
+    for (const { key, raw } of await this.findLocked(namespace, ids)) {
+      await this.client.zrem(key, raw);
+    }
+  }
+  async release(namespace, ids, { error, retryInMs = 0 } = {}) {
+    for (const { key, raw, item } of await this.findLocked(namespace, ids)) {
+      const availableKey = key.replace(/:locked$/, ':available');
+      const availableAt = Date.now() + retryInMs;
+      await this.client.zrem(key, raw);
+      await this.client.zadd(
+        availableKey,
+        availableAt,
+        JSON.stringify({ ...item, availableAt, lastError: error ?? null }),
+      );
+    }
+  }
+  async fail(namespace, ids, { error } = {}) {
+    for (const { key, raw, item } of await this.findLocked(namespace, ids)) {
+      const failedKey = key.replace(/:locked$/, ':failed');
+      await this.client.zrem(key, raw);
+      await this.client.hset(
+        failedKey,
+        String(item.id),
+        JSON.stringify({ ...item, status: 'failed', lastError: error ?? null }),
+      );
+    }
+  }
+  async retry(namespace, ids) {
+    const idSet = new Set(ids.map(Number));
+    const keys = await this.scanKeys(`${this.prefix}${namespace}:*:failed`);
+    for (const key of keys) {
+      const values = await this.client.hgetall(key);
+      for (const [id, raw] of Object.entries(values)) {
+        if (!idSet.has(Number(id))) continue;
+        const item = JSON.parse(raw);
+        await this.client.hdel(key, id);
+        const availableAt = Date.now();
+        await this.client.zadd(
+          key.replace(/:failed$/, ':available'),
+          availableAt,
+          JSON.stringify({
+            ...item,
+            status: undefined,
+            attempts: 0,
+            availableAt,
+            lastError: null,
+          }),
+        );
       }
     }
   }
+  async list(namespace, topic, { status, limit = 100 } = {}) {
+    const statuses = status ? [status] : ['available', 'locked', 'failed'];
+    const rows = [];
+    for (const current of statuses) {
+      let values;
+      if (current === 'failed') {
+        values = Object.values(await this.client.hgetall(this.failedKey(namespace, topic)));
+      } else {
+        const scored = await this.client.zrange(
+          current === 'locked'
+            ? this.lockedKey(namespace, topic)
+            : this.availableKey(namespace, topic),
+          0,
+          limit - 1,
+          'WITHSCORES',
+        );
+        values = [];
+        for (let index = 0; index < scored.length; index += 2) {
+          const item = JSON.parse(scored[index]);
+          values.push(
+            JSON.stringify({
+              ...item,
+              availableAt: current === 'available' ? Number(scored[index + 1]) : item.availableAt,
+            }),
+          );
+        }
+      }
+      rows.push(...values.map((raw) => ({ ...JSON.parse(raw), status: current })));
+    }
+    return rows.sort((a, b) => Number(a.id) - Number(b.id)).slice(0, limit);
+  }
+  async count(namespace, topic) {
+    const [available, locked, failed] = await Promise.all([
+      this.client.zcard(this.availableKey(namespace, topic)),
+      this.client.zcard(this.lockedKey(namespace, topic)),
+      this.client.hlen(this.failedKey(namespace, topic)),
+    ]);
+    return { available, locked, failed };
+  }
   async scanKeys(pattern) {
     const keys = [];
     let cursor = '0';

package/server/queue/index.js

@@ -45,7 +45,7 @@ class Queue {
         this._log?.warn('Queue pop: corrupt JSON payload, using raw string', { id: r.id });
         data = r.payload;
       }
-      return { id: r.id, data };
+      return { id: r.id, data, attempts: r.attempts ?? 0, lastError: r.lastError ?? null };
     });
   }
 
@@ -53,6 +53,34 @@ class Queue {
     await this._driver.remove(this._namespace, ids);
   }
 
+  async release(ids, options) {
+    await this._driver.release(this._namespace, ids, options);
+  }
+
+  async fail(ids, options) {
+    await this._driver.fail(this._namespace, ids, options);
+  }
+
+  async retry(ids) {
+    await this._driver.retry(this._namespace, ids);
+  }
+
+  async list(topic, options) {
+    const rows = await this._driver.list(this._namespace, topic, options);
+    return rows.map((row) => ({
+      id: row.id,
+      data: JSON.parse(row.payload),
+      status: row.status,
+      attempts: Number(row.attempts ?? 0),
+      availableAt: row.available_at ?? row.availableAt ?? null,
+      lastError: row.last_error ?? row.lastError ?? null,
+    }));
+  }
+
+  async count(topic) {
+    return this._driver.count(this._namespace, topic);
+  }
+
   /** Return a namespaced child that shares the same driver. */
   withNamespace(namespace) {
     const child = Object.create(Queue.prototype);

package/server/rate-limit/index.js

@@ -1,4 +1,5 @@
 import { ErrorCodes } from '../constants.js';
+import { resolveRateLimitKey } from '../router/ratelimit-key.js';
 function defaultKeyFn(req) {
   const forwarded = req.headers['x-forwarded-for'];
   if (forwarded) return forwarded.split(',')[0].trim();
@@ -9,8 +10,9 @@ function createRateLimitMiddleware(options, store) {
   const windowMs = options.windowMs ?? 60000;
   const keyFn = options.keyFn ?? defaultKeyFn;
   return async (ctx) => {
-    const key = keyFn(ctx.req);
-    const result = await store.check(key, max, windowMs);
+    const resolved = resolveRateLimitKey({ _by: keyFn }, ctx.req);
+    if (!resolved) return;
+    const result = await store.check(resolved.value, max, windowMs);
     if (!result.allowed) {
       const resetTimestamp = Math.ceil((Date.now() + result.resetMs) / 1e3);
       const retryAfterSec = Math.ceil(result.resetMs / 1e3);

package/server/router/api-router.js

@@ -154,7 +154,7 @@ class ApiRouter {
 
   async executeRoute(route, reqInfo) {
     if (route.config._parsedRateLimit && this._redis) {
-      const checked = await checkRouteRateLimits(this._redis.client, route.config, reqInfo.ip);
+      const checked = await checkRouteRateLimits(this._redis.client, route.config, reqInfo);
       if (!checked.allowed) {
         const { policy, result } = checked.selected;
         const retryAfter = Math.max(1, result.resetAt - Math.ceil(Date.now() / 1000));
@@ -274,9 +274,16 @@ class ApiRouter {
 
     // ── Rate limiting ──
     if (route.config._parsedRateLimit && this._redis) {
-      const checked = await checkRouteRateLimits(this._redis.client, route.config, ip);
-      const { policy, result } = checked.selected;
+      const checked = await checkRouteRateLimits(this._redis.client, route.config, {
+        ip,
+        query: req.query ?? {},
+        params,
+        body: req.body,
+        session: req.session,
+        headers: req.flatHeaders ?? flattenHeaders(req.headers),
+      });
       if (!checked.allowed) {
+        const { policy, result } = checked.selected;
         const retryAfter = Math.max(1, result.resetAt - Math.ceil(Date.now() / 1000));
         sendJson(
           res,
@@ -296,9 +303,12 @@ class ApiRouter {
         );
         return true;
       }
-      res.setHeader('X-RateLimit-Limit', String(policy.max));
-      res.setHeader('X-RateLimit-Remaining', String(result.remaining));
-      res.setHeader('X-RateLimit-Reset', String(result.resetAt));
+      if (checked.selected) {
+        const { policy, result } = checked.selected;
+        res.setHeader('X-RateLimit-Limit', String(policy.max));
+        res.setHeader('X-RateLimit-Remaining', String(result.remaining));
+        res.setHeader('X-RateLimit-Reset', String(result.resetAt));
+      }
     }
 
     // ── Body parsing control ──

package/server/router/ratelimit-key.js

@@ -0,0 +1,39 @@
+import { createHash } from 'node:crypto';
+
+const RATE_LIMIT_ROOTS = new Set(['body', 'query', 'params', 'session', 'headers']);
+
+function hashRateLimitValue(value) {
+  return createHash('sha256').update(value.trim().toLowerCase()).digest('hex').slice(0, 32);
+}
+
+function isValidRateLimitBy(by) {
+  if (typeof by === 'function' || by === 'ip') return true;
+  if (typeof by !== 'string') return false;
+  const [root, ...segments] = by.split('.');
+  return RATE_LIMIT_ROOTS.has(root) && segments.length > 0 && segments.every(Boolean);
+}
+
+function readPath(req, path) {
+  const [root, ...segments] = path.split('.');
+  let value = req[root];
+  for (const segment of segments) {
+    if (value == null || typeof value !== 'object') return null;
+    value = value[segment];
+  }
+  return value;
+}
+
+function resolveRateLimitKey(policy, req) {
+  const by = policy._by ?? 'ip';
+  if (by === 'ip') return { scope: 'ip', value: req.ip ?? 'unknown' };
+  const raw = typeof by === 'function' ? by(req) : readPath(req, by);
+  if (raw == null) return null;
+  const value = String(raw).trim();
+  if (!value) return null;
+  return {
+    scope: typeof by === 'function' ? 'custom' : by,
+    value: hashRateLimitValue(value),
+  };
+}
+
+export { hashRateLimitValue, isValidRateLimitBy, resolveRateLimitKey };

package/server/router/ratelimit.js

@@ -38,8 +38,8 @@ local ttl = redis.call('TTL', KEYS[1])
 return {count, ttl}
 `;
 
-async function checkRateLimit(redisClient, { key, ip, max, windowSec }) {
-  const redisKey = `rl:${key}:${windowSec}:${ip}`;
+async function checkRateLimit(redisClient, { key, ip, scope = 'ip', value = ip, max, windowSec }) {
+  const redisKey = `rl:${key}:${windowSec}:${scope}:${value}`;
   const result = await redisClient.eval(LUA_INCR_EXPIRE, 1, redisKey, windowSec);
   const count = result[0];
   const ttl = result[1];
@@ -57,14 +57,18 @@ function configuredPolicies(config) {
   return [{ key: config.ratelimit.key, ...config._parsedRateLimit }];
 }
 
-async function checkRouteRateLimits(redisClient, config, ip) {
+async function checkRouteRateLimits(redisClient, config, req) {
   const policies = configuredPolicies(config);
+  const applicable = policies
+    .map((policy) => ({ policy, resolved: resolveRateLimitKey(policy, req) }))
+    .filter(({ resolved }) => resolved !== null);
   const results = await Promise.all(
-    policies.map(async (policy) => ({
+    applicable.map(async ({ policy, resolved }) => ({
       policy,
-      result: await checkRateLimit(redisClient, { ...policy, ip }),
+      result: await checkRateLimit(redisClient, { ...policy, ...resolved }),
     })),
   );
+  if (results.length === 0) return { allowed: true, selected: null, results };
   const denied = results.filter(({ result }) => !result.allowed);
   const candidates = denied.length > 0 ? denied : results;
   const selected = candidates.reduce((strictest, candidate) => {
@@ -84,3 +88,4 @@ async function checkRouteRateLimits(redisClient, config, ip) {
 }
 
 export { checkRateLimit, checkRouteRateLimits, parseRateLimit };
+import { resolveRateLimitKey } from './ratelimit-key.js';

package/server/router/routes.js

@@ -1,6 +1,7 @@
 import { compileRoutePattern, extractRouteParams } from '#client/route-pattern.js';
 import { discoverModules } from '../discovery.js';
 import { parseRateLimit } from './ratelimit.js';
+import { isValidRateLimitBy } from './ratelimit-key.js';
 const HTTP_METHODS = ['GET', 'HEAD', 'POST', 'PUT', 'PATCH', 'DELETE'];
 function filePathToPattern(relativePath) {
   let route = relativePath.replace(/\\/g, '/');
@@ -84,8 +85,16 @@ function buildRoutesFromModules(entries, { prefix = '', plugin } = {}) {
               `Route ${method} ${urlPattern} (${filePath}) ratelimit${suffix}.key must be a non-empty string`,
             );
           }
+          const by = policy.by ?? 'ip';
+          if (!isValidRateLimitBy(by)) {
+            const suffix = policies.length > 1 ? `[${index}]` : '';
+            throw new Error(
+              `Route ${method} ${urlPattern} (${filePath}) ratelimit${suffix}.by must be "ip", a request path, or a function`,
+            );
+          }
           return {
             key: policy.key ?? defaultRateLimitKey(relativePath, method, prefix),
+            _by: by,
             ...parseRateLimit(policy.limit),
           };
         });

package/server/testing/index.js

@@ -170,6 +170,8 @@ async function testBoot(options) {
   });
   const baseUrl = `http://127.0.0.1:${app.port}`;
   const appContext = {
+    config: app.config,
+    env: app.config?.env,
     db: app.db,
     events: app.eventBus,
     queue: { push: async () => {}, pop: async () => [], remove: async () => {} },