IF Commons GitHub

schedule

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-system FR-017

The operating system's own scheduled job, installed and removed (commons 0001-system FR-017): installJob plans the job with the kernel's planJob, writes its files under the home folder (making their folders, with their modes) and runs the commands that load it; removeJob runs the commands that unload it, removes its files and runs what follows (systemd's daemon-reload). Each file and each command is reported as an outcome, and the first failure that matters is a typed error carrying the outcomes until then; a command marked mayFail (nothing to unload) never stops the rest. The scheduler, the home folder, the user's id and the program that runs a command are parameters, defaulting to this computer's (build.os, homeDir(), uid(), run), so a test plans and installs any scheduler's job in a temporary folder with a fake runner, and no real systemctl, launchctl or schtasks runs. Taken from Stolos's src/archon/export/schedule.ts (installJob, uninstallJob), which took its file and command functions as dependencies and threw; here the files go through ./fs.ts, the commands through ./proc.ts or a given runner, and errors are values.

import { jobName, schedule } from "./job-plan.ts";
import { installJob } from "./schedule.ts";
const name = jobName("backup");
const when = schedule({ kind: "weekly", day: "sun", hour: 3, minute: 30 });
if (name.kind === "ok" && when.kind === "ok") {
  const r = await installJob({ name: name.value, owner: { domain: "org.example", folder: "Example" }, argv: ["/usr/bin/backup"], workdir: "/srv", when: when.value });
  if (r.kind === "err") console.error(r.error.kind);
}

Source: commons/system/src/schedule.ts

6 of 20 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

jobsnamespace
namespace jobs
jobs.StepResulttypeno test imports it
type StepResult = { readonly code: number; readonly output: string };

What a command did: its exit status (127 where it could not be started) and what it said (standard error, else standard output, trimmed).

jobs.StepRunnertypeno test imports it
type StepRunner = (argv: readonly string[]) => Promise<StepResult>;

Runs one command by its argument vector; the default runs it with ./proc.ts, a test gives a fake. Never rejects for a failure of the command.

jobs.runStepconstno test imports it
const runStep: StepRunner

The default runner: the program run with run, never through a shell; one that cannot be started gives status 127 and the reason.

jobs.JobOptionstypeno test imports it
type JobOptions = { /** The scheduler (`build.os` by default). */ readonly os?: SchedulerOs; /** The user's home f… (411 characters)
type JobOptions = {
  /** The scheduler (`build.os` by default). */
  readonly os?: SchedulerOs;
  /** The user's home folder, under which the files go (`homeDir()` by default). */
  readonly home?: string;
  /** The user's numeric id, for launchctl's `gui/<uid>` domain (`uid()` by default). */
  readonly uid?: number;
  /** What runs each command (`runStep` by default). */
  readonly runner?: StepRunner;
};

Where and how to install or remove a job; every field defaults to this computer.

jobs.Outcometypeno test imports it
type Outcome =
  | { readonly kind: "wrote"; readonly path: string }
  | { readonly kind: "removed"; readonly path: string; readonly existed: boolean }
  | { readonly kind: "ran"; readonly argv: readonly string[]; readonly code: number; readonly output: string; readonly mayFail: boolean };

One thing done: a file written or removed (its absolute path, and whether it was there), or a command run (its status and output).

jobs.JobReporttypeno test imports it
type JobReport = { readonly plan: JobPlan; readonly outcomes: readonly Outcome[] };

A job installed or removed: its plan and what was done, in order.

jobs.JobErrortypeno test imports it
type JobError = | { readonly kind: "unsupported"; readonly os: string; readonly outcomes: readonly Outcome[] } | { r… (638 characters)
type JobError =
  | { readonly kind: "unsupported"; readonly os: string; readonly outcomes: readonly Outcome[] }
  | { readonly kind: "plan"; readonly error: ScheduleError; readonly outcomes: readonly Outcome[] }
  | { readonly kind: "write"; readonly path: string; readonly message: string; readonly outcomes: readonly Outcome[] }
  | { readonly kind: "remove"; readonly path: string; readonly message: string; readonly outcomes: readonly Outcome[] }
  | {
      readonly kind: "step";
      readonly argv: readonly string[];
      readonly code: number;
      readonly output: string;
      readonly outcomes: readonly Outcome[];
    };

Why installing or removing stopped, with what was done until then.

jobs.formatJobErrorfunctionno test imports it
function formatJobError(e: JobError): string

A job error as one line.

jobs.installJobfunctionno test imports it
function installJob(job: JobSpec, options?: JobOptions): Promise<Result<JobReport, JobError>>

A job scheduled: planned, its files written (their folders made, their modes set), then the commands that load it run.

jobs.removeJobfunctionno test imports it
function removeJob(job: JobSpec, options?: JobOptions): Promise<Result<JobReport, JobError>>

A job unscheduled: the commands that unload it run, its files removed (one already gone is no error), then what follows run.

StepResulttypeno test imports it
type StepResult = { readonly code: number; readonly output: string };

What a command did: its exit status (127 where it could not be started) and what it said (standard error, else standard output, trimmed).

StepRunnertype
type StepRunner = (argv: readonly string[]) => Promise<StepResult>;

Runs one command by its argument vector; the default runs it with ./proc.ts, a test gives a fake. Never rejects for a failure of the command.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

runStepconstno test imports it
const runStep: StepRunner

The default runner: the program run with run, never through a shell; one that cannot be started gives status 127 and the reason.

JobOptionstype
type JobOptions = { /** The scheduler (`build.os` by default). */ readonly os?: SchedulerOs; /** The user's home f… (411 characters)
type JobOptions = {
  /** The scheduler (`build.os` by default). */
  readonly os?: SchedulerOs;
  /** The user's home folder, under which the files go (`homeDir()` by default). */
  readonly home?: string;
  /** The user's numeric id, for launchctl's `gui/<uid>` domain (`uid()` by default). */
  readonly uid?: number;
  /** What runs each command (`runStep` by default). */
  readonly runner?: StepRunner;
};

Where and how to install or remove a job; every field defaults to this computer.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Outcometype
type Outcome =
  | { readonly kind: "wrote"; readonly path: string }
  | { readonly kind: "removed"; readonly path: string; readonly existed: boolean }
  | { readonly kind: "ran"; readonly argv: readonly string[]; readonly code: number; readonly output: string; readonly mayFail: boolean };

One thing done: a file written or removed (its absolute path, and whether it was there), or a command run (its status and output).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

JobReporttypeno test imports it
type JobReport = { readonly plan: JobPlan; readonly outcomes: readonly Outcome[] };

A job installed or removed: its plan and what was done, in order.

JobErrortypeno test imports it
type JobError = | { readonly kind: "unsupported"; readonly os: string; readonly outcomes: readonly Outcome[] } | { r… (638 characters)
type JobError =
  | { readonly kind: "unsupported"; readonly os: string; readonly outcomes: readonly Outcome[] }
  | { readonly kind: "plan"; readonly error: ScheduleError; readonly outcomes: readonly Outcome[] }
  | { readonly kind: "write"; readonly path: string; readonly message: string; readonly outcomes: readonly Outcome[] }
  | { readonly kind: "remove"; readonly path: string; readonly message: string; readonly outcomes: readonly Outcome[] }
  | {
      readonly kind: "step";
      readonly argv: readonly string[];
      readonly code: number;
      readonly output: string;
      readonly outcomes: readonly Outcome[];
    };

Why installing or removing stopped, with what was done until then.

formatJobErrorfunction
function formatJobError(e: JobError): string

A job error as one line.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

installJobfunction
function installJob(job: JobSpec, options?: JobOptions): Promise<Result<JobReport, JobError>>

A job scheduled: planned, its files written (their folders made, their modes set), then the commands that load it run.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

removeJobfunction
function removeJob(job: JobSpec, options?: JobOptions): Promise<Result<JobReport, JobError>>

A job unscheduled: the commands that unload it run, its files removed (one already gone is no error), then what follows run.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.