@owlmeans/server-job 0.1.18-rc.0

package/build/entrypoints.js

@@ -0,0 +1,46 @@
+import { entrypoint, filter, guard, query } from '@owlmeans/entrypoint';
+import { backend, route, RouteMethod, socket } from '@owlmeans/route';
+import { DEFAULT_GUARD } from '@owlmeans/auth-common';
+import { DEFAULT_JOB_PATH } from './consts.js';
+import { JobListQuerySchema } from './schemas.js';
+/**
+ * The aliases one job group answers under.
+ *
+ * The shape — `<root>` and `<root>:<verb>` — is the contract `@owlmeans/client-job` addresses the
+ * same group by, so a group renamed here is renamed there by passing the same root.
+ */
+export const jobEntrypointAliases = (root) => ({
+    base: root,
+    list: `${root}:list`,
+    get: `${root}:get`,
+    cancel: `${root}:cancel`,
+    watch: `${root}:watch`,
+});
+/**
+ * Declare the list/get/cancel/watch entrypoints of one job group.
+ *
+ * It belongs in the SHARED package of a target app — the one both the API and the browser import —
+ * so that the server elevates and the client calls the very declarations, and neither side ever
+ * writes a path. Declaring a second group is the same call with another root.
+ *
+ * The guard rides on the base alone: guards are inherited, so stating it once is what keeps the
+ * four from drifting apart.
+ */
+export const declareJobEntrypoints = (root, opts) => {
+    const aliases = jobEntrypointAliases(root);
+    const base = {
+        ...(opts?.parent != null ? { parent: opts.parent } : {}),
+        ...(opts?.service != null ? { service: opts.service } : {}),
+    };
+    const guarded = opts?.guard === null ? undefined : guard(opts?.guard ?? DEFAULT_GUARD);
+    return [
+        entrypoint(route(aliases.base, opts?.path ?? DEFAULT_JOB_PATH, backend(base)), guarded),
+        entrypoint(route(aliases.list, '/', backend(aliases.base)), filter(query(JobListQuerySchema))),
+        // Static before parametric, so `/watch` is not swallowed by `/:id`. The router picks the
+        // static branch on its own; the order here is for whoever reads the declaration.
+        entrypoint(route(aliases.watch, '/watch', socket(aliases.base))),
+        entrypoint(route(aliases.get, '/:id', backend(aliases.base))),
+        entrypoint(route(aliases.cancel, '/:id', backend(aliases.base, RouteMethod.DELETE))),
+    ];
+};
+//# sourceMappingURL=entrypoints.js.map

package/build/entrypoints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entrypoints.js","sourceRoot":"","sources":["../src/entrypoints.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAA;AAEvE,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAErE,OAAO,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AACrD,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAGjD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,IAAY,EAAwB,EAAE,CAAC,CAAC;IAC3E,IAAI,EAAE,IAAI;IACV,IAAI,EAAE,GAAG,IAAI,OAAO;IACpB,GAAG,EAAE,GAAG,IAAI,MAAM;IAClB,MAAM,EAAE,GAAG,IAAI,SAAS;IACxB,KAAK,EAAE,GAAG,IAAI,QAAQ;CACvB,CAAC,CAAA;AAEF;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CACnC,IAAY,EAAE,IAA2B,EACrB,EAAE;IACtB,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;IAC1C,MAAM,IAAI,GAA0B;QAClC,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACxD,GAAG,CAAC,IAAI,EAAE,OAAO,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC5D,CAAA;IACD,MAAM,OAAO,GAAG,IAAI,EAAE,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,IAAI,aAAa,CAAC,CAAA;IAEtF,OAAO;QACL,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,gBAAgB,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,OAAO,CAAC;QACvF,UAAU,CACR,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAC/C,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC,CAClC;QACD,yFAAyF;QACzF,iFAAiF;QACjF,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAChE,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;QAC7D,UAAU,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC,CAAC;KACrF,CAAA;AACH,CAAC,CAAA"}

package/build/helper.d.ts

@@ -0,0 +1,14 @@
+import type { ServerEntrypoint } from '@owlmeans/server-entrypoint';
+import type { CommonEntrypoint } from '@owlmeans/entrypoint';
+import type { JobHandlerOptions } from './types.js';
+/**
+ * Attach this package's handlers to a group declared by {@link declareJobEntrypoints}.
+ *
+ * The whole server half of "a long job reports progress to the user's screen" is this call plus
+ * the queue driver an app already wires — nothing is subclassed, and an app that wants one
+ * handler of its own elevates that alias itself afterwards, since `elevate` replaces in place.
+ *
+ * @throws {SyntaxError} when the array carries no group under that root.
+ */
+export declare const serveJobEntrypoints: <R>(entrypoints: (CommonEntrypoint | ServerEntrypoint<R>)[], root: string, opts?: JobHandlerOptions) => ServerEntrypoint<R>[];
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAA;AACnE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAA;AAG5D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAEnD;;;;;;;;GAQG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,eACtB,CAAC,gBAAgB,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAAC,EAAE,QAAQ,MAAM,SAAS,iBAAiB,KAC9F,gBAAgB,CAAC,CAAC,CAAC,EASrB,CAAA"}

package/build/helper.js

@@ -0,0 +1,21 @@
+import { elevate } from '@owlmeans/server-entrypoint';
+import { jobEntrypointAliases } from './entrypoints.js';
+import { cancelJob, getJob, listJobs, watchJobs } from './actions/index.js';
+/**
+ * Attach this package's handlers to a group declared by {@link declareJobEntrypoints}.
+ *
+ * The whole server half of "a long job reports progress to the user's screen" is this call plus
+ * the queue driver an app already wires — nothing is subclassed, and an app that wants one
+ * handler of its own elevates that alias itself afterwards, since `elevate` replaces in place.
+ *
+ * @throws {SyntaxError} when the array carries no group under that root.
+ */
+export const serveJobEntrypoints = (entrypoints, root, opts) => {
+    const aliases = jobEntrypointAliases(root);
+    elevate(entrypoints, aliases.base);
+    elevate(entrypoints, aliases.list, listJobs(opts));
+    elevate(entrypoints, aliases.watch, watchJobs(opts));
+    elevate(entrypoints, aliases.get, getJob(opts));
+    return elevate(entrypoints, aliases.cancel, cancelJob(opts));
+};
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAA;AAGrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAA;AAG3E;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CACjC,WAAuD,EAAE,IAAY,EAAE,IAAwB,EACxE,EAAE;IACzB,MAAM,OAAO,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;IAE1C,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAA;IAClD,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,KAAK,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;IACpD,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC,CAAA;IAE/C,OAAO,OAAO,CAAC,WAAW,EAAE,OAAO,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;AAC9D,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,8 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './schemas.js';
+export * from './entrypoints.js';
+export * from './helper.js';
+export * from './actions/index.js';
+export * from './utils/index.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,mBAAmB,YAAY,CAAA;AAE/B,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA"}

package/build/index.js

@@ -0,0 +1,7 @@
+export * from './consts.js';
+export * from './schemas.js';
+export * from './entrypoints.js';
+export * from './helper.js';
+export * from './actions/index.js';
+export * from './utils/index.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,cAAc,CAAA;AAC5B,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,oBAAoB,CAAA;AAClC,cAAc,kBAAkB,CAAA"}

package/build/schemas.d.ts

@@ -0,0 +1,10 @@
+import type { JSONSchemaType } from 'ajv';
+import type { JobListQuery } from './types.js';
+/**
+ * Every field is optional: a list screen opens before it has a filter, and a caller that knows
+ * nothing about jobs must still get the page it is allowed to see. `state` and `name` are left as
+ * plain strings rather than enums so that a driver reporting a state this line does not know
+ * narrows the list instead of failing the request.
+ */
+export declare const JobListQuerySchema: JSONSchemaType<JobListQuery>;
+//# sourceMappingURL=schemas.d.ts.map

package/build/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,KAAK,CAAA;AACzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,EAAE,cAAc,CAAC,YAAY,CAS3D,CAAA"}

package/build/schemas.js

@@ -0,0 +1,17 @@
+/**
+ * Every field is optional: a list screen opens before it has a filter, and a caller that knows
+ * nothing about jobs must still get the page it is allowed to see. `state` and `name` are left as
+ * plain strings rather than enums so that a driver reporting a state this line does not know
+ * narrows the list instead of failing the request.
+ */
+export const JobListQuerySchema = {
+    type: 'object',
+    properties: {
+        state: { type: 'string', maxLength: 32, nullable: true },
+        name: { type: 'string', maxLength: 256, nullable: true },
+        page: { type: 'integer', minimum: 0, nullable: true },
+        size: { type: 'integer', minimum: 1, maximum: 200, nullable: true },
+    },
+    additionalProperties: true,
+};
+//# sourceMappingURL=schemas.js.map

package/build/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sourceRoot":"","sources":["../src/schemas.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAiC;IAC9D,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE;QACV,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE;QACxD,IAAI,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE;QACxD,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE;QACrD,IAAI,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE;KACpE;IACD,oBAAoB,EAAE,IAAI;CAC3B,CAAA"}

package/build/types.d.ts

@@ -0,0 +1,60 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context';
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { QueueAppend, QueueConfig } from '@owlmeans/queue';
+import type { ApiServerAppend } from '@owlmeans/server-api';
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context';
+export interface Config extends ServerConfig {
+    queue?: QueueConfig;
+}
+export interface Context<C extends Config = Config> extends ServerContext<C>, ApiServerAppend, QueueAppend {
+}
+/** The alias every entrypoint of one job group answers under, derived from the group's root. */
+export interface JobEntrypointAliases {
+    base: string;
+    list: string;
+    get: string;
+    cancel: string;
+    watch: string;
+}
+export interface JobEntrypointOptions {
+    /** The path segment the group answers under. Defaults to `/jobs`. */
+    path?: string;
+    /** The entrypoint the group hangs under — an app's API base. Top level when omitted. */
+    parent?: string;
+    /** The service route the group answers on, when it is not this app's own. */
+    service?: string;
+    /**
+     * The guard the group's base carries, and every entrypoint under it inherits.
+     *
+     * `DEFAULT_GUARD` unless told otherwise, because ownership is derived from the authenticated
+     * subject and an unguarded declaration has no subject to derive it from. Pass `null` only for a
+     * group that is scoped some other way — its handlers then answer `AuthorizationError`.
+     */
+    guard?: string | null;
+}
+/** The list entrypoint's query, as it travels on the wire. */
+export interface JobListQuery {
+    state?: string;
+    name?: string;
+    page?: number;
+    size?: number;
+}
+/**
+ * A request that may read the queue unscoped.
+ *
+ * A predicate rather than a permission name: which permission, gate or role means "operator" is
+ * the application's decision, and hardcoding one here would make every deployment that names it
+ * differently patch this package.
+ */
+export interface JobAdminCheck {
+    (req: AbstractRequest, ctx: BasicContext<BasicConfig>): boolean | Promise<boolean>;
+}
+export interface JobHandlerOptions {
+    /** Which declared queue these handlers read. The context's sole queue when omitted. */
+    queue?: string;
+    /** The field inside `JobRecord.data` that names the owner. Defaults to `owner`. */
+    ownerField?: string;
+    /** The escape hatch — see {@link JobAdminCheck}. Nothing is unscoped without one. */
+    admin?: JobAdminCheck;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAA;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAE3E,MAAM,WAAW,MAAO,SAAQ,YAAY;IAC1C,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC,EAC1E,eAAe,EAAE,WAAW;CAAI;AAElC,gGAAgG;AAChG,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,MAAM,CAAA;IACZ,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,oBAAoB;IACnC,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B,CAAC,GAAG,EAAE,eAAe,EAAE,GAAG,EAAE,YAAY,CAAC,WAAW,CAAC,GAAG,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACnF;AAED,MAAM,WAAW,iBAAiB;IAChC,uFAAuF;IACvF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,mFAAmF;IACnF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,qFAAqF;IACrF,KAAK,CAAC,EAAE,aAAa,CAAA;CACtB"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/utils/index.d.ts

@@ -0,0 +1,3 @@
+export * from './owner.js';
+export * from './resource.js';
+//# sourceMappingURL=index.d.ts.map

package/build/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/build/utils/index.js

@@ -0,0 +1,3 @@
+export * from './owner.js';
+export * from './resource.js';
+//# sourceMappingURL=index.js.map

package/build/utils/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAA;AAC1B,cAAc,eAAe,CAAA"}

package/build/utils/owner.d.ts

@@ -0,0 +1,33 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context';
+import type { AbstractRequest } from '@owlmeans/entrypoint';
+import type { Criteria } from '@owlmeans/resource';
+import type { JobRecord } from '@owlmeans/queue';
+import type { JobHandlerOptions } from '../types.js';
+/**
+ * The subject a job is attributed to.
+ *
+ * Profile first, user second — the same pair `@owlmeans/server-socket` addresses a connection by,
+ * so a job enqueued for one profile of a multi-profile account is not visible to the others.
+ */
+export declare const jobOwnerOf: (req: AbstractRequest) => string | undefined;
+/**
+ * @throws {AuthorizationError} when the request carries no authenticated subject.
+ */
+export declare const requireJobOwner: (req: AbstractRequest) => string;
+export declare const ownerFieldOf: (opts?: JobHandlerOptions) => string;
+/** What one record says its owner is — the payload's own field, never a broker one. */
+export declare const ownerOf: (record: JobRecord, opts?: JobHandlerOptions) => unknown;
+/**
+ * Who this request reads the queue as: the owner every record must name, or `undefined` for a
+ * request that reads it unscoped.
+ *
+ * `undefined` is reachable only through {@link JobHandlerOptions.admin}. Absent an admin check
+ * every read is narrowed to the caller's own jobs and an anonymous request is refused, so a group
+ * wired with no options at all is scoped rather than open.
+ *
+ * @throws {AuthorizationError}
+ */
+export declare const jobViewer: <C extends BasicConfig, T extends BasicContext<C>>(req: AbstractRequest, ctx: T, opts?: JobHandlerOptions) => Promise<string | undefined>;
+/** The criteria one viewer reads the queue through; nothing to add when they read it unscoped. */
+export declare const jobScope: (viewer: string | undefined, opts?: JobHandlerOptions) => Criteria<JobRecord>;
+//# sourceMappingURL=owner.d.ts.map

package/build/utils/owner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.d.ts","sourceRoot":"","sources":["../../src/utils/owner.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AAE3D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAA;AAClD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD;;;;;GAKG;AACH,eAAO,MAAM,UAAU,QAAS,eAAe,KAAG,MAAM,GAAG,SAClB,CAAA;AAEzC;;GAEG;AACH,eAAO,MAAM,eAAe,QAAS,eAAe,KAAG,MAOtD,CAAA;AAED,eAAO,MAAM,YAAY,UAAW,iBAAiB,KAAG,MACf,CAAA;AAEzC,uFAAuF;AACvF,eAAO,MAAM,OAAO,WAAY,SAAS,SAAS,iBAAiB,KAAG,OACM,CAAA;AAE5E;;;;;;;;;GASG;AACH,eAAO,MAAM,SAAS,GAAU,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,OACzE,eAAe,OAAO,CAAC,SAAS,iBAAiB,KACrD,OAAO,CAAC,MAAM,GAAG,SAAS,CAM5B,CAAA;AAED,kGAAkG;AAClG,eAAO,MAAM,QAAQ,WACX,MAAM,GAAG,SAAS,SAAS,iBAAiB,KACnD,QAAQ,CAAC,SAAS,CAAqE,CAAA"}

package/build/utils/owner.js

@@ -0,0 +1,41 @@
+import { AuthorizationError } from '@owlmeans/auth';
+import { DEFAULT_OWNER_FIELD } from '../consts.js';
+/**
+ * The subject a job is attributed to.
+ *
+ * Profile first, user second — the same pair `@owlmeans/server-socket` addresses a connection by,
+ * so a job enqueued for one profile of a multi-profile account is not visible to the others.
+ */
+export const jobOwnerOf = (req) => req.auth?.profileId ?? req.auth?.userId;
+/**
+ * @throws {AuthorizationError} when the request carries no authenticated subject.
+ */
+export const requireJobOwner = (req) => {
+    const owner = jobOwnerOf(req);
+    if (owner == null || owner === '') {
+        throw new AuthorizationError();
+    }
+    return owner;
+};
+export const ownerFieldOf = (opts) => opts?.ownerField ?? DEFAULT_OWNER_FIELD;
+/** What one record says its owner is — the payload's own field, never a broker one. */
+export const ownerOf = (record, opts) => record.data?.[ownerFieldOf(opts)];
+/**
+ * Who this request reads the queue as: the owner every record must name, or `undefined` for a
+ * request that reads it unscoped.
+ *
+ * `undefined` is reachable only through {@link JobHandlerOptions.admin}. Absent an admin check
+ * every read is narrowed to the caller's own jobs and an anonymous request is refused, so a group
+ * wired with no options at all is scoped rather than open.
+ *
+ * @throws {AuthorizationError}
+ */
+export const jobViewer = async (req, ctx, opts) => {
+    if (opts?.admin != null && await opts.admin(req, ctx)) {
+        return undefined;
+    }
+    return requireJobOwner(req);
+};
+/** The criteria one viewer reads the queue through; nothing to add when they read it unscoped. */
+export const jobScope = (viewer, opts) => viewer == null ? {} : { [`data.${ownerFieldOf(opts)}`]: viewer };
+//# sourceMappingURL=owner.js.map

package/build/utils/owner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"owner.js","sourceRoot":"","sources":["../../src/utils/owner.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAGnD,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAA;AAGlD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,GAAoB,EAAsB,EAAE,CACrE,GAAG,CAAC,IAAI,EAAE,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAA;AAEzC;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,GAAoB,EAAU,EAAE;IAC9D,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;IAC7B,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;QAClC,MAAM,IAAI,kBAAkB,EAAE,CAAA;IAChC,CAAC;IAED,OAAO,KAAK,CAAA;AACd,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,IAAwB,EAAU,EAAE,CAC/D,IAAI,EAAE,UAAU,IAAI,mBAAmB,CAAA;AAEzC,uFAAuF;AACvF,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,MAAiB,EAAE,IAAwB,EAAW,EAAE,CAC7E,MAAM,CAAC,IAA4C,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,CAAA;AAE5E;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,KAAK,EAC5B,GAAoB,EAAE,GAAM,EAAE,IAAwB,EACzB,EAAE;IAC/B,IAAI,IAAI,EAAE,KAAK,IAAI,IAAI,IAAI,MAAM,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,GAAgC,CAAC,EAAE,CAAC;QACnF,OAAO,SAAS,CAAA;IAClB,CAAC;IAED,OAAO,eAAe,CAAC,GAAG,CAAC,CAAA;AAC7B,CAAC,CAAA;AAED,kGAAkG;AAClG,MAAM,CAAC,MAAM,QAAQ,GAAG,CACtB,MAA0B,EAAE,IAAwB,EAC/B,EAAE,CAAC,MAAM,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,YAAY,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,MAAM,EAAE,CAAA"}

package/build/utils/resource.d.ts

@@ -0,0 +1,23 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context';
+import type { JobRecord, QueueResource } from '@owlmeans/queue';
+import type { JobHandlerOptions } from '../types.js';
+/**
+ * The queue these handlers read.
+ *
+ * Named by the declaration or, with nothing named, the context's sole declared queue — which
+ * `ctx.jobs()` refuses to guess once a second queue exists, so an app that grows one is told to
+ * name it rather than quietly served the wrong backlog.
+ */
+export declare const jobsOf: <D = unknown, R = unknown>(ctx: BasicContext<BasicConfig>, opts?: JobHandlerOptions) => QueueResource<D, R>;
+/** Does this viewer own that record? An unscoped viewer (`undefined`) owns everything. */
+export declare const owns: (record: JobRecord, viewer: string | undefined, opts?: JobHandlerOptions) => boolean;
+/**
+ * One job, as this viewer is allowed to see it.
+ *
+ * A job that exists but belongs to someone else answers exactly as an absent one does: telling an
+ * unauthorized caller apart from a wrong id is what turns an id space into an enumeration oracle.
+ *
+ * @throws {UnknownJob}
+ */
+export declare const readOwnedJob: <D = unknown, R = unknown>(resource: QueueResource<D, R>, id: string, viewer: string | undefined, opts?: JobHandlerOptions) => Promise<JobRecord<D, R>>;
+//# sourceMappingURL=resource.d.ts.map

package/build/utils/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/utils/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAClE,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAE/D,OAAO,KAAK,EAAW,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAG7D;;;;;;GAMG;AACH,eAAO,MAAM,MAAM,GAAI,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,OACxC,YAAY,CAAC,WAAW,CAAC,SAAS,iBAAiB,KACvD,aAAa,CAAC,CAAC,EAAE,CAAC,CAAwD,CAAA;AAE7E,0FAA0F;AAC1F,eAAO,MAAM,IAAI,WACP,SAAS,UAAU,MAAM,GAAG,SAAS,SAAS,iBAAiB,KACtE,OAA6D,CAAA;AAEhE;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,GAAU,CAAC,GAAG,OAAO,EAAE,CAAC,GAAG,OAAO,YAC/C,aAAa,CAAC,CAAC,EAAE,CAAC,CAAC,MAAM,MAAM,UAAU,MAAM,GAAG,SAAS,SAAS,iBAAiB,KAC9F,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAOzB,CAAA"}

package/build/utils/resource.js

@@ -0,0 +1,28 @@
+import { UnknownJob } from '@owlmeans/queue';
+import { ownerOf } from './owner.js';
+/**
+ * The queue these handlers read.
+ *
+ * Named by the declaration or, with nothing named, the context's sole declared queue — which
+ * `ctx.jobs()` refuses to guess once a second queue exists, so an app that grows one is told to
+ * name it rather than quietly served the wrong backlog.
+ */
+export const jobsOf = (ctx, opts) => ctx.jobs(opts?.queue);
+/** Does this viewer own that record? An unscoped viewer (`undefined`) owns everything. */
+export const owns = (record, viewer, opts) => viewer == null || ownerOf(record, opts) === viewer;
+/**
+ * One job, as this viewer is allowed to see it.
+ *
+ * A job that exists but belongs to someone else answers exactly as an absent one does: telling an
+ * unauthorized caller apart from a wrong id is what turns an id space into an enumeration oracle.
+ *
+ * @throws {UnknownJob}
+ */
+export const readOwnedJob = async (resource, id, viewer, opts) => {
+    const record = await resource.load(id);
+    if (record == null || !owns(record, viewer, opts)) {
+        throw new UnknownJob(`${resource.queue}:${id}`);
+    }
+    return record;
+};
+//# sourceMappingURL=resource.js.map

package/build/utils/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/utils/resource.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAE5C,OAAO,EAAE,OAAO,EAAE,MAAM,YAAY,CAAA;AAEpC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,GAA8B,EAAE,IAAwB,EACnC,EAAE,CAAE,GAA0B,CAAC,IAAI,CAAO,IAAI,EAAE,KAAK,CAAC,CAAA;AAE7E,0FAA0F;AAC1F,MAAM,CAAC,MAAM,IAAI,GAAG,CAClB,MAAiB,EAAE,MAA0B,EAAE,IAAwB,EAC9D,EAAE,CAAC,MAAM,IAAI,IAAI,IAAI,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,MAAM,CAAA;AAEhE;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,QAA6B,EAAE,EAAU,EAAE,MAA0B,EAAE,IAAwB,EACrE,EAAE;IAC5B,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,CAAA;IACtC,IAAI,MAAM,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,UAAU,CAAC,GAAG,QAAQ,CAAC,KAAK,IAAI,EAAE,EAAE,CAAC,CAAA;IACjD,CAAC;IAED,OAAO,MAAM,CAAA;AACf,CAAC,CAAA"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@owlmeans/server-job",
+  "version": "0.1.18-rc.0",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 354 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "devDependencies": {
+    "@owlmeans/dep-config": "workspace:*",
+    "@types/node": "^26.1.0",
+    "nodemon": "^3.1.14",
+    "typescript": "^7.0.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@owlmeans/auth": "^0.1.18-rc.9",
+    "@owlmeans/auth-common": "^0.1.18-rc.13",
+    "@owlmeans/context": "^0.1.18-rc.8",
+    "@owlmeans/entrypoint": "^0.1.18-rc.11",
+    "@owlmeans/queue": "^0.1.18-rc.9",
+    "@owlmeans/resource": "^0.1.18-rc.9",
+    "@owlmeans/route": "^0.1.18-rc.9",
+    "@owlmeans/server-api": "^0.1.18-rc.17",
+    "@owlmeans/server-context": "^0.1.18-rc.12",
+    "@owlmeans/server-entrypoint": "^0.1.18-rc.11",
+    "@owlmeans/server-socket": "^0.1.18-rc.18",
+    "@owlmeans/socket": "^0.1.18-rc.9"
+  }
+}

package/src/actions/cancel.ts

@@ -0,0 +1,26 @@
+import { handleParams } from '@owlmeans/server-api'
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint'
+import type { JobHandlerOptions } from '../types.js'
+import { jobViewer, jobsOf, readOwnedJob } from '../utils/index.js'
+
+/**
+ * Cancel a job and answer with what was cancelled.
+ *
+ * Cancellation IS deletion in the queue contract — the job and its children leave the broker — so
+ * a job already finished cancels to its final record and one already gone answers `UnknownJob`.
+ * Nothing here interrupts a processor that is mid-run; a job holding a lock keeps it until the
+ * processor notices its own `signal`.
+ *
+ * @throws {UnknownJob}
+ */
+export const cancelJob = (
+  opts?: JobHandlerOptions
+): RefedEntrypointHandler<AbstractResponse<any>> =>
+  handleParams<{ id: string }>(async ({ id }, ctx, req) => {
+    const resource = jobsOf(ctx, opts)
+    // Read first: `take` cannot tell whose job it removed, so ownership is settled before it.
+    await readOwnedJob(resource, id, await jobViewer(req, ctx, opts), opts)
+
+    return await resource.take(id)
+  })

package/src/actions/get.ts

@@ -0,0 +1,19 @@
+import { handleParams } from '@owlmeans/server-api'
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint'
+import type { JobHandlerOptions } from '../types.js'
+import { jobViewer, jobsOf, readOwnedJob } from '../utils/index.js'
+
+/**
+ * One job.
+ *
+ * @throws {UnknownJob} for an id that is absent AND for one that belongs to someone else.
+ */
+export const getJob = (
+  opts?: JobHandlerOptions
+): RefedEntrypointHandler<AbstractResponse<any>> =>
+  handleParams<{ id: string }>(async ({ id }, ctx, req) => {
+    const resource = jobsOf(ctx, opts)
+
+    return await readOwnedJob(resource, id, await jobViewer(req, ctx, opts), opts)
+  })

package/src/actions/index.ts

@@ -0,0 +1,4 @@
+export * from './list.js'
+export * from './get.js'
+export * from './cancel.js'
+export * from './watch.js'

package/src/actions/list.ts

@@ -0,0 +1,36 @@
+import { handleRequest } from '@owlmeans/server-api'
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint'
+import type { Criteria } from '@owlmeans/resource'
+import type { JobRecord } from '@owlmeans/queue'
+import type { JobState } from '@owlmeans/queue'
+import { DEFAULT_JOB_SORT } from '../consts.js'
+import type { JobHandlerOptions, JobListQuery } from '../types.js'
+import { jobScope, jobViewer, jobsOf } from '../utils/index.js'
+
+/**
+ * The caller's jobs, newest first.
+ *
+ * Paging is opt-in: a `page` without a `size` is refused by the queue resource rather than
+ * silently windowed, because a broker has no default page size to count against. The state and
+ * name filters go through the same criteria language as every other resource, so a filter written
+ * for this list means the same thing applied to the store the browser holds.
+ */
+export const listJobs = (
+  opts?: JobHandlerOptions
+): RefedEntrypointHandler<AbstractResponse<any>> => handleRequest(async (req, ctx) => {
+  const resource = jobsOf(ctx, opts)
+  const viewer = await jobViewer(req, ctx, opts)
+  const query = (req.query ?? {}) as JobListQuery
+
+  const where: Criteria<JobRecord> = {
+    ...jobScope(viewer, opts),
+    ...(query.state != null ? { state: query.state as JobState } : {}),
+    ...(query.name != null ? { name: query.name } : {}),
+  }
+
+  return await resource.list(where, {
+    sort: [{ field: DEFAULT_JOB_SORT, order: 'desc' }],
+    ...(query.size != null ? { size: query.size, page: query.page ?? 0 } : {}),
+  })
+})

package/src/actions/watch.ts

@@ -0,0 +1,66 @@
+import { handleConnection } from '@owlmeans/server-socket'
+import type { AbstractResponse } from '@owlmeans/entrypoint'
+import type { RefedEntrypointHandler } from '@owlmeans/server-entrypoint'
+import type { EventMessage } from '@owlmeans/socket'
+import { MessageType } from '@owlmeans/socket'
+import type { JobEvent } from '@owlmeans/queue'
+import { JOB_EVENT } from '../consts.js'
+import type { JobHandlerOptions } from '../types.js'
+import { jobViewer, jobsOf, owns } from '../utils/index.js'
+
+/**
+ * Push this caller's job lifecycle events down a socket.
+ *
+ * The frames are `JobEvent`s exactly as the queue publishes them, under the {@link JOB_EVENT}
+ * event name — no shape of this package's own, so a client applies them with the contract types.
+ *
+ * **A `JobEvent` carries no owner**, so each one is attributed by reading its job back, and the
+ * ids that answered are remembered for the life of the connection. A queue configured with
+ * `removeOnComplete` therefore loses its completion events here: the record they would be
+ * attributed by is gone by the time the event arrives, and an unattributable event is dropped
+ * rather than fanned out to everyone. Leave completed jobs in place on any queue that is watched.
+ */
+export const watchJobs = (
+  opts?: JobHandlerOptions
+): RefedEntrypointHandler<AbstractResponse<any>> => handleConnection(async (conn, ctx, req) => {
+  const resource = jobsOf(ctx, opts)
+  const viewer = await jobViewer(req, ctx, opts)
+  const mine = new Set<string>()
+
+  const attributable = async (event: JobEvent): Promise<boolean> => {
+    if (viewer == null || mine.has(event.id)) {
+      return true
+    }
+    const record = await resource.load(event.id)
+    if (record == null || !owns(record, viewer, opts)) {
+      return false
+    }
+    mine.add(event.id)
+
+    return true
+  }
+
+  const unsubscribe = await resource.subscribe(async event => {
+    try {
+      if (await attributable(event)) {
+        await conn.notify(JOB_EVENT, event)
+      }
+    } catch (e) {
+      console.error('Job watch notify error:', e)
+    }
+  })
+
+  conn.listen(async message => {
+    if (typeof message !== 'object') {
+      return
+    }
+    const msg = message as EventMessage<void>
+    if (msg.type === MessageType.System && msg.event === 'close') {
+      try {
+        await unsubscribe()
+      } catch (e) {
+        console.error('Job watch unsubscribe error:', e)
+      }
+    }
+  })
+})

package/src/consts.ts

@@ -0,0 +1,28 @@
+/**
+ * The alias root a target app gets when its declaration names none, and the path segment the
+ * group answers under.
+ */
+export const DEFAULT_JOB_ROOT = 'jobs'
+export const DEFAULT_JOB_PATH = '/jobs'
+
+/**
+ * Where the owner is recorded inside a job's payload.
+ *
+ * A `JobRecord` has no owner column — the broker keeps only what the contract declares — so the
+ * producer writes the subject into the job's own `data`, and every read here filters on
+ * `data.<field>`. Change it per declaration when the app's payloads already name the subject
+ * something else.
+ */
+export const DEFAULT_OWNER_FIELD = 'owner'
+
+/**
+ * The socket event a `JobEvent` frame is pushed under.
+ *
+ * This name, and the `<root>:<verb>` alias shape in `entrypoints.ts`, are the whole contract
+ * between this package and `@owlmeans/client-job` — the two halves cannot share a module without
+ * dragging fastify into a browser bundle, so they each state it and the skills pin it.
+ */
+export const JOB_EVENT = 'job-event'
+
+/** Newest first: a job list is read to see what is happening now. */
+export const DEFAULT_JOB_SORT = 'createdAt'