jobsnamespacenamespace jobsThe 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);
}jobsnamespacenamespace jobsjobs.StepResulttypeno test imports ittype 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 ittype 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 itconst runStep: StepRunnerThe 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 ittype 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 ittype 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 ittype 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 ittype 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 itfunction formatJobError(e: JobError): stringA job error as one line.
jobs.installJobfunctionno test imports itfunction 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 itfunction 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 ittype 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).
StepRunnertypetype 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.
runStepconstno test imports itconst runStep: StepRunnerThe default runner: the program run with run, never through a shell; one that cannot be started gives status 127 and the reason.
JobOptionstypetype 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.
Outcometypetype 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).
JobReporttypeno test imports ittype JobReport = { readonly plan: JobPlan; readonly outcomes: readonly Outcome[] };A job installed or removed: its plan and what was done, in order.
JobErrortypeno test imports ittype 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.
formatJobErrorfunctionfunction formatJobError(e: JobError): stringA job error as one line.
installJobfunctionfunction 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.
removeJobfunctionfunction 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.