@owlmeans/server-job 0.1.18-rc.0

package/src/entrypoints.ts

@@ -0,0 +1,56 @@
+import { entrypoint, filter, guard, query } from '@owlmeans/entrypoint'
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import { backend, route, RouteMethod, socket } from '@owlmeans/route'
+import type { RouteOptions } from '@owlmeans/route'
+import { DEFAULT_GUARD } from '@owlmeans/auth-common'
+import { DEFAULT_JOB_PATH } from './consts.js'
+import { JobListQuerySchema } from './schemas.js'
+import type { JobEntrypointAliases, JobEntrypointOptions } from './types.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: string): JobEntrypointAliases => ({
+  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: string, opts?: JobEntrypointOptions
+): CommonEntrypoint[] => {
+  const aliases = jobEntrypointAliases(root)
+  const base: Partial<RouteOptions> = {
+    ...(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))),
+  ]
+}

package/src/helper.ts

@@ -0,0 +1,28 @@
+import { elevate } from '@owlmeans/server-entrypoint'
+import type { ServerEntrypoint } from '@owlmeans/server-entrypoint'
+import type { CommonEntrypoint } from '@owlmeans/entrypoint'
+import { jobEntrypointAliases } from './entrypoints.js'
+import { cancelJob, getJob, listJobs, watchJobs } from './actions/index.js'
+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 const serveJobEntrypoints = <R>(
+  entrypoints: (CommonEntrypoint | ServerEntrypoint<R>)[], root: string, opts?: JobHandlerOptions
+): ServerEntrypoint<R>[] => {
+  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))
+}

package/src/index.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'

package/src/schemas.ts

@@ -0,0 +1,19 @@
+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 const JobListQuerySchema: JSONSchemaType<JobListQuery> = {
+  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,
+}

package/src/types.ts

@@ -0,0 +1,66 @@
+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
+}

package/src/utils/index.ts

@@ -0,0 +1,2 @@
+export * from './owner.js'
+export * from './resource.js'

package/src/utils/owner.ts

@@ -0,0 +1,60 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { AbstractRequest } from '@owlmeans/entrypoint'
+import { AuthorizationError } from '@owlmeans/auth'
+import type { Criteria } from '@owlmeans/resource'
+import type { JobRecord } from '@owlmeans/queue'
+import { DEFAULT_OWNER_FIELD } from '../consts.js'
+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 const jobOwnerOf = (req: AbstractRequest): string | undefined =>
+  req.auth?.profileId ?? req.auth?.userId
+
+/**
+ * @throws {AuthorizationError} when the request carries no authenticated subject.
+ */
+export const requireJobOwner = (req: AbstractRequest): string => {
+  const owner = jobOwnerOf(req)
+  if (owner == null || owner === '') {
+    throw new AuthorizationError()
+  }
+
+  return owner
+}
+
+export const ownerFieldOf = (opts?: JobHandlerOptions): string =>
+  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: JobRecord, opts?: JobHandlerOptions): unknown =>
+  (record.data as Record<string, unknown> | undefined)?.[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 <C extends BasicConfig, T extends BasicContext<C>>(
+  req: AbstractRequest, ctx: T, opts?: JobHandlerOptions
+): Promise<string | undefined> => {
+  if (opts?.admin != null && await opts.admin(req, ctx as BasicContext<BasicConfig>)) {
+    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: string | undefined, opts?: JobHandlerOptions
+): Criteria<JobRecord> => viewer == null ? {} : { [`data.${ownerFieldOf(opts)}`]: viewer }

package/src/utils/resource.ts

@@ -0,0 +1,40 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context'
+import type { JobRecord, QueueResource } from '@owlmeans/queue'
+import { UnknownJob } from '@owlmeans/queue'
+import type { Context, JobHandlerOptions } from '../types.js'
+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 = <D = unknown, R = unknown>(
+  ctx: BasicContext<BasicConfig>, opts?: JobHandlerOptions
+): QueueResource<D, R> => (ctx as unknown as Context).jobs<D, R>(opts?.queue)
+
+/** Does this viewer own that record? An unscoped viewer (`undefined`) owns everything. */
+export const owns = (
+  record: JobRecord, viewer: string | undefined, opts?: JobHandlerOptions
+): boolean => 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 <D = unknown, R = unknown>(
+  resource: QueueResource<D, R>, id: string, viewer: string | undefined, opts?: JobHandlerOptions
+): Promise<JobRecord<D, R>> => {
+  const record = await resource.load(id)
+  if (record == null || !owns(record, viewer, opts)) {
+    throw new UnknownJob(`${resource.queue}:${id}`)
+  }
+
+  return record
+}

package/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "extends": [
+    "@owlmeans/dep-config/tsconfig.base.json",
+    "@owlmeans/dep-config/tsconfig.node.json"
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/",
+    "outDir": "./build/"
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./tests/**/*",
+    "./*.ts"
+  ]
+}