@ismaelsoilet/synapsejs 1.8.0 → 1.11.1

package/src/core/config.ts

@@ -11,7 +11,7 @@ export interface SynapsePlugin {
   name: string;
   // biome-ignore lint/suspicious/noExplicitAny: generic boundary for framework server
   onBootstrap?: (server: any) => Promise<void> | void;
-  onRequest?: (req: Request) => Promise<Response | null | undefined> | Response | null | void;
+  onRequest?: (req: Request) => Promise<Response | null | undefined> | Response | null | undefined;
   onResponse?: (res: Response, req: Request) => Promise<Response> | Response;
   // biome-ignore lint/suspicious/noExplicitAny: generic boundary for database client
   onMigrate?: (db: any) => Promise<void> | void;
@@ -55,9 +55,31 @@ export interface SynapseConfig<TServices = Record<string, unknown>> {
 
   /**
    * Trust proxy headers (cf-connecting-ip, x-forwarded-for) for rate limiting and IP resolution.
+   * Opt-in: when this is not explicitly `true` (or SYNAPSE_TRUST_PROXY is not `true`), the
+   * immediate peer address is used and a rotating forwarding header cannot mint a new allowance.
    */
   trustProxy?: boolean;
 
+  /**
+   * Process-level maximum request body size, enforced by the HTTP server itself before any
+   * body reader runs (default: 12 MiB, above every per-route ceiling). It is the backstop
+   * behind the RPC (5 MiB), webhook (10 MiB) and upload (5 MiB) limits.
+   */
+  maxRequestBodyBytes?: number;
+
+  /**
+   * Rate limiting. Scope is the serving process only: each instance keeps its own counters,
+   * so N instances behind a load balancer permit N times the per-instance allowance.
+   */
+  rateLimit?: {
+    /** Maximum burst capacity (default: 150). */
+    capacity?: number;
+    /** Refill rate in tokens per second (default: 100). */
+    refillRate?: number;
+    /** Maximum tracked client identities before the registry is saturated (default: 10,000). */
+    maxBuckets?: number;
+  };
+
   /**
    * Max allowed payload bytes for RPC POST requests (default: 5MB).
    */
@@ -75,11 +97,54 @@ export interface SynapseConfig<TServices = Record<string, unknown>> {
     maxEntries?: number;
   };
 
+  /**
+   * Third-party CDN and web-font origins (Tailwind's runtime compiler, Google Fonts).
+   * **Opt-in**: nothing third-party is referenced by default. When enabled, the
+   * content-security policy is rebuilt to permit exactly the configured origins, and
+   * the emitted tags carry a subresource-integrity hash — without one, the tag is not
+   * emitted at all, because an unpinned third-party script in an origin that holds a
+   * script-readable session cookie is the whole risk.
+   */
+  cdn?: {
+    enabled?: boolean;
+    /** SRI hash for the Tailwind runtime script (`sha384-...`). */
+    scriptIntegrity?: string;
+    /** SRI hash for the Google Fonts stylesheet (`sha384-...`). */
+    fontIntegrity?: string;
+  };
+
+  /**
+   * Realtime (event stream and WebSocket) limits. Long-lived connections consume a
+   * token from the rate limiter at most once, so these bounds — not the token bucket —
+   * are what caps concurrent streams.
+   */
+  realtime?: {
+    /** Maximum distinct topics with an open subscription (default: 1000). */
+    maxTopics?: number;
+    /** Maximum concurrently open realtime connections (default: 1000). */
+    maxSubscriptions?: number;
+    /** Maximum concurrently open realtime connections from one client (default: 8). */
+    maxConnectionsPerClient?: number;
+  };
+
+  /**
+   * Operator-supplied Content-Security-Policy. When present it is emitted as given —
+   * the framework never weakens it — and replaces the built-in policy.
+   */
+  contentSecurityPolicy?: string;
+
   /**
    * Image optimizer security settings.
+   * When `allowedDomains` is absent, any publicly routable host is permitted (loopback,
+   * link-local, private and metadata addresses are always refused) and the documentation
+   * says so rather than implying a restriction that is not enforced.
    */
   imageOptimizer?: {
     allowedDomains?: string[];
+    /** Maximum bytes accepted from a remote image host (default: 10 MiB). */
+    maxResponseBytes?: number;
+    /** Maximum time a remote image fetch may take, in ms (default: 10,000). */
+    timeoutMs?: number;
   };
 }
 
@@ -93,20 +158,33 @@ const CONFIG_FILENAMES = ['synapse.config.ts', 'synapse.config.js', 'synapse.con
 
 /**
  * Discovers and loads `synapse.config.(ts|js|mjs)` from the application root.
+ *
+ * A configuration file that exists but cannot be loaded is **fatal**: the config
+ * carries security-relevant defaults (trusted proxy, body ceilings, realtime bounds),
+ * so degrading to an empty configuration silently would start the server with
+ * settings nobody chose. Absence of the file is not an error — it means "defaults".
  */
 export async function loadSynapseConfig(appDir: string): Promise<SynapseConfig> {
   for (const filename of CONFIG_FILENAMES) {
     const candidate = path.join(appDir, filename);
-    if (fs.existsSync(candidate)) {
-      try {
-        const mod = await import(candidate);
-        const config = mod.default || mod;
-        return typeof config === 'function' ? await config() : config;
-      } catch (err: unknown) {
-        const errMessage = err instanceof Error ? err.message : String(err);
-        console.warn(`[SynapseConfig] Aviso ao carregar ${filename}: ${errMessage}`);
-      }
+
+    if (!fs.existsSync(candidate)) {
+      continue;
     }
+
+    let mod: { default?: unknown } & Record<string, unknown>;
+
+    try {
+      mod = (await import(candidate)) as { default?: unknown } & Record<string, unknown>;
+    } catch (err: unknown) {
+      const errMessage = err instanceof Error ? err.message : String(err);
+
+      throw new Error(`[SynapseConfig] falha ao carregar ${filename}: ${errMessage}`);
+    }
+
+    const config = (mod.default || mod) as SynapseConfig | (() => SynapseConfig | Promise<SynapseConfig>);
+
+    return typeof config === 'function' ? await config() : config;
   }
 
   return {};

package/src/core/cron-parser.ts

@@ -0,0 +1,167 @@
+/**
+ * SynapseJS - Zero-Dependency 5-Field Standard Cron Expression Parser
+ *
+ * Evaluates standard cron strings (minute, hour, day-of-month, month, day-of-week)
+ * and calculates the exact next UTC execution timestamp deterministically.
+ *
+ * Day-of-month and day-of-week follow POSIX/Vixie semantics: when both fields are
+ * restricted, the expression matches the union of the two (OR), not the
+ * intersection. Names, L, W, # and ? are rejected explicitly instead of silently
+ * searching for an impossible date.
+ */
+
+export interface ParsedCronField {
+  matches(val: number): boolean;
+}
+
+function matchesField(value: number, sundaySeven: boolean, predicate: (value: number) => boolean): boolean {
+  return predicate(value) || (sundaySeven && value === 0 && predicate(7));
+}
+
+function parseField(field: string, min: number, max: number, sundaySeven = false): ParsedCronField {
+  const trimmed = field.trim();
+  if (trimmed === '*') {
+    return { matches: () => true };
+  }
+
+  // Handle step: */5 or 10-30/5
+  if (trimmed.includes('/')) {
+    const [rangePart, stepPart] = trimmed.split('/');
+    const step = Number.parseInt(stepPart, 10);
+    if (Number.isNaN(step) || step <= 0) {
+      throw new Error(`Invalid cron step: "${stepPart}" in "${field}"`);
+    }
+
+    let start = min;
+    let end = max;
+    if (rangePart !== '*') {
+      if (rangePart.includes('-')) {
+        const [rawStart, rawEnd] = rangePart.split('-').map((n) => Number.parseInt(n, 10));
+        if (Number.isNaN(rawStart) || Number.isNaN(rawEnd) || rawStart < min || rawEnd > max || rawStart > rawEnd) {
+          throw new Error(`Invalid cron range: "${rangePart}" in "${field}"`);
+        }
+        start = rawStart;
+        end = rawEnd;
+      } else {
+        const rawStart = Number.parseInt(rangePart, 10);
+        if (Number.isNaN(rawStart) || rawStart < min || rawStart > max) {
+          throw new Error(`Invalid cron number: "${rangePart}" (expected ${min}-${max})`);
+        }
+        start = rawStart;
+      }
+    }
+
+    return {
+      matches: (val: number) =>
+        matchesField(val, sundaySeven, (value) => value >= start && value <= end && (value - start) % step === 0)
+    };
+  }
+
+  // Handle list: 1,2,5
+  if (trimmed.includes(',')) {
+    const subParsers = trimmed.split(',').map((part) => parseField(part, min, max, sundaySeven));
+    return {
+      matches: (val: number) => subParsers.some((parser) => parser.matches(val))
+    };
+  }
+
+  // Handle range: 1-5
+  if (trimmed.includes('-')) {
+    const [start, end] = trimmed.split('-').map((n) => Number.parseInt(n, 10));
+    if (Number.isNaN(start) || Number.isNaN(end) || start > end || start < min || end > max) {
+      throw new Error(`Invalid cron range: "${field}"`);
+    }
+    return {
+      matches: (val: number) => matchesField(val, sundaySeven, (value) => value >= start && value <= end)
+    };
+  }
+
+  // Exact number: 5
+  const exact = Number.parseInt(trimmed, 10);
+  if (Number.isNaN(exact) || exact < min || exact > max) {
+    throw new Error(`Invalid cron number: "${trimmed}" (expected ${min}-${max})`);
+  }
+  return {
+    matches: (val: number) => matchesField(val, sundaySeven, (value) => value === exact)
+  };
+}
+
+export function parseNextCronOccurrence(cronExpr: string, fromDate: Date = new Date()): Date {
+  const parts = cronExpr.trim().split(/\s+/);
+  if (parts.length !== 5) {
+    throw new Error(`Cron expression must contain exactly 5 parts (got ${parts.length}): "${cronExpr}"`);
+  }
+
+  for (const part of parts) {
+    if (/[A-Za-z?#]/.test(part)) {
+      throw new Error(
+        `Unsupported cron syntax: "${part}". Names, L, W, # and ? are not supported; use numbers, ranges, lists and steps.`
+      );
+    }
+  }
+
+  const minuteField = parseField(parts[0], 0, 59);
+  const hourField = parseField(parts[1], 0, 23);
+  const dayOfMonthField = parseField(parts[2], 1, 31);
+  const monthField = parseField(parts[3], 1, 12);
+  // Sunday is accepted as 0 or 7; the field matcher tests both representations.
+  const dayOfWeekField = parseField(parts[4], 0, 7, true);
+
+  const dayOfMonthRestricted = parts[2].trim() !== '*';
+  const dayOfWeekRestricted = parts[4].trim() !== '*';
+
+  // Start checking from the next whole minute
+  const candidate = new Date(fromDate.getTime());
+  candidate.setUTCSeconds(0, 0);
+  candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+
+  // Limit search to 5 years (approx 2,628,000 minutes) to prevent infinite loops on impossible dates
+  const maxIterations = 5 * 365 * 24 * 60;
+  let iterations = 0;
+
+  while (iterations < maxIterations) {
+    const month = candidate.getUTCMonth() + 1; // 1-12
+    if (!monthField.matches(month)) {
+      // Advance to start of next month
+      candidate.setUTCMonth(candidate.getUTCMonth() + 1, 1);
+      candidate.setUTCHours(0, 0, 0, 0);
+      iterations += 60;
+      continue;
+    }
+
+    const dayOfMonth = candidate.getUTCDate();
+    const dayOfWeek = candidate.getUTCDay(); // 0 = Sunday
+    const dayOfMonthMatches = dayOfMonthField.matches(dayOfMonth);
+    const dayOfWeekMatches = dayOfWeekField.matches(dayOfWeek);
+    const dayMatches =
+      dayOfMonthRestricted && dayOfWeekRestricted
+        ? dayOfMonthMatches || dayOfWeekMatches
+        : dayOfMonthMatches && dayOfWeekMatches;
+
+    if (!dayMatches) {
+      // Advance to start of next day
+      candidate.setUTCDate(candidate.getUTCDate() + 1);
+      candidate.setUTCHours(0, 0, 0, 0);
+      iterations += 60;
+      continue;
+    }
+
+    const hour = candidate.getUTCHours();
+    if (!hourField.matches(hour)) {
+      // Advance to next hour
+      candidate.setUTCHours(candidate.getUTCHours() + 1, 0, 0, 0);
+      iterations += 60;
+      continue;
+    }
+
+    const minute = candidate.getUTCMinutes();
+    if (minuteField.matches(minute)) {
+      return candidate;
+    }
+
+    candidate.setUTCMinutes(candidate.getUTCMinutes() + 1);
+    iterations++;
+  }
+
+  throw new Error(`Unable to find next execution for cron expression: "${cronExpr}" within search horizon.`);
+}

package/src/core/database-client.ts

@@ -1,8 +1,9 @@
 /**
  * SynapseJS - Database Context & Query Builder Abstraction
  *
- * Provides a clean, type-safe persistence contract without reflection-based ORM bloat.
- * Compatible with raw parameterized SQL, Kysely, and Drizzle query builders.
+ * Provides a clean, type-safe persistence contract without reflection-based ORM bloat:
+ * raw parameterized SQL plus a relational query builder, with no adapter for any other
+ * query builder.
  */
 
 export interface QueryResult<T = unknown> {
@@ -98,6 +99,21 @@ export interface DatabaseClient {
    */
   delete(table: string, where: WhereCondition): Promise<number>;
 
+  /**
+   * Declarative row count with optional WHERE filter.
+   */
+  count(table: string, where?: WhereCondition): Promise<number>;
+
+  /**
+   * Declarative existence check returning true if at least one matching row exists.
+   */
+  exists(table: string, where: WhereCondition): Promise<boolean>;
+
+  /**
+   * Declarative aggregation and grouping query.
+   */
+  aggregate<T = Record<string, unknown>>(table: string, options: QueryOptions): Promise<T[]>;
+
   /**
    * Execute command inside a database transaction boundary.
    */
@@ -112,6 +128,24 @@ export interface DatabaseClient {
 /**
  * In-memory Mock Database Client for deterministic testing and PBT (Fast-Check).
  */
+/** Equality and `eq`/`in` matching, which is what the in-memory store can honour honestly. */
+function rowMatchesCondition(row: Record<string, unknown>, where: WhereCondition): boolean {
+  return Object.entries(where).every(([column, condition]) => {
+    const value = row[column];
+
+    if (condition !== null && typeof condition === 'object' && 'op' in (condition as Record<string, unknown>)) {
+      const { op, val } = condition as { op: string; val: unknown };
+
+      if (op === 'eq') return value === val;
+      if (op === 'in') return Array.isArray(val) && val.includes(value);
+
+      return false;
+    }
+
+    return value === condition;
+  });
+}
+
 export class MockDatabaseClient implements DatabaseClient {
   private tables: Map<string, Array<Record<string, unknown>>> = new Map();
   private queryHandlers: Array<{
@@ -228,18 +262,81 @@ export class MockDatabaseClient implements DatabaseClient {
   async update<T = unknown>(table: string, data: Record<string, unknown>, where: WhereCondition): Promise<T[]> {
     const { sql, params } = compileUpdate(table, data, where);
     const results = await this.query<T>(sql, params);
-    if (results.length > 0) return results;
-    return [data as T];
+
+    if (results.length > 0) {
+      return results;
+    }
+
+    // No row matched, so no row is returned: reporting the payload back would be a
+    // write that never happened.
+    const rows = this.tables.get(table);
+
+    if (!rows) {
+      return [];
+    }
+
+    const updated = rows.filter((row) => rowMatchesCondition(row, where));
+    for (const row of updated) {
+      Object.assign(row, data);
+    }
+
+    return updated as unknown as T[];
   }
 
   async delete(table: string, where: WhereCondition): Promise<number> {
     const { sql, params } = compileDelete(table, where);
     const results = await this.query(sql, params);
-    return results.length > 0 ? results.length : 1;
+
+    if (results.length > 0) {
+      return results.length;
+    }
+
+    // A delete that matched nothing removed nothing.
+    const rows = this.tables.get(table);
+
+    if (!rows) {
+      return 0;
+    }
+
+    const survivors = rows.filter((row) => !rowMatchesCondition(row, where));
+    const removed = rows.length - survivors.length;
+    this.tables.set(table, survivors);
+
+    return removed;
+  }
+
+  async count(table: string, where?: WhereCondition): Promise<number> {
+    const rows = await this.findMany(table, { where });
+    return rows.length;
+  }
+
+  async exists(table: string, where: WhereCondition): Promise<boolean> {
+    const rows = await this.findMany(table, { where, limit: 1 });
+    return rows.length > 0;
+  }
+
+  async aggregate<T = Record<string, unknown>>(table: string, options: QueryOptions): Promise<T[]> {
+    if (options.aggregations?.length || options.groupBy || options.having) {
+      throw new Error(
+        'UNSUPPORTED_OPERATION: MockDatabaseClient.aggregate does not implement aggregations, grouping or HAVING; use a real database for that assertion'
+      );
+    }
+
+    return this.findMany<T>(table, options);
   }
 
   async transaction<T>(operation: (tx: DatabaseClient) => Promise<T>): Promise<T> {
-    return operation(this);
+    const snapshot = new Map(
+      Array.from(this.tables.entries()).map(([table, rows]) => [table, rows.map((row) => ({ ...row }))])
+    );
+
+    try {
+      return await operation(this);
+    } catch (error) {
+      // A rolled-back transaction discards the writes made inside it.
+      this.tables = snapshot;
+      throw error;
+    }
   }
 
   close(): void {}

package/src/core/index.ts

@@ -2,11 +2,14 @@ export * from './action-context';
 export * from './action-definition';
 export * from './cache';
 export * from './config';
+export * from './cron-parser';
 export * from './database-client';
 export * from './database-factory';
 export * from './image-optimizer';
 export * from './jobs';
 export * from './machine-types';
+export * from './oauth-client';
+export * from './path-guard';
 export * from './postgres-client';
 export * from './postgres-queue';
 export * from './query-builder';
@@ -14,5 +17,7 @@ export * from './session-context';
 export * from './session-token';
 export * from './sqlite-client';
 export * from './storage';
+export * from './topics';
 export * from './validation';
+export * from './webhook-signature';
 export * from './websocket';

package/src/core/jobs.ts

@@ -8,10 +8,35 @@
  * });
  */
 
+import { Value } from '@sinclair/typebox/value';
 import type { ActionContext } from './action-context';
 
 export type JobHandlerFn<TPayload = unknown> = (payload: TPayload, ctx: ActionContext) => Promise<void>;
 
+export type JobScheduleErrorCode = 'CRON_UNSUPPORTED_ENGINE' | 'CONFLICTING_SCHEDULE' | 'INVALID_CRON_PAYLOAD';
+
+export class JobScheduleError extends Error {
+  readonly code: JobScheduleErrorCode;
+
+  constructor(code: JobScheduleErrorCode, message: string) {
+    super(`${code}: ${message}`);
+    this.name = 'JobScheduleError';
+    this.code = code;
+  }
+}
+
+export function jobPayloadMatchesSchema(schema: unknown, payload: unknown): boolean {
+  if (!schema || typeof schema !== 'object') {
+    return true;
+  }
+
+  try {
+    return Value.Check(schema as never, payload);
+  } catch {
+    return true;
+  }
+}
+
 export interface JobDefinition<TPayload = unknown> {
   /** Unique name identifier for the job */
   readonly name: string;
@@ -21,6 +46,12 @@ export interface JobDefinition<TPayload = unknown> {
   readonly retryLimit?: number;
   /** Initial backoff in seconds for exponential backoff retries (default: 5) */
   readonly backoffSeconds?: number;
+  /** Optional recurring cron expression (e.g. '0 0 * * *' or hourly/daily) */
+  readonly cron?: string;
+  /** Optional payload factory used for the first run and each recurrence. */
+  readonly cronPayload?: () => TPayload;
+  /** Optional future execution timestamp in milliseconds */
+  readonly runAt?: number;
   /** Optional schema validator (e.g. TypeBox schema) */
   readonly schema?: unknown;
 }
@@ -31,6 +62,9 @@ export interface JobOptions<TPayload = unknown> {
   perform?: JobHandlerFn<TPayload>;
   retryLimit?: number;
   backoffSeconds?: number;
+  cron?: string;
+  cronPayload?: () => TPayload;
+  runAt?: number;
   schema?: unknown;
 }
 
@@ -48,6 +82,9 @@ export function defineJob<TPayload = unknown>(options: JobOptions<TPayload>): Jo
     handler,
     retryLimit: options.retryLimit ?? 3,
     backoffSeconds: options.backoffSeconds ?? 5,
+    cron: options.cron,
+    cronPayload: options.cronPayload,
+    runAt: options.runAt,
     schema: options.schema
   });
 }