@pithy-sh/core 0.12.0 → 0.13.0

package/src/createEntrypoint.ts

@@ -28,7 +28,13 @@ export interface PithyEntrypoint {
    */
   email?: (message: ForwardableEmailMessage, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
   /**
-   * The Worker `scheduled` handler — starts every registered job that declares a `schedule`.
+   * The Worker `scheduled` handler — starts every registered job whose `schedule` is the cron that fired.
+   *
+   * A Worker carries one `scheduled` entry for all of its `triggers.crons`, and the runtime names the one
+   * that fired on `controller.cron`, verbatim as `wrangler.jsonc` declares it. Only the jobs whose
+   * `schedule` is that string start: a daily job composed beside an hourly one must not run every hour,
+   * and the hourly one must not run an extra time at the daily job's minute (#622). An event that names
+   * no cron, or one no job declares, starts nothing.
    *
    * **Present only when at least one job carries a cron.** The reason differs from `email`'s: an
    * inert `email()` silently *drops* mail, which is a correctness bug, whereas an inert `scheduled()`
@@ -50,6 +56,13 @@ export interface PithyEntrypoint {
   scheduled?: (controller: unknown, env: Record<string, unknown>, ctx: ExecutionContext) => Promise<void>;
 }
 
+/** The cron expression a `scheduled` event fired for, or `undefined` when the event names none. */
+function firedCron(controller: unknown): string | undefined {
+  if (typeof controller !== "object" || controller === null) return undefined;
+  const cron = (controller as { cron?: unknown }).cron;
+  return typeof cron === "string" ? cron : undefined;
+}
+
 /**
  * The raw MIME stream of a `ForwardableEmailMessage` is **single-use** — once one handler reads it,
  * the next sees an empty stream. When more than one capability handles inbound mail we buffer the
@@ -99,9 +112,11 @@ export function createEntrypoint<
   // job whose binding is missing cannot stop the rest of the schedule from running; the failure is
   // rethrown after the pass so the invocation is still recorded as failed.
   if (scheduled.length > 0) {
-    entrypoint.scheduled = async (_controller, env) => {
+    entrypoint.scheduled = async (controller, env) => {
+      const cron = firedCron(controller);
       const failures: unknown[] = [];
       for (const entry of scheduled) {
+        if (entry.spec.schedule !== cron) continue;
         // A cron supplies no caller input, which is an *empty* parameter object, not an absent one —
         // `z.object({})` accepts `{}` and rejects `undefined`. A job whose schema requires fields it
         // can never receive on a schedule therefore fails loudly here, which is the author's bug and

package/src/error/payload.ts

@@ -1525,6 +1525,54 @@ const OrganizationNominationInvalidPublic = z
   })
   .describe("No standing ownership offer this caller may accept (400).");
 
+const OrganizationLastOwnerPublic = z
+  .object({
+    code: z
+      .literal("organization/last_owner")
+      .describe(
+        "An operator write would leave the account with nobody holding the role a transfer of ownership confers: removing or demoting its only owner. An account with no owner is the unadministrable state membership administration exists to get out of, so the way out is to force ownership onto somebody else first, which `params.ownershipRoute` names.",
+      ),
+    status: z.literal(409).describe("Conflict — an account nobody owns is not a state to arrive at."),
+    ...publicFields,
+  })
+  .describe("The last owner cannot be removed or demoted (409).");
+
+const OrganizationAlreadyMemberPublic = z
+  .object({
+    code: z
+      .literal("organization/already_member")
+      .describe(
+        "An operator tried to add somebody who already holds a membership in the account. One membership per person per organization, so this is a refusal rather than a second row — and `params.role` names the role they already hold, because the next step is a role change rather than an add.",
+      ),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("That person is already a member (409).");
+
+const OrganizationSeatLimitReachedPublic = z
+  .object({
+    code: z
+      .literal("organization/seat_limit_reached")
+      .describe(
+        "The account holds as many members as its seat limit allows, so another one would exceed it. `params.seatLimit` names the limit. An operator add may override it, and the override is recorded; an invitation accepted against a full account is refused until a seat frees.",
+      ),
+    status: z.literal(409).describe("Conflict."),
+    ...publicFields,
+  })
+  .describe("The account has no free seat (409).");
+
+const OrganizationSuspendedPublic = z
+  .object({
+    code: z
+      .literal("organization/organization_suspended")
+      .describe(
+        "The organization this request acts in is suspended by an operator, so nobody can act in it until it is reinstated (#623). The caller's own account is not affected, and their other organizations are not either. `params.suspendedUntil`, when present, is when the suspension ends by itself, ISO-8601. Not `organization/forbidden`, because no role would let them, and not `organization/not_found`, because the caller is a proved member and already knows the organization exists.",
+      ),
+    status: z.literal(403).describe("Forbidden — the organization may not be acted in, whoever asks."),
+    ...publicFields,
+  })
+  .describe("The organization is suspended (403).");
+
 // --- @pithy-sh/artifacts: Git repositories, ownership, grants and short-lived tokens ---
 
 const ArtifactsNotFoundPublic = z
@@ -1908,6 +1956,10 @@ export const KitPublicErrorPayload = z
     OrganizationLastAdministratorPublic,
     OrganizationSlugTakenPublic,
     OrganizationNominationInvalidPublic,
+    OrganizationLastOwnerPublic,
+    OrganizationAlreadyMemberPublic,
+    OrganizationSeatLimitReachedPublic,
+    OrganizationSuspendedPublic,
     ArtifactsNotFoundPublic,
     ArtifactsForbiddenPublic,
     ArtifactsInvalidNamePublic,
@@ -2304,6 +2356,18 @@ const OrganizationSlugTaken = OrganizationSlugTakenPublic.extend(internalFields)
 const OrganizationNominationInvalid = OrganizationNominationInvalidPublic.extend(internalFields).describe(
   OrganizationNominationInvalidPublic.description ?? "",
 );
+const OrganizationLastOwner = OrganizationLastOwnerPublic.extend(internalFields).describe(
+  OrganizationLastOwnerPublic.description ?? "",
+);
+const OrganizationAlreadyMember = OrganizationAlreadyMemberPublic.extend(internalFields).describe(
+  OrganizationAlreadyMemberPublic.description ?? "",
+);
+const OrganizationSeatLimitReached = OrganizationSeatLimitReachedPublic.extend(internalFields).describe(
+  OrganizationSeatLimitReachedPublic.description ?? "",
+);
+const OrganizationSuspended = OrganizationSuspendedPublic.extend(internalFields).describe(
+  OrganizationSuspendedPublic.description ?? "",
+);
 
 const ArtifactsNotFound = ArtifactsNotFoundPublic.extend(internalFields).describe(
   ArtifactsNotFoundPublic.description ?? "",
@@ -2469,6 +2533,10 @@ export const KitErrorPayload = z
     OrganizationLastAdministrator,
     OrganizationSlugTaken,
     OrganizationNominationInvalid,
+    OrganizationLastOwner,
+    OrganizationAlreadyMember,
+    OrganizationSeatLimitReached,
+    OrganizationSuspended,
     ArtifactsNotFound,
     ArtifactsForbidden,
     ArtifactsInvalidName,

package/src/http/validation.ts

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: MIT
 
 import { zValidator } from "@hono/zod-validator";
-import type { ValidationTargets } from "hono";
+import type { Context, MiddlewareHandler, ValidationTargets } from "hono";
 import type { z } from "zod";
 import { fromZodError } from "../error/pithyError";
 
@@ -70,12 +70,44 @@ export interface RequestContract {
 export function validate<Target extends keyof ValidationTargets, Schema extends z.ZodType>(
   target: Target,
   schema: Schema,
+  onInvalid?: InvalidRequestListener,
 ) {
-  const middleware = zValidator(target, schema, validationHook);
   const contract: RequestContract = { target, schema };
-  return Object.assign(middleware, { [REQUEST_CONTRACT]: contract });
+  if (!onInvalid) return Object.assign(zValidator(target, schema, validationHook), { [REQUEST_CONTRACT]: contract });
+  // What each refused request sent, keyed by its context, so the listener is handed the input without
+  // reading the request raw — which no route may do.
+  const refusedInput = new WeakMap<Context, unknown>();
+  const middleware = zValidator(target, schema, (outcome: ValidationOutcome & { data?: unknown }, c: Context) => {
+    if (!outcome.success) refusedInput.set(c, outcome.data);
+    validationHook(outcome);
+  });
+  // Only a throw from the validator itself is a refusal of the request. Once `next` runs, a throw is the
+  // handler's, and is the handler's to record.
+  const listened: MiddlewareHandler = async (c, next) => {
+    let reached = false;
+    try {
+      return await middleware(c, async () => {
+        reached = true;
+        await next();
+      });
+    } catch (error) {
+      if (!reached) await onInvalid(c, error, refusedInput.get(c));
+      throw error;
+    }
+  };
+  return Object.assign(listened as typeof middleware, { [REQUEST_CONTRACT]: contract });
 }
 
+/**
+ * Told when {@link validate} refuses a request — a body that does not parse, or one that fails the schema —
+ * before the refusal is thrown. A route whose every attempt must be on the audit trail records the refusal
+ * here. It cannot turn the refusal into anything else: the error is thrown after it returns, and a listener
+ * that throws replaces it. `input` is what the request sent for the validated part, as it arrived; it is
+ * `undefined` when there was nothing to read, as for a body that is not JSON. Input validated by an earlier
+ * {@link validate} on the same route is readable with `c.req.valid(target)`.
+ */
+export type InvalidRequestListener = (c: Context, error: unknown, input: unknown) => Promise<void> | void;
+
 /** The contract a {@link validate} middleware carries, or `undefined` for any other handler. */
 export function requestContractOf(handler: unknown): RequestContract | undefined {
   if (typeof handler !== "function") return undefined;

package/src/version.generated.ts

@@ -13,4 +13,4 @@
 export const PACKAGE_NAME = "@pithy-sh/core";
 
 /** This package's version, stamped from its own package.json at generation time. */
-export const PACKAGE_VERSION = "0.12.0";
+export const PACKAGE_VERSION = "0.13.0";