@artian-techs/adonis-orbit 0.1.0

package/build/src/controllers/dashboard_controller.js

@@ -0,0 +1,341 @@
+import app from '@adonisjs/core/services/app';
+import db from '@adonisjs/lucid/services/db';
+import edge from 'edge.js';
+import { DateTime } from 'luxon';
+import { favicon, logo } from '../logo.js';
+import JobRun, { JobRunStatus } from '../models/job_run.js';
+import SilencedJob from '../models/silenced_job.js';
+import { retryRun } from '../retry.js';
+const PER_PAGE = 50;
+/** The two modes that a person chooses between. */
+const THEMES = ['light', 'dark'];
+/** Where the choice of the mode is held, and for how long. */
+const THEME_COOKIE = 'orbit_theme';
+const THEME_AGE = '1y';
+/** How far back the metrics read. */
+const METRICS_WINDOW = { hours: 24 };
+const STATUS_LABELS = {
+    [JobRunStatus.PENDING]: 'Pending',
+    [JobRunStatus.RUNNING]: 'Running',
+    [JobRunStatus.RETRYING]: 'Retrying',
+    [JobRunStatus.COMPLETED]: 'Completed',
+    [JobRunStatus.FAILED]: 'Failed',
+};
+/**
+ * The drawings of the side menu. They are written here, and the page prints
+ * them as they are.
+ */
+const ICONS = {
+    overview: '<rect x="3" y="3" width="7" height="9"/><rect x="14" y="3" width="7" height="5"/><rect x="14" y="12" width="7" height="9"/><rect x="3" y="16" width="7" height="5"/>',
+    pending: '<circle cx="12" cy="12" r="9"/><path d="M12 7v5l3 2"/>',
+    running: '<circle cx="12" cy="12" r="9"/><path d="M10 8.5l5 3.5-5 3.5z"/>',
+    retrying: '<path d="M21 12a9 9 0 1 1-3-6.7"/><path d="M21 4v5h-5"/>',
+    completed: '<circle cx="12" cy="12" r="9"/><path d="M8 12.5l3 3 5-6"/>',
+    failed: '<circle cx="12" cy="12" r="9"/><path d="M12 7v6"/><path d="M12 16.5v.5"/>',
+    silenced: '<path d="M18 8a6 6 0 0 0-9.3-5"/><path d="M6 9v5l-2 3h13"/><path d="M10.5 20a2 2 0 0 0 3 0"/><path d="M3 3l18 18"/>',
+    metrics: '<path d="M4 20V10"/><path d="M10 20V4"/><path d="M16 20v-7"/><path d="M22 20H2"/>',
+};
+/**
+ * The page that shows what the queue does.
+ *
+ * It reads the table, not Redis: a job that ended left Redis, and the table
+ * keeps it. The page is served by the API itself, outside the front, thus it
+ * answers even when the front is down.
+ */
+export default class DashboardController {
+    #silenced;
+    /**
+     * Everything the queue did, and the four numbers that say how it goes.
+     *
+     * The side menu leads here with a status. A row that was asked again leads
+     * here with the identifier of the job that answered. Without one and without
+     * the other, the page shows the numbers and the last jobs of every status.
+     */
+    async index(ctx) {
+        const { request } = ctx;
+        const status = request.input('status');
+        const job = request.input('job');
+        const page = Number(request.input('page', 1)) || 1;
+        const silenced = await this.#silencedNames();
+        const query = JobRun.query().orderBy('id', 'desc');
+        if (status) {
+            query.where('status', status);
+        }
+        /**
+         * A person who asks for one job asks for that job, thus a class that is
+         * silenced answers here as any other class.
+         */
+        if (job) {
+            query.where('jobId', job);
+        }
+        else if (silenced.length > 0) {
+            query.whereNotIn('name', silenced);
+        }
+        const runs = await query.paginate(page, PER_PAGE);
+        const answers = await this.#answers(runs.all());
+        const alone = Boolean(status || job);
+        return this.#render(ctx, 'index', {
+            active: status || 'overview',
+            title: this.#title(status, job),
+            showStats: !alone,
+            stats: alone ? null : await this.#stats(),
+            status: status ?? '',
+            rows: runs.all().map((run) => this.#row(run, silenced, answers)),
+            page: runs.currentPage,
+            lastPage: runs.lastPage,
+            total: runs.total,
+        });
+    }
+    /** What the page is called. */
+    #title(status, job) {
+        if (job) {
+            return 'One job';
+        }
+        return status ? STATUS_LABELS[status] : 'Overview';
+    }
+    /**
+     * What became of the jobs that were asked again.
+     *
+     * One reading answers for the whole page: a row that names a new job reads
+     * the status of that job beside it, and leads to it.
+     */
+    async #answers(runs) {
+        const asked = runs.map((run) => run.retriedJobId).filter((id) => id !== null);
+        if (asked.length === 0) {
+            return new Map();
+        }
+        const answers = await JobRun.query().whereIn('jobId', asked).select('jobId', 'status');
+        return new Map(answers.map((run) => [run.jobId, run.status]));
+    }
+    /**
+     * The classes that the lists leave out.
+     *
+     * Their work goes on and their trace is written. Take a name away from here
+     * and everything it did comes back, including what it did while it was
+     * silent.
+     */
+    async silenced(ctx) {
+        const silenced = await SilencedJob.query().orderBy('name', 'asc');
+        return this.#render(ctx, 'silenced', {
+            active: 'silenced',
+            title: 'Silenced jobs',
+            names: silenced.map((row) => row.name),
+        });
+    }
+    /**
+     * What each class and each queue cost in the last day.
+     *
+     * A job that takes long, or that fails often, is read here before it is read
+     * in the list.
+     */
+    async metrics(ctx) {
+        const since = DateTime.now().minus(METRICS_WINDOW).toJSDate();
+        return this.#render(ctx, 'metrics', {
+            active: 'metrics',
+            title: 'Metrics',
+            hours: METRICS_WINDOW.hours,
+            byJob: await this.#metricsBy('name', since),
+            byQueue: await this.#metricsBy('queue', since),
+        });
+    }
+    /**
+     * Ask the queue for one job again.
+     *
+     * The row that answers stays where it is. The new job opens a row of its
+     * own, thus the page shows the two.
+     */
+    async retry({ params, response }) {
+        const run = await JobRun.findOrFail(params.id);
+        await retryRun(run);
+        return response.redirect().back();
+    }
+    /**
+     * Read the page in the light, or in the dark.
+     *
+     * The choice is held in a cookie, thus the page carries it on the next
+     * request and no script reads it. A person who chose nothing reads the mode
+     * of their machine.
+     */
+    async theme({ params, response }) {
+        const theme = String(params.theme);
+        if (!THEMES.includes(theme)) {
+            return response.notFound({ success: false, error: 'Not found' });
+        }
+        response.plainCookie(THEME_COOKIE, theme, {
+            path: this.#config().path,
+            maxAge: THEME_AGE,
+            httpOnly: false,
+            sameSite: 'lax',
+        });
+        return response.redirect().back();
+    }
+    /** Take a class out of the lists, or put it back. */
+    async silence({ params, response }) {
+        const name = String(params.name);
+        const silenced = await SilencedJob.findBy('name', name);
+        if (silenced) {
+            await silenced.delete();
+        }
+        else {
+            await SilencedJob.create({ name });
+        }
+        return response.redirect().back();
+    }
+    /** The four numbers of the overview. */
+    async #stats() {
+        const now = DateTime.now();
+        return {
+            perMinute: await this.#finishedSince(now.minus({ minutes: 1 })),
+            pastHour: await this.#finishedSince(now.minus({ hours: 1 })),
+            failedPastWeek: await this.#count(JobRun.query()
+                .where('status', JobRunStatus.FAILED)
+                .where('finishedAt', '>', now.minus({ days: 7 }).toJSDate())),
+            running: await this.#count(JobRun.query().where('status', JobRunStatus.RUNNING)),
+        };
+    }
+    #finishedSince(moment) {
+        return this.#count(JobRun.query().where('finishedAt', '>', moment.toJSDate()));
+    }
+    async #count(query) {
+        const [row] = await query.count('* as total').pojo();
+        return Number(row.total);
+    }
+    /**
+     * What one column cost over the window.
+     *
+     * The count of the failures rides with the count of the rows: one reading of
+     * the table answers both.
+     */
+    async #metricsBy(column, since) {
+        const result = await db.rawQuery(`select ${column} as label,
+              count(*) as total,
+              count(*) filter (where status = ?) as failed,
+              round(avg(duration)::numeric, 1) as average,
+              round(max(duration)::numeric, 1) as longest
+         from ${JobRun.table}
+        where finished_at > ?
+        group by ${column}
+        order by count(*) desc`, [JobRunStatus.FAILED, since]);
+        return result.rows.map((row) => ({
+            label: row.label,
+            total: Number(row.total),
+            failed: Number(row.failed),
+            average: row.average === null ? null : Number(row.average),
+            longest: row.longest === null ? null : Number(row.longest),
+        }));
+    }
+    /**
+     * The classes that the lists leave out.
+     *
+     * One request reads them once: the page asks for them, and the frame around
+     * it asks again for its counts.
+     */
+    async #silencedNames() {
+        if (!this.#silenced) {
+            const rows = await SilencedJob.query().select('name');
+            this.#silenced = rows.map((row) => row.name);
+        }
+        return this.#silenced;
+    }
+    /**
+     * The word that the buttons of the page carry.
+     *
+     * A form that asks for something writes it beside what it asks. An
+     * application that guards its forms reads it; one that does not, reads
+     * nothing, and the page holds no word at all.
+     */
+    /** What the application told Orbit. */
+    #config() {
+        return app.config.get('orbit', {
+            path: '/queue',
+            authorize: () => false,
+            sinks: [],
+        });
+    }
+    /** The mode that the person chose, if they chose one. */
+    #theme(request) {
+        const theme = request.plainCookie(THEME_COOKIE);
+        return THEMES.includes(theme) ? theme : null;
+    }
+    #csrfToken(request) {
+        return request.csrfToken ?? null;
+    }
+    /** What one line of the table shows. The page reads, it does not calculate. */
+    #row(run, silenced, answers) {
+        const answer = run.retriedJobId ? answers.get(run.retriedJobId) : undefined;
+        return {
+            id: run.id,
+            jobId: run.jobId,
+            name: run.name,
+            queue: run.queue,
+            status: run.status,
+            statusLabel: STATUS_LABELS[run.status],
+            attempts: run.attempts,
+            duration: run.duration,
+            payload: JSON.stringify(run.payload ?? {}, null, 2),
+            error: run.error,
+            dispatchedAt: run.dispatchedAt?.toFormat('dd LLL yyyy HH:mm:ss') ?? null,
+            finishedAt: run.finishedAt?.toFormat('dd LLL yyyy HH:mm:ss') ?? null,
+            retriedAt: run.retriedAt?.toFormat('dd LLL yyyy HH:mm:ss') ?? null,
+            retriedJobId: run.retriedJobId,
+            retriedStatus: answer ? STATUS_LABELS[answer] : null,
+            canRetry: run.status === JobRunStatus.FAILED && !run.retriedJobId,
+            isSilenced: silenced.includes(run.name),
+        };
+    }
+    /**
+     * The page, with everything the frame around it asks for.
+     *
+     * The side menu carries the count of each status, thus every page says how
+     * many jobs wait and how many fell.
+     */
+    async #render({ request, response }, template, data) {
+        const config = this.#config();
+        /**
+         * A silenced class counts nowhere: a badge that says two, over a list that
+         * shows nothing, says nothing true.
+         */
+        const silenced = await this.#silencedNames();
+        const query = db.from(JobRun.table).select('status').count('* as total').groupBy('status');
+        if (silenced.length > 0) {
+            query.whereNotIn('name', silenced);
+        }
+        const counts = await query;
+        const byStatus = Object.fromEntries(counts.map((row) => [row.status, Number(row.total)]));
+        const menu = [
+            { key: 'overview', label: 'Overview', href: config.path, icon: ICONS.overview, count: null },
+            ...Object.values(JobRunStatus).map((status) => ({
+                key: status,
+                label: STATUS_LABELS[status],
+                href: `${config.path}?status=${status}`,
+                icon: ICONS[status],
+                count: byStatus[status] ?? 0,
+            })),
+            {
+                key: 'silenced',
+                label: 'Silenced',
+                href: `${config.path}/silenced`,
+                icon: ICONS.silenced,
+                count: null,
+            },
+            {
+                key: 'metrics',
+                label: 'Metrics',
+                href: `${config.path}/metrics`,
+                icon: ICONS.metrics,
+                count: null,
+            },
+        ];
+        const html = await edge.render(`orbit::${template}`, {
+            ...data,
+            path: config.path,
+            logo,
+            favicon,
+            theme: this.#theme(request),
+            menu,
+            csrfToken: this.#csrfToken(request),
+        });
+        response.header('content-type', 'text/html; charset=utf-8');
+        return response.send(html);
+    }
+}

package/build/src/define_config.d.ts

@@ -0,0 +1,5 @@
+import type { OrbitConfig } from './types.js';
+/**
+ * Define the configuration of Orbit with type safety.
+ */
+export declare function defineConfig(config: OrbitConfig): OrbitConfig;

package/build/src/define_config.js

@@ -0,0 +1,6 @@
+/**
+ * Define the configuration of Orbit with type safety.
+ */
+export function defineConfig(config) {
+    return config;
+}

package/build/src/jobs/prune_job_runs.d.ts

@@ -0,0 +1,20 @@
+import { Job } from '@adonisjs/queue';
+import type { JobOptions } from '@adonisjs/queue/types';
+interface PruneJobRunsPayload {
+    /** How long a job that succeeded stays readable, in days. */
+    days: number;
+}
+/**
+ * Take out of the table the jobs that ended well.
+ *
+ * A job that succeeded says nothing after a few days, and the table would grow
+ * with every mail of every day.
+ *
+ * A job that failed is never taken out. It waits for a person, however long
+ * that takes.
+ */
+export default class PruneJobRuns extends Job<PruneJobRunsPayload> {
+    static options: JobOptions;
+    execute(): Promise<void>;
+}
+export {};

package/build/src/jobs/prune_job_runs.js

@@ -0,0 +1,27 @@
+import logger from '@adonisjs/core/services/logger';
+import { Job } from '@adonisjs/queue';
+import { DateTime } from 'luxon';
+import JobRun, { JobRunStatus } from '../models/job_run.js';
+/**
+ * Take out of the table the jobs that ended well.
+ *
+ * A job that succeeded says nothing after a few days, and the table would grow
+ * with every mail of every day.
+ *
+ * A job that failed is never taken out. It waits for a person, however long
+ * that takes.
+ */
+export default class PruneJobRuns extends Job {
+    static options = {
+        queue: 'default',
+        maxRetries: 1,
+    };
+    async execute() {
+        const before = DateTime.now().minus({ days: this.payload.days });
+        const removed = await JobRun.query()
+            .where('status', JobRunStatus.COMPLETED)
+            .where('finishedAt', '<', before.toJSDate())
+            .delete();
+        logger.info(`${removed} trace(s) of jobs removed.`);
+    }
+}

package/build/src/logo.d.ts

@@ -0,0 +1,4 @@
+/** The mark, to write in the page. */
+export declare const logo: string;
+/** The mark, as the address that the tab of the browser reads. */
+export declare const favicon: string;

package/build/src/logo.js

@@ -0,0 +1,12 @@
+import { readFileSync } from 'node:fs';
+/**
+ * The mark of Orbit.
+ *
+ * The package serves no file of its own, thus the mark is written in the page
+ * and given to the tab as an address of data. One file answers for the two.
+ */
+const source = readFileSync(new URL('../templates/orbit.svg', import.meta.url), 'utf-8');
+/** The mark, to write in the page. */
+export const logo = source;
+/** The mark, as the address that the tab of the browser reads. */
+export const favicon = `data:image/svg+xml;base64,${Buffer.from(source).toString('base64')}`;

package/build/src/middleware/dashboard_auth.d.ts

@@ -0,0 +1,10 @@
+import type { HttpContext } from '@adonisjs/core/http';
+import type { NextFn } from '@adonisjs/core/types/http';
+import type { OrbitConfig } from '../types.js';
+/**
+ * Ask the guard of the configuration who may read the page.
+ *
+ * A guard that says `false` and writes nothing leaves the page as a page that
+ * does not exist: a machine that guards nothing shows nothing.
+ */
+export declare function dashboardAuth(config: OrbitConfig): (ctx: HttpContext, next: NextFn) => Promise<any>;

package/build/src/middleware/dashboard_auth.js

@@ -0,0 +1,16 @@
+/**
+ * Ask the guard of the configuration who may read the page.
+ *
+ * A guard that says `false` and writes nothing leaves the page as a page that
+ * does not exist: a machine that guards nothing shows nothing.
+ */
+export function dashboardAuth(config) {
+    return async (ctx, next) => {
+        if (await config.authorize(ctx)) {
+            return next();
+        }
+        if (!ctx.response.hasContent) {
+            ctx.response.notFound({ success: false, error: 'Not found' });
+        }
+    };
+}

package/build/src/models/job_run.d.ts

@@ -0,0 +1,35 @@
+import { BaseModel } from '@adonisjs/lucid/orm';
+import type { DateTime } from 'luxon';
+/**
+ * What the queue did with one job.
+ *
+ * `pending` and `running` are what the worker is about to do or does now.
+ * `completed` and `failed` are what it did. `retrying` names a job that failed
+ * a try and waits for the next one.
+ */
+export declare const JobRunStatus: {
+    readonly PENDING: "pending";
+    readonly RUNNING: "running";
+    readonly RETRYING: "retrying";
+    readonly COMPLETED: "completed";
+    readonly FAILED: "failed";
+};
+export type JobRunStatusValue = (typeof JobRunStatus)[keyof typeof JobRunStatus];
+export default class JobRun extends BaseModel {
+    id: number;
+    jobId: string;
+    name: string;
+    queue: string;
+    status: JobRunStatusValue;
+    payload: Record<string, unknown>;
+    attempts: number;
+    error: string | null;
+    duration: number | null;
+    dispatchedAt: DateTime | null;
+    startedAt: DateTime | null;
+    finishedAt: DateTime | null;
+    retriedAt: DateTime | null;
+    retriedJobId: string | null;
+    createdAt: DateTime<true>;
+    updatedAt: DateTime;
+}

package/build/src/models/job_run.js

@@ -0,0 +1,71 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseModel, column } from '@adonisjs/lucid/orm';
+/**
+ * What the queue did with one job.
+ *
+ * `pending` and `running` are what the worker is about to do or does now.
+ * `completed` and `failed` are what it did. `retrying` names a job that failed
+ * a try and waits for the next one.
+ */
+export const JobRunStatus = {
+    PENDING: 'pending',
+    RUNNING: 'running',
+    RETRYING: 'retrying',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+};
+export default class JobRun extends BaseModel {
+}
+__decorate([
+    column({ isPrimary: true })
+], JobRun.prototype, "id", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "jobId", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "name", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "queue", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "status", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "payload", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "attempts", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "error", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "duration", void 0);
+__decorate([
+    column.dateTime()
+], JobRun.prototype, "dispatchedAt", void 0);
+__decorate([
+    column.dateTime()
+], JobRun.prototype, "startedAt", void 0);
+__decorate([
+    column.dateTime()
+], JobRun.prototype, "finishedAt", void 0);
+__decorate([
+    column.dateTime()
+], JobRun.prototype, "retriedAt", void 0);
+__decorate([
+    column()
+], JobRun.prototype, "retriedJobId", void 0);
+__decorate([
+    column.dateTime({ autoCreate: true })
+], JobRun.prototype, "createdAt", void 0);
+__decorate([
+    column.dateTime({ autoCreate: true, autoUpdate: true })
+], JobRun.prototype, "updatedAt", void 0);

package/build/src/models/silenced_job.d.ts

@@ -0,0 +1,14 @@
+import { BaseModel } from '@adonisjs/lucid/orm';
+import type { DateTime } from 'luxon';
+/**
+ * A job class that the page leaves out of its lists.
+ *
+ * The row names a class, not one job. Take it away, and everything that class
+ * did comes back, including what it did while it was silent.
+ */
+export default class SilencedJob extends BaseModel {
+    id: number;
+    name: string;
+    createdAt: DateTime<true>;
+    updatedAt: DateTime;
+}

package/build/src/models/silenced_job.js

@@ -0,0 +1,27 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { BaseModel, column } from '@adonisjs/lucid/orm';
+/**
+ * A job class that the page leaves out of its lists.
+ *
+ * The row names a class, not one job. Take it away, and everything that class
+ * did comes back, including what it did while it was silent.
+ */
+export default class SilencedJob extends BaseModel {
+}
+__decorate([
+    column({ isPrimary: true })
+], SilencedJob.prototype, "id", void 0);
+__decorate([
+    column()
+], SilencedJob.prototype, "name", void 0);
+__decorate([
+    column.dateTime({ autoCreate: true })
+], SilencedJob.prototype, "createdAt", void 0);
+__decorate([
+    column.dateTime({ autoCreate: true, autoUpdate: true })
+], SilencedJob.prototype, "updatedAt", void 0);

package/build/src/recorder.d.ts

@@ -0,0 +1,14 @@
+import type { OrbitConfig } from './types.js';
+/**
+ * Keep what the queue does with its jobs.
+ *
+ * The queue holds its jobs in Redis and removes them when they end. The trace
+ * holds what a job carried, how many tries it took, and the error that stopped
+ * it.
+ *
+ * The channels of the queue answer at once, thus the events are written apart.
+ * A sink that refuses an event must never stop the job that runs.
+ *
+ * A configuration that names no sink keeps nothing.
+ */
+export declare function recordJobRuns(config: OrbitConfig): void;