alepha 0.19.3 → 0.19.5

package/src/api/jobs/services/JobService.ts

@@ -68,7 +68,7 @@ export class JobService {
           COUNT(*) FILTER (WHERE ${e.status} = 'retrying') AS retrying,
           COUNT(*) FILTER (WHERE ${e.status} = 'dead') AS dead,
           COUNT(*) FILTER (WHERE ${e.status} = 'completed' AND ${e.completedAt} >= ${periodAgo}) AS completed_24h,
-          COUNT(*) FILTER (WHERE ${e.status} IN ('dead', 'failed') AND ${e.completedAt} >= ${periodAgo}) AS failed_24h
+          COUNT(*) FILTER (WHERE ${e.status} = 'dead' AND ${e.completedAt} >= ${periodAgo}) AS failed_24h
         FROM ${e}
       `,
       t.object({
@@ -127,12 +127,7 @@ export class JobService {
               hasBackoff: Boolean(opts.retry.backoff),
             }
           : undefined,
-        batch: opts.batch
-          ? {
-              size: opts.batch.size,
-              window: String(opts.batch.window),
-            }
-          : undefined,
+        paused: this.jobProvider.isJobPaused(name),
       };
 
       result.push(registration);
@@ -278,6 +273,48 @@ export class JobService {
     return { ok: true };
   }
 
+  public pauseJob(
+    name: string,
+    context?: { pausedBy?: string; pausedByName?: string },
+  ): { ok: boolean } {
+    const jobPrimitives = this.alepha.primitives($job);
+    const job = jobPrimitives.find((j) => j.name === name);
+
+    if (!job) {
+      throw new NotFoundError(`Job not found: ${name}`);
+    }
+
+    this.log.info(`Pausing job '${name}'`, {
+      pausedBy: context?.pausedByName ?? context?.pausedBy,
+    });
+
+    job.pause();
+    return { ok: true };
+  }
+
+  public async resumeJob(
+    name: string,
+    context?: { resumedBy?: string; resumedByName?: string },
+  ): Promise<{ ok: boolean }> {
+    const jobPrimitives = this.alepha.primitives($job);
+    const job = jobPrimitives.find((j) => j.name === name);
+
+    if (!job) {
+      throw new NotFoundError(`Job not found: ${name}`);
+    }
+
+    this.log.info(`Resuming job '${name}'`, {
+      resumedBy: context?.resumedByName ?? context?.resumedBy,
+    });
+
+    await job.resume();
+    return { ok: true };
+  }
+
+  public getPausedJobs(): string[] {
+    return this.jobProvider.getPausedJobs();
+  }
+
   public async getCronJobs(): Promise<JobCronInfo[]> {
     const jobs = this.jobProvider.getRegisteredJobs();
     const cronJobNames: string[] = [];
@@ -301,6 +338,7 @@ export class JobService {
         priority: (opts.priority ?? "normal") as JobCronInfo["priority"],
         concurrency: opts.concurrency ?? 1,
         hasSchema: Boolean(opts.schema),
+        paused: this.jobProvider.isJobPaused(name),
         lastExecution: last
           ? {
               id: last.id,
@@ -355,6 +393,7 @@ export class JobService {
         retrying: Number(row?.retrying ?? 0),
         dead: Number(row?.dead ?? 0),
         concurrency: reg.options.concurrency ?? 1,
+        paused: this.jobProvider.isJobPaused(name),
       });
     }
 
@@ -378,10 +417,10 @@ export class JobService {
         SELECT
           ds.date::text AS date,
           COALESCE(COUNT(*) FILTER (WHERE ${e.status} = 'completed'), 0) AS completed,
-          COALESCE(COUNT(*) FILTER (WHERE ${e.status} IN ('dead', 'failed')), 0) AS failed
+          COALESCE(COUNT(*) FILTER (WHERE ${e.status} = 'dead'), 0) AS failed
         FROM date_series ds
         LEFT JOIN ${e} ON DATE(${e.completedAt}) = ds.date
-          AND ${e.status} IN ('completed', 'dead', 'failed')
+          AND ${e.status} IN ('completed', 'dead')
         GROUP BY ds.date
         ORDER BY ds.date ASC
       `,
@@ -404,7 +443,7 @@ export class JobService {
     const startDate = now.subtract(days - 1, "day");
 
     const where = this.executions.createQueryWhere();
-    where.status = { inArray: ["completed", "dead", "failed"] };
+    where.status = { inArray: ["completed", "dead"] };
     where.completedAt = { gte: startDate.startOf("day").toISOString() };
 
     const executions = await this.executions.findMany({ where });
@@ -448,7 +487,7 @@ export class JobService {
           COUNT(*) AS failures,
           (ARRAY_AGG(${e.error} ORDER BY ${e.completedAt} DESC))[1] AS last_error
         FROM ${e}
-        WHERE ${e.status} IN ('dead', 'failed')
+        WHERE ${e.status} = 'dead'
           AND ${e.completedAt} >= ${periodAgoIso}
         GROUP BY ${e.jobName}
         ORDER BY failures DESC
@@ -471,7 +510,7 @@ export class JobService {
     periodAgoIso: string,
   ): Promise<JobFailure[]> {
     const where = this.executions.createQueryWhere();
-    where.status = { inArray: ["dead", "failed"] };
+    where.status = { eq: "dead" };
     where.completedAt = { gte: periodAgoIso };
 
     const failures = await this.executions.findMany({

package/src/api/notifications/schemas/notificationQuerySchema.ts

@@ -9,7 +9,6 @@ export const notificationQuerySchema = t.extend(pageQuerySchema, {
       "retrying",
       "running",
       "completed",
-      "failed",
       "dead",
       "cancelled",
     ]),

package/src/api/parameters/__tests__/$parameter.spec.ts

@@ -1902,3 +1902,330 @@ describe("ParameterTreeNode children structure", () => {
     expect(aNode.children.map((c: any) => c.name).sort()).toEqual(["b", "c"]);
   });
 });
+
+// ---------------------------------------------------------------------------
+// Content validation in save()
+// ---------------------------------------------------------------------------
+
+describe("save validation", () => {
+  it("should reject invalid content when schema hash matches", async () => {
+    class AppConfig {
+      features = $parameter({
+        name: "validate.reject",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const provider = alepha.inject(ParameterProvider);
+    const schemaHash = (provider as any).schemaHashes.get("validate.reject");
+
+    // Invalid: maxUploadSize should be number, not string
+    await expect(
+      provider.save(
+        "validate.reject",
+        { enableBeta: true, maxUploadSize: "not-a-number" } as any,
+        schemaHash,
+      ),
+    ).rejects.toThrow();
+  });
+
+  it("should accept valid content when schema hash matches", async () => {
+    class AppConfig {
+      features = $parameter({
+        name: "validate.accept",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const provider = alepha.inject(ParameterProvider);
+    const schemaHash = (provider as any).schemaHashes.get("validate.accept");
+
+    const result = await provider.save(
+      "validate.accept",
+      { enableBeta: true, maxUploadSize: 999 },
+      schemaHash,
+    );
+
+    expect(result.content).toEqual({ enableBeta: true, maxUploadSize: 999 });
+  });
+
+  it("should skip validation when schema hash differs (migration seed)", async () => {
+    class AppConfig {
+      features = $parameter({
+        name: "validate.skip",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const provider = alepha.inject(ParameterProvider);
+
+    // Save with mismatched hash — should NOT validate against current schema
+    const result = await provider.save(
+      "validate.skip",
+      { totally: "different", shape: 42 } as any,
+      "old-hash",
+    );
+
+    expect(result.content).toEqual({ totally: "different", shape: 42 });
+  });
+});
+
+// ---------------------------------------------------------------------------
+// $parameter.name fallback
+// ---------------------------------------------------------------------------
+
+describe("$parameter.name fallback", () => {
+  it("should use ClassName.propertyKey when name option is omitted", async () => {
+    class MySettings {
+      theme = $parameter({
+        schema: t.object({ dark: t.boolean() }),
+        default: { dark: false },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(MySettings);
+    await alepha.start();
+
+    const settings = alepha.inject(MySettings);
+    expect(settings.theme.name).toBe("MySettings.theme");
+  });
+
+  it("should use explicit name when provided", async () => {
+    class MySettings {
+      theme = $parameter({
+        name: "app.ui.theme",
+        schema: t.object({ dark: t.boolean() }),
+        default: { dark: false },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(MySettings);
+    await alepha.start();
+
+    const settings = alepha.inject(MySettings);
+    expect(settings.theme.name).toBe("app.ui.theme");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// delete()
+// ---------------------------------------------------------------------------
+
+describe("delete", () => {
+  it("should delete all versions and clear cache", async () => {
+    class AppConfig {
+      features = $parameter({
+        name: "delete.test",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+    const provider = alepha.inject(ParameterProvider);
+
+    await config.features.set({ enableBeta: true, maxUploadSize: 100 });
+    await config.features.set({ enableBeta: false, maxUploadSize: 200 });
+
+    const historyBefore = await provider.getHistory("delete.test");
+    expect(historyBefore.length).toBe(2);
+
+    await config.features.delete();
+
+    // All versions gone
+    const historyAfter = await provider.getHistory("delete.test");
+    expect(historyAfter.length).toBe(0);
+
+    // Cache cleared — falls back to default
+    expect(await config.features.get()).toEqual({
+      enableBeta: false,
+      maxUploadSize: 10485760,
+    });
+    expect(config.features.isUsingDefault).toBe(true);
+  });
+
+  it("should be a no-op for non-existent parameter", async () => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const provider = alepha.inject(ParameterProvider);
+
+    // Should not throw
+    await provider.delete("nonexistent.param");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getHistory pagination
+// ---------------------------------------------------------------------------
+
+describe("getHistory pagination", () => {
+  it("should respect limit and offset", async () => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const provider = alepha.inject(ParameterProvider);
+
+    for (let i = 1; i <= 5; i++) {
+      await provider.save("paginate.test", { v: i }, "h");
+    }
+
+    // Get first 2 (versions 5, 4 — desc order)
+    const page1 = await provider.getHistory("paginate.test", {
+      limit: 2,
+    });
+    expect(page1.length).toBe(2);
+    expect(page1[0].version).toBe(5);
+    expect(page1[1].version).toBe(4);
+
+    // Get next 2 (versions 3, 2)
+    const page2 = await provider.getHistory("paginate.test", {
+      limit: 2,
+      offset: 2,
+    });
+    expect(page2.length).toBe(2);
+    expect(page2[0].version).toBe(3);
+    expect(page2[1].version).toBe(2);
+  });
+
+  it("should return all when no limit specified", async () => {
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    await alepha.start();
+
+    const provider = alepha.inject(ParameterProvider);
+
+    await provider.save("paginate.all", { v: 1 }, "h");
+    await provider.save("paginate.all", { v: 2 }, "h");
+    await provider.save("paginate.all", { v: 3 }, "h");
+
+    const all = await provider.getHistory("paginate.all");
+    expect(all.length).toBe(3);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// getVersion on primitive
+// ---------------------------------------------------------------------------
+
+describe("$parameter.getVersion", () => {
+  it("should return a specific version via the primitive", async () => {
+    class AppConfig {
+      features = $parameter({
+        name: "prim.getversion",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    await config.features.set({ enableBeta: true, maxUploadSize: 1 });
+    await config.features.set({ enableBeta: false, maxUploadSize: 2 });
+
+    const v1 = await config.features.getVersion(1);
+    expect(v1).not.toBeNull();
+    expect(v1!.content).toEqual({ enableBeta: true, maxUploadSize: 1 });
+
+    const missing = await config.features.getVersion(99);
+    expect(missing).toBeNull();
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tags
+// ---------------------------------------------------------------------------
+
+describe("tags", () => {
+  it("should store and retrieve tags on parameter versions", async () => {
+    class AppConfig {
+      features = $parameter({
+        name: "tags.test",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    await config.features.set(
+      { enableBeta: true, maxUploadSize: 100 },
+      { tags: ["feature-flag", "beta"] },
+    );
+
+    const history = await config.features.getHistory();
+    expect(history[0].tags).toEqual(["feature-flag", "beta"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Set idempotency
+// ---------------------------------------------------------------------------
+
+describe("set idempotency", () => {
+  it("should not notify subscribers when setting the same value", async () => {
+    class AppConfig {
+      features = $parameter({
+        name: "idempotent.test",
+        schema: featureSchema,
+        default: { enableBeta: false, maxUploadSize: 10485760 },
+      });
+    }
+
+    const alepha = Alepha.create().with(AlephaOrmPostgres);
+    alepha.with(AlephaApiParameters);
+    alepha.with(AppConfig);
+    await alepha.start();
+
+    const config = alepha.inject(AppConfig);
+
+    await config.features.set({ enableBeta: true, maxUploadSize: 100 });
+
+    const received: unknown[] = [];
+    config.features.sub((v) => received.push(v));
+
+    // Set the exact same value again
+    await config.features.set({ enableBeta: true, maxUploadSize: 100 });
+
+    expect(received.length).toBe(0);
+  });
+});

package/src/api/parameters/controllers/AdminParameterController.ts

@@ -1,6 +1,6 @@
 import { $inject, AlephaError, t } from "alepha";
 import { $secure } from "alepha/security";
-import { $action } from "alepha/server";
+import { $action, okSchema } from "alepha/server";
 import { activateParameterBodySchema } from "../schemas/activateParameterBodySchema.ts";
 import { createParameterVersionBodySchema } from "../schemas/createParameterVersionBodySchema.ts";
 import { parameterCurrentResponseSchema } from "../schemas/parameterCurrentResponseSchema.ts";
@@ -78,10 +78,17 @@ export class AdminParameterController {
     method: "GET",
     schema: {
       params: parameterNameParamSchema,
+      query: t.object({
+        limit: t.optional(t.integer({ minimum: 1, maximum: 100 })),
+        offset: t.optional(t.integer({ minimum: 0 })),
+      }),
       response: parameterHistoryResponseSchema,
     },
-    handler: async ({ params }) => {
-      const rawVersions = await this.provider.getHistory(params.name);
+    handler: async ({ params, query }) => {
+      const rawVersions = await this.provider.getHistory(params.name, {
+        limit: query.limit,
+        offset: query.offset,
+      });
       const versions = this.provider.calculateStatuses(rawVersions);
       return { versions };
     },
@@ -241,4 +248,23 @@ export class AdminParameterController {
       );
     },
   });
+
+  /**
+   * Delete all versions of a parameter.
+   */
+  deleteParameter = $action({
+    group: this.group,
+    use: [$secure({ permissions: ["admin:parameter:delete"] })],
+    description: "Delete all versions of a parameter.",
+    path: "/parameters/:name",
+    method: "DELETE",
+    schema: {
+      params: parameterNameParamSchema,
+      response: okSchema,
+    },
+    handler: async ({ params }) => {
+      await this.provider.delete(params.name);
+      return { ok: true };
+    },
+  });
 }

package/src/api/parameters/index.browser.ts

@@ -3,6 +3,18 @@ import { $module } from "alepha";
 // ---------------------------------------------------------------------------------------------------------------------
 
 export * from "./entities/parameters.ts";
+export * from "./schemas/activateParameterBodySchema.ts";
+export * from "./schemas/createParameterVersionBodySchema.ts";
+export * from "./schemas/parameterCurrentResponseSchema.ts";
+export * from "./schemas/parameterHistoryResponseSchema.ts";
+export * from "./schemas/parameterNameParamSchema.ts";
+export * from "./schemas/parameterNamesResponseSchema.ts";
+export * from "./schemas/parameterResponseSchema.ts";
+export * from "./schemas/parameterStatusSchema.ts";
+export * from "./schemas/parameterTreeNodeSchema.ts";
+export * from "./schemas/parameterVersionParamSchema.ts";
+export * from "./schemas/parameterVersionResponseSchema.ts";
+export * from "./schemas/rollbackParameterBodySchema.ts";
 
 // ---------------------------------------------------------------------------------------------------------------------
 

package/src/api/parameters/primitives/$parameter.ts

@@ -84,7 +84,10 @@ export class ParameterPrimitive<T extends TObject> extends Primitive<
    * Parameter name (uses property key if not specified).
    */
   public get name(): string {
-    return this.options.name || this.config.propertyKey;
+    return (
+      this.options.name ||
+      `${this.config.service.name}.${this.config.propertyKey}`
+    );
   }
 
   /**
@@ -163,8 +166,22 @@ export class ParameterPrimitive<T extends TObject> extends Primitive<
   /**
    * Get version history for this parameter.
    */
-  public async getHistory() {
-    return this.provider.getHistory(this.name);
+  public async getHistory(options?: { limit?: number; offset?: number }) {
+    return this.provider.getHistory(this.name, options);
+  }
+
+  /**
+   * Get a specific version of this parameter.
+   */
+  public async getVersion(version: number) {
+    return this.provider.getVersion(this.name, version);
+  }
+
+  /**
+   * Delete all versions of this parameter.
+   */
+  public async delete(): Promise<void> {
+    await this.provider.delete(this.name);
   }
 
   /**

package/src/api/parameters/services/ParameterProvider.ts

@@ -89,6 +89,12 @@ export class ParameterProvider {
    */
   protected readonly loadPromises = new Map<string, Promise<void>>();
 
+  /**
+   * Generation counter per parameter — incremented on each doLoad call.
+   * Used to discard results from superseded loads.
+   */
+  protected readonly loadGeneration = new Map<string, number>();
+
   /**
    * Subscriber callbacks per parameter name.
    */
@@ -379,6 +385,15 @@ export class ParameterProvider {
       schemaHash = this.schemaHashes.get(name) ?? "";
     }
 
+    // Validate content against the registered schema when the schema hash
+    // matches. A mismatched hash means the content is from a different
+    // schema version (e.g., migration seed) and should not be validated
+    // against the current schema.
+    const param = this.primitives.get(name);
+    if (param && schemaHash === this.schemaHashes.get(name)) {
+      content = this.alepha.codec.validate(param.schema, content) as Static<T>;
+    }
+
     const now = this.dateTimeProvider.now().toDate();
     const activationDate = options.activationDate ?? now;
     const isImmediate = activationDate <= now;
@@ -444,13 +459,32 @@ export class ParameterProvider {
   /**
    * Get all versions of a parameter.
    */
-  public async getHistory(name: string): Promise<Parameter[]> {
+  public async getHistory(
+    name: string,
+    options?: { limit?: number; offset?: number },
+  ): Promise<Parameter[]> {
     return this.repo.findMany({
       where: { name },
       orderBy: { column: "version", direction: "desc" },
+      limit: options?.limit,
+      offset: options?.offset,
     });
   }
 
+  /**
+   * Delete all versions of a parameter.
+   */
+  public async delete(name: string): Promise<void> {
+    await this.repo.deleteMany({ name: { eq: name } });
+    this.cachedCurrent.delete(name);
+    this.cachedNext.delete(name);
+    this.loaded.delete(name);
+    this.loadPromises.delete(name);
+    this.loadGeneration.delete(name);
+    this.migrationChecked.delete(name);
+    this.log.info("Parameter deleted", { name });
+  }
+
   /**
    * Get a specific version of a parameter.
    */
@@ -568,9 +602,15 @@ export class ParameterProvider {
    * Fetches current and next from database, updates cache.
    */
   protected async doLoad(name: string): Promise<void> {
+    const gen = (this.loadGeneration.get(name) ?? 0) + 1;
+    this.loadGeneration.set(name, gen);
+
     const { current, next } = await this.loadCurrentAndNext(name);
     const schemaHash = this.schemaHashes.get(name) ?? "";
 
+    // Superseded by a newer load — discard results
+    if (this.loadGeneration.get(name) !== gen) return;
+
     // Check if migration is needed
     if (current && !this.migrationChecked.has(name)) {
       this.migrationChecked.add(name);
@@ -665,21 +705,22 @@ export class ParameterProvider {
   }
 
   /**
-   * Poll until a lock is released.
+   * Poll until a lock is released (or TTL expires).
+   * Uses a probe-only SET NX with minimal TTL to detect release
+   * without holding the lock longer than necessary.
    */
   protected async waitForLock(lockKey: string): Promise<void> {
     const maxWait = 30_000;
+    const probeId = crypto.randomUUID();
     const start = this.dateTimeProvider.nowMillis();
     while (this.dateTimeProvider.nowMillis() - start < maxWait) {
-      await this.dateTimeProvider.wait(200);
-      const lockId = crypto.randomUUID();
-      const value = await this.lockProvider.set(lockKey, lockId, true, 1000);
-      if (value === lockId) {
+      await this.dateTimeProvider.wait(500);
+      const value = await this.lockProvider.set(lockKey, probeId, true, 500);
+      if (value === probeId) {
         await this.lockProvider.del(lockKey);
         return;
       }
     }
-    // Timeout — proceed anyway (lock expired or will expire)
   }
 
   /**