@artian-techs/adonis-orbit 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Artian Techs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+of the Software, and to permit persons to whom the Software is furnished to do
+so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+<p align="center">
+  <img src="templates/orbit.svg" width="96" alt="Orbit">
+</p>
+
+# adonis-orbit
+
+What the queue of AdonisJS did with each job, kept in a table, read on a page,
+and asked again when it failed.
+
+The queue holds its jobs in Redis and lets them go when they end. This package
+listens to the channels that the queue publishes, writes one row for each job,
+and serves a page that reads the table. A job that failed keeps the values it
+carried, so a person can ask for it again — from the page, or from a command.
+
+It works with AdonisJS 6 and 7.
+
+## Install
+
+```bash
+pnpm add @artian-techs/adonis-orbit
+node ace configure @artian-techs/adonis-orbit
+node ace migration:run
+```
+
+The configure step writes the provider in `adonisrc.ts`, publishes
+`config/orbit.ts`, publishes the two migrations — the table of the jobs, and
+the one that names the silenced classes — and declares the two environment
+variables that guard the page.
+
+## The page
+
+```
+http://localhost:3333/queue
+```
+
+It asks for a name and a word, in Basic auth. **While one of the two is
+missing, the page answers "not found"**: a machine that carries neither shows
+nothing.
+
+The page holds no session on purpose: it belongs to the team that runs the
+machine, not to the users of the application. It speaks English only.
+
+A menu on the left leads to each view, and carries the count of each status.
+Under it, one button reads the page in the light or in the dark. The page reads
+the mode of the machine while nobody chose; a choice is held in a cookie. The
+page holds no JavaScript.
+
+| Entry | What it shows |
+| --- | --- |
+| Overview | four numbers, then the last jobs of every status |
+| Pending, Running, Retrying, Completed, Failed | the same list, of one status |
+| Silenced | the classes that the lists leave out |
+| Metrics | what each class and each queue cost over the last 24 hours |
+
+The four numbers of the overview:
+
+| Number | What it counts |
+| --- | --- |
+| Jobs per minute | the jobs that ended in the last minute |
+| Jobs past hour | the jobs that ended in the last hour |
+| Failed jobs past 7 days | the jobs whose last try fell |
+| Jobs running now | the jobs a worker holds at this moment |
+
+Metrics reads the same table: for each class and for each queue, how many jobs
+ended, how many fell, and the average and the longest of their durations.
+
+## Silence a job
+
+A job that runs every minute fills the list and hides the rest. The button
+**Silence** on any row takes its class out of the lists, and out of the counts
+of the menu.
+
+Nothing else changes: the worker keeps its work, and the table keeps its trace.
+The page **Silenced** shows what is left out, and **Show again** brings the
+class back — with everything it did while it was silent.
+
+## Configuration
+
+```ts
+import { DatabaseSink, basicAuth, defineConfig } from '@artian-techs/adonis-orbit'
+
+import env from '#start/env'
+
+export default defineConfig({
+  path: '/queue',
+
+  authorize: basicAuth({
+    user: env.get('ORBIT_DASHBOARD_USER'),
+    password: env.get('ORBIT_DASHBOARD_PASSWORD'),
+  }),
+
+  sinks: [new DatabaseSink()],
+})
+```
+
+## Who may read the page
+
+`authorize` reads the request and answers `true` or `false`. It answers `false`,
+and the page says "not found": a machine that guards nothing shows nothing.
+
+`basicAuth` asks for a name and a word, with no session. It is what the
+configure step writes, and it answers "not found" while one of the two is
+missing.
+
+An application that already knows who is asking writes its own guard:
+
+```ts
+const TEAM = ['someone@example.com', 'someone-else@example.com']
+
+export default defineConfig({
+  path: '/queue',
+
+  authorize: async ({ auth }) => {
+    await auth.check()
+
+    return TEAM.includes(auth.user?.email ?? '')
+  },
+
+  sinks: [new DatabaseSink()],
+})
+```
+
+The package imports no authentication of its own: the guard reads the context
+of the request, and the application says what it reads there.
+
+A guard that wants to say something other than "not found" writes its answer
+before it says `false`:
+
+```ts
+authorize: async (ctx) => {
+  if (await ctx.auth.check()) {
+    return true
+  }
+
+  ctx.response.redirect('/login')
+
+  return false
+}
+```
+
+## Where the trace goes
+
+**Nothing is kept that the configuration does not name.** The table of
+`job_runs` is one sink among others, and the configure step writes it in
+`config/orbit.ts`:
+
+```ts
+import { DatabaseSink, defineConfig } from '@artian-techs/adonis-orbit'
+
+export default defineConfig({
+  path: '/queue',
+  auth: { user: env.get('ORBIT_DASHBOARD_USER'), password: env.get('ORBIT_DASHBOARD_PASSWORD') },
+
+  sinks: [new DatabaseSink(), new MySink()],
+})
+```
+
+Take `DatabaseSink` away, and the table stays empty and the page shows nothing:
+the page reads the table, and reads nothing else. A machine that sends its
+trace somewhere else thus keeps none of it.
+
+A sink reads one step of one job, and gives nothing back:
+
+```ts
+import type { JobEvent, Sink } from '@artian-techs/adonis-orbit'
+
+class MySink implements Sink {
+  async write(events: JobEvent[]) {
+    // { type: 'dispatched' | 'started' | 'finished', at, job: { id, name, queue, payload, attempts } }
+  }
+}
+```
+
+The events of one step arrive together: a dispatch of ten jobs calls `write`
+once, with ten events. A sink that fails is written in the log, and the job
+that runs goes on.
+
+## What of the payload is kept
+
+A payload holds what a person wrote: an address, a name, a number. The
+configuration says how much of it the trace keeps.
+
+```ts
+export default defineConfig({
+  // ...
+
+  /** 'full' by default. 'none' keeps nothing. */
+  payload: (payload, job) => ({ ...payload, password: undefined }),
+})
+```
+
+The rule is applied before the first sink reads the event, thus what it takes
+out reaches nothing and nobody.
+
+## What the table holds
+
+One row for one job, completed at each step.
+
+| Status | What it says |
+| --- | --- |
+| `pending` | the job waits for a worker |
+| `running` | a worker holds it |
+| `retrying` | a try failed, the next one is set |
+| `completed` | done |
+| `failed` | every try fell |
+
+The row that the dispatch writes and the row that the worker writes are the
+same row. Either of the two can arrive first, thus the first one writes and the
+second one completes.
+
+## Ask a job again
+
+From the page, with the button on a row that failed. Or with the job that the
+package carries:
+
+```ts
+import { JobRun, JobRunStatus, retryRun } from '@artian-techs/adonis-orbit'
+
+const runs = await JobRun.query().where('status', JobRunStatus.FAILED)
+
+for (const run of runs) {
+  await retryRun(run)
+}
+```
+
+The row is never replaced: the new job takes a new identifier and opens its own
+row, and the old one names it.
+
+## Tests
+
+```bash
+pnpm test
+```
+
+The tests read a PostgreSQL server, as the package does. The environment names
+it, and without it the tests read `127.0.0.1:5432` and the database
+`orbit_test`:
+
+| Variable | What it names |
+| --- | --- |
+| `PG_HOST` | the machine, `127.0.0.1` |
+| `PG_PORT` | the port, `5432` |
+| `PG_USER` | the name, `postgres` |
+| `PG_PASSWORD` | the word, `postgres` |
+| `PG_DATABASE` | the database, `orbit_test` |
+
+A server for the tests alone:
+
+```bash
+docker run -d --name orbit-test-pg -p 55432:5432 \
+  -e POSTGRES_USER=orbit -e POSTGRES_PASSWORD=orbit -e POSTGRES_DB=orbit_test \
+  postgres:16
+
+PG_PORT=55432 PG_USER=orbit PG_PASSWORD=orbit pnpm test
+```
+
+The tests create the two tables from the stubs of `stubs/migrations`, and take
+them away at the end.
+
+`pnpm preview` opens the page on `http://localhost:3333/queue`, with jobs of
+every status to read and the name `orbit` and the word `orbit`. It reads a
+database of its own, `orbit_preview`, and makes it if it is not there.
+
+## Take out the traces that ended well
+
+The package carries `PruneJobRuns` and names it to the queue itself. Give it a
+place in the schedule of the application:
+
+```ts
+import { PruneJobRuns } from '@artian-techs/adonis-orbit'
+
+await PruneJobRuns.schedule({ days: 7 }).cron('10 0 * * *').run()
+```
+
+A row that failed is never taken out.

package/build/configure.d.ts

@@ -0,0 +1,8 @@
+import type Configure from '@adonisjs/core/commands/configure';
+/**
+ * Put Orbit in an application.
+ *
+ * The table belongs to the application, thus the migration is published there
+ * and read like the others.
+ */
+export declare function configure(command: Configure): Promise<void>;

package/build/configure.js

@@ -0,0 +1,38 @@
+import { stubsRoot } from './stubs/main.js';
+/**
+ * Put Orbit in an application.
+ *
+ * The table belongs to the application, thus the migration is published there
+ * and read like the others.
+ */
+export async function configure(command) {
+    const codemods = await command.createCodemods();
+    await codemods.updateRcFile((rcFile) => {
+        rcFile.addProvider('@artian-techs/adonis-orbit/orbit_provider');
+    });
+    await codemods.makeUsingStub(stubsRoot, 'config/orbit.stub', {});
+    const now = new Date().getTime();
+    await codemods.makeUsingStub(stubsRoot, 'migrations/create_job_runs_table.stub', {
+        migration: {
+            folder: 'database/migrations',
+            fileName: `${now}_create_job_runs_table.ts`,
+        },
+    });
+    await codemods.makeUsingStub(stubsRoot, 'migrations/create_silenced_jobs_table.stub', {
+        migration: {
+            folder: 'database/migrations',
+            fileName: `${now + 1}_create_silenced_jobs_table.ts`,
+        },
+    });
+    await codemods.defineEnvVariables({
+        ORBIT_DASHBOARD_USER: '',
+        ORBIT_DASHBOARD_PASSWORD: '',
+    });
+    await codemods.defineEnvValidations({
+        variables: {
+            ORBIT_DASHBOARD_USER: 'Env.schema.string.optional()',
+            ORBIT_DASHBOARD_PASSWORD: 'Env.schema.string.optional()',
+        },
+        leadingComment: 'Variables for the page of the queue',
+    });
+}

package/build/index.d.ts

@@ -0,0 +1,10 @@
+export { defineConfig } from './src/define_config.js';
+export { basicAuth } from './src/auth/basic_auth.js';
+export { default as DatabaseSink } from './src/sinks/database_sink.js';
+export type { Authorize, JobEvent, JobIdentity, JobOutcome, OrbitConfig, PayloadRule, Sink, } from './src/types.js';
+export { default as JobRun, JobRunStatus, type JobRunStatusValue } from './src/models/job_run.js';
+export { default as SilencedJob } from './src/models/silenced_job.js';
+export { default as PruneJobRuns } from './src/jobs/prune_job_runs.js';
+export { retryRun } from './src/retry.js';
+export { stubsRoot } from './stubs/main.js';
+export { configure } from './configure.js';

package/build/index.js

@@ -0,0 +1,9 @@
+export { defineConfig } from './src/define_config.js';
+export { basicAuth } from './src/auth/basic_auth.js';
+export { default as DatabaseSink } from './src/sinks/database_sink.js';
+export { default as JobRun, JobRunStatus } from './src/models/job_run.js';
+export { default as SilencedJob } from './src/models/silenced_job.js';
+export { default as PruneJobRuns } from './src/jobs/prune_job_runs.js';
+export { retryRun } from './src/retry.js';
+export { stubsRoot } from './stubs/main.js';
+export { configure } from './configure.js';

package/build/providers/orbit_provider.d.ts

@@ -0,0 +1,13 @@
+import type { ApplicationService } from '@adonisjs/core/types';
+/**
+ * Watch what the queue does, and keep it.
+ *
+ * The provider listens to the channels of the queue, writes each job in the
+ * table, and opens the page that reads it. The application gives it a path and
+ * the two words that guard the page, and nothing else.
+ */
+export default class OrbitProvider {
+    protected app: ApplicationService;
+    constructor(app: ApplicationService);
+    boot(): Promise<void>;
+}

package/build/providers/orbit_provider.js

@@ -0,0 +1,35 @@
+import { Locator } from '@adonisjs/queue';
+import edge from 'edge.js';
+import PruneJobRuns from '../src/jobs/prune_job_runs.js';
+const DEFAULTS = { path: '/queue', authorize: () => false, sinks: [] };
+/**
+ * Watch what the queue does, and keep it.
+ *
+ * The provider listens to the channels of the queue, writes each job in the
+ * table, and opens the page that reads it. The application gives it a path and
+ * the two words that guard the page, and nothing else.
+ */
+export default class OrbitProvider {
+    app;
+    constructor(app) {
+        this.app = app;
+    }
+    async boot() {
+        const config = this.app.config.get('orbit', DEFAULTS);
+        /**
+         * The page of Orbit lives with Orbit, thus the application carries no
+         * view for it.
+         */
+        edge.mount('orbit', new URL('../templates/', import.meta.url));
+        /**
+         * The application looks for its jobs in its own folders, and this one
+         * lives here. It names itself to the queue.
+         */
+        Locator.register(PruneJobRuns.name, PruneJobRuns);
+        const { recordJobRuns } = await import('../src/recorder.js');
+        recordJobRuns(config);
+        const router = await this.app.container.make('router');
+        const { registerRoutes } = await import('../src/routes.js');
+        registerRoutes(router, config);
+    }
+}

package/build/src/auth/basic_auth.d.ts

@@ -0,0 +1,12 @@
+import type { Authorize } from '../types.js';
+/**
+ * Read the page with a name and a word, and no session.
+ *
+ * The page belongs to the team that runs the machine, not to the users of the
+ * application. It shows nothing at all while one of the two is missing, thus a
+ * machine that carries neither shows nothing.
+ */
+export declare function basicAuth(credentials: {
+    user?: string;
+    password?: string;
+}): Authorize;

package/build/src/auth/basic_auth.js

@@ -0,0 +1,36 @@
+import { timingSafeEqual } from 'node:crypto';
+/**
+ * Compare the two words in a time that does not change with the number of
+ * letters that agree.
+ */
+function matches(given, expected) {
+    if (!given) {
+        return false;
+    }
+    const a = Buffer.from(given);
+    const b = Buffer.from(expected);
+    return a.length === b.length && timingSafeEqual(a, b);
+}
+/**
+ * Read the page with a name and a word, and no session.
+ *
+ * The page belongs to the team that runs the machine, not to the users of the
+ * application. It shows nothing at all while one of the two is missing, thus a
+ * machine that carries neither shows nothing.
+ */
+export function basicAuth(credentials) {
+    return ({ request, response }) => {
+        const { user, password } = credentials;
+        if (!user || !password) {
+            return false;
+        }
+        const [scheme, given] = (request.header('authorization') ?? '').split(' ');
+        const expected = Buffer.from(`${user}:${password}`).toString('base64');
+        if (scheme !== 'Basic' || !matches(given, expected)) {
+            response.header('www-authenticate', 'Basic realm="Queue"');
+            response.unauthorized({ success: false, error: 'Authentication is required' });
+            return false;
+        }
+        return true;
+    };
+}

package/build/src/controllers/dashboard_controller.d.ts

@@ -0,0 +1,51 @@
+import type { HttpContext } from '@adonisjs/core/http';
+/**
+ * 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 {
+    #private;
+    /**
+     * 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.
+     */
+    index(ctx: HttpContext): Promise<void>;
+    /**
+     * 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.
+     */
+    silenced(ctx: HttpContext): Promise<void>;
+    /**
+     * 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.
+     */
+    metrics(ctx: HttpContext): Promise<void>;
+    /**
+     * 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.
+     */
+    retry({ params, response }: HttpContext): Promise<void>;
+    /**
+     * 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.
+     */
+    theme({ params, response }: HttpContext): Promise<void>;
+    /** Take a class out of the lists, or put it back. */
+    silence({ params, response }: HttpContext): Promise<void>;
+}