@mason-data/cli 0.9.0 → 0.10.0

package/dist/src/cli/usage.js

@@ -12,9 +12,10 @@ import { fileSize, guarded, runFailure } from "./commands.js";
 import { timeOf } from "./request-filter.js";
 import { duration, msText } from "./readiness.js";
 import { SIZE_EVERY_MS } from "../duck/usage.js";
+import { parseDuration } from "../lib/table-sync.js";
 const out = (m) => { process.stdout.write(`${m}\n`); };
 const n = (x) => x.toLocaleString("en-US");
-export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>] [--step <span>] [--json]
+export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>] [--step <duration>] [--json]
 
   What Mason was and did over time, from a sample it takes every minute and keeps MASON_HISTORY_DAYS days
   (default 7): a line each span — the statements of the Postgres API (how many, how many were refused, failed or
@@ -29,15 +30,18 @@ export const USAGE_USAGE = `usage: mason usage [--since <when>] [--until <when>]
 
   --since <when>   from when: an age (90s, 30m, 6h, 7d) or an ISO 8601 date or time with its zone; default 1h
   --until <when>   until when, the same way; default now
-  --step <span>    a line per span (1m to the days kept; default 5m), or 0 for every sample as it was taken
-  --json           as data: { since, until, stepSeconds (null: every sample), sampleSeconds, keptDays, samples: [{ at
-                   (with a step, the span's start), seconds, copyBytes, copyRows, tablesAdded, tablesCopied,
-                   tablesFailed, oldestSyncSeconds, statements, statementsRefused, statementsFailed, statementsCancelled,
-                   rowsSent, bytesSent, durationP50Ms, durationP95Ms, streamLagBytes, streamLagSeconds, rssBytes,
-                   heapUsedBytes, copyMemoryBytes, copyMemoryLimitBytes, slotWalHeldBytes (replication: the WAL the
-                   slot holds on the database), diskFreeBytes (free where the synced data is; with a step, the lowest),
-                   sessionsOpen (the Postgres API's sessions logged in) }],
-                   copySizes: [{ table, bytes, at }], next }
+  --step <duration>  a line per span (1m to the days kept; default 5m; a bare number is seconds), or 0 for every
+                   sample as it was taken
+  --json           as data: its shape is at the end
+
+  The --json answer: { since, until, stepSeconds (null: every sample), sampleSeconds, keptDays, samples: [{ at
+    (with a step, the span's start), seconds, copyBytes, copyRows, tablesAdded, tablesCopied,
+    tablesFailed, oldestSyncSeconds, statements, statementsRefused, statementsFailed, statementsCancelled,
+    rowsSent, bytesSent, durationP50Ms, durationP95Ms, streamLagBytes, streamLagSeconds, rssBytes,
+    heapUsedBytes, copyMemoryBytes, copyMemoryLimitBytes, slotWalHeldBytes (replication: the WAL the
+    slot holds on the database), diskFreeBytes (free where the synced data is; with a step, the lowest),
+    sessionsOpen (the Postgres API's sessions logged in) }],
+    copySizes: [{ table, bytes, at }], next }
 `;
 export const USAGE = {
     needs: "run",
@@ -47,13 +51,13 @@ export const USAGE = {
     options: { since: { type: "string" }, until: { type: "string" }, step: { type: "string" }, json: { type: "boolean" } },
     json: ["since", "until", "stepSeconds", "sampleSeconds", "keptDays", "samples", "copySizes", "next"],
 };
-const UNIT = { s: 1, m: 60, h: 3600, d: 86_400 };
-/** A span as the options write it (90s, 30m, 6h, 7d; 0), in seconds, or null when it is not one. */
+/** A span as the options write it (the command line's one duration grammar, src/lib/table-sync.ts `parseDuration`:
+ *  90s, 30m, 6h, 7d, a bare number of seconds; 0 for every sample), in whole seconds, or null when it is not one. */
 export function spanSeconds(text) {
     if (text.trim() === "0")
         return 0;
-    const m = /^\s*(\d+)\s*([smhd])\s*$/.exec(text);
-    return m ? Number(m[1]) * UNIT[m[2]] : null;
+    const d = parseDuration(text, { zero: true });
+    return "problem" in d || !Number.isInteger(d.seconds) ? null : d.seconds;
 }
 /** One sample on one line: the time, the statements, those refused, failed or cancelled, p95, rows sent, the copy, its rows, the stalest copy, the lag, the memory. */
 export function sampleLine(s, withLag) {
@@ -87,7 +91,7 @@ export async function usage(argv, now = Date.now()) {
             return failed("usage", { ...t, usage: USAGE_USAGE }, { json });
     const step = spanSeconds(v.step ?? "5m");
     if (step === null)
-        return failed("usage", { message: `--step is a span (1m, 5m, 1h, 1d) or 0 for every sample, not ${JSON.stringify(v.step)}`, code: "usage", usage: USAGE_USAGE }, { json });
+        return failed("usage", { message: `--step is a duration (300, 1m, 5m, 1h, 1d: a bare number is seconds) or 0 for every sample, not ${JSON.stringify(v.step)}`, code: "usage", usage: USAGE_USAGE }, { json });
     const w = await reach(USAGE, json);
     if (w === null || !("run" in w))
         return 1;

package/dist/src/cli/user-hosted.js

@@ -4,7 +4,8 @@
  * server takes for it (src/cli/run-server.ts `/api/users`), sent to the service under `/v1/replicas/{org}/{name}/users`:
  *
  *   list      GET    …/users?lastUsed=1                     mason user list --json's shape, beside its next
- *   add       POST   …/users  { name, role?, set? }          mason user add --json's shape (the run is up: its url)
+ *   add       POST   …/users  { name, role?, set?, from? }   mason user add --json's shape (the run is up: its url)
+ *   from      POST   …/users/{user}/from  { from }           { changed, already }: its ranges replaced (null: any address)
  *   disable   POST   …/users/{user}/disable                  { disabled, already }
  *   enable    POST   …/users/{user}/enable                   { enabled, already }
  *   remove    DELETE …/users/{user}                          { removed }
@@ -36,6 +37,10 @@
  *   role, roleFrom, readsNothing,         rows, list's lines, --json                  `ROLE_NAME_RE`; closed sets; booleans; each consistent with the others
  *     roleKnown, live
  *   attributes, missingAttributes         rows, list's lines, --json                  `ATTRIBUTE_NAME_RE` names; each value one line (`serviceText`), bounded
+ *   from (a user's address ranges)        rows, list's lines, add's row, --json       null, or 1 to MAX_RANGES ranges each in the one form
+ *                                                                                     src/duck/users.ts `userRanges` writes back (`heldRanges`);
+ *                                                                                     on add and from, exactly the ranges sent, else the answer
+ *                                                                                     is refused whole (`sameRanges`, `unconfirmed`: fail closed)
  *   lastUsedNote, urlNote                 list's tip "Last used: …", --json           one line (`serviceText`), bounded
  *   requestLogDays                        list's lines, --json                        a whole number, 1 to 36500
  *   already                               the headline chosen, --json                 a boolean
@@ -57,12 +62,12 @@ import { replicaText, tokenFor } from "./replica.js";
 import { holdOutput } from "./output-gate.js";
 import { err as styleErr, out as styleOut } from "./style.js";
 import { connectionUrl, psqlLine } from "./pg-url.js";
-import { USER_NAME_RE } from "../duck/users.js";
+import { MAX_RANGES, USER_NAME_RE, userRanges } from "../duck/users.js";
 import { ROLE_NAME_RE } from "./roles.js";
 import { ATTRIBUTE_NAME_RE } from "../duck/row-filter.js";
 import { databaseNameProblem } from "../lib/database-name.js";
 import { NO_ROLES } from "../duck/grants.js";
-import { addedNext, addedReport, disabledNext, disabledReport, enabledNext, enabledReport, listNext, listText, REMOVED_NEXT, removedReport, USER } from "./user.js";
+import { addedNext, addedReport, disabledNext, disabledReport, enabledNext, enabledReport, fromNext, fromReport, listNext, listText, REMOVED_NEXT, removedReport, USER } from "./user.js";
 /** The bound of a list's answer (a replica's users, a row each), and of the number of users in it; every other answer
  *  is `call`'s own 64 KiB. */
 export const MAX_LIST_BYTES = 1024 * 1024;
@@ -83,7 +88,9 @@ export function requestOf(r, o) {
     // a user's name is USER_NAME_RE's (checked before this): letters, digits, `_`, `.` and `-`, safe in a path as it is
     switch (o.verb) {
         case "list": return { method: "GET", path: `${base}?lastUsed=1` };
-        case "add": return { method: "POST", path: base, json: { name: o.name, ...(o.role !== undefined ? { role: o.role } : {}), ...(o.sets.length ? { set: [...o.sets] } : {}) } };
+        case "add": return { method: "POST", path: base, json: { name: o.name, ...(o.role !== undefined ? { role: o.role } : {}), ...(o.sets.length ? { set: [...o.sets] } : {}),
+                ...(o.from !== undefined && o.from !== null ? { from: [...o.from] } : {}) } };
+        case "from": return { method: "POST", path: `${base}/${o.name}/from`, json: { from: o.from === undefined || o.from === null ? null : [...o.from] } };
         case "disable":
         case "enable": return { method: "POST", path: `${base}/${o.name}/${o.verb}` };
         case "remove": return { method: "DELETE", path: `${base}/${o.name}` };
@@ -125,6 +132,16 @@ function attributesOf(v) {
     }
     return outv;
 }
+/** A user's address ranges as the service sends them: null (any address), or 1 to MAX_RANGES ranges, each in the one form
+ *  the one grammar writes back (src/duck/users.ts `userRanges`); undefined when they are not that. */
+export function heldRanges(v) {
+    if (v === null)
+        return null;
+    if (!Array.isArray(v) || v.length < 1 || v.length > MAX_RANGES || !v.every((x) => typeof x === "string" && x.length <= 64))
+        return undefined;
+    const r = userRanges(v);
+    return "problem" in r || r.from.length !== v.length || r.from.some((x, i) => x !== v[i]) ? undefined : r.from;
+}
 const names = (v) => Array.isArray(v) && v.length >= 1 && v.length <= 64 && v.every((x) => typeof x === "string" && ATTRIBUTE_NAME_RE.test(x));
 const timeOrNull = (v) => v === null || isServiceTime(v);
 /** One row of a list, as `listUsers` makes it (src/cli/user.ts `UserRow`); null when it is not that shape. */
@@ -142,6 +159,10 @@ function rowOf(v) {
     const role = roleOf(u);
     if (role === null)
         return null;
+    // a replica's Mason before address ranges sends none: it has none, so any address
+    const from = u.from === undefined ? null : heldRanges(u.from);
+    if (from === undefined)
+        return null;
     const attributes = u.attributes === undefined ? undefined : attributesOf(u.attributes);
     if (attributes === null)
         return null;
@@ -150,7 +171,7 @@ function rowOf(v) {
     if (u.roleKnown !== undefined && (typeof u.roleKnown !== "boolean" || role.roleFrom !== "file"))
         return null;
     return { name: u.name, id: u.id, addedAt: u.addedAt, removedAt: u.removedAt, disabledAt: u.disabledAt, live: u.live, lastUsedAt: u.lastUsedAt,
-        url: u.url, ...role, ...(attributes !== undefined ? { attributes } : {}),
+        url: u.url, from, ...role, ...(attributes !== undefined ? { attributes } : {}),
         ...(u.missingAttributes !== undefined ? { missingAttributes: u.missingAttributes } : {}),
         ...(typeof u.roleKnown === "boolean" ? { roleKnown: u.roleKnown } : {}) };
 }
@@ -195,11 +216,15 @@ export function heldAdded(json, asked, secrets) {
     const role = roleOf(a);
     if (role === null)
         return null;
+    const from = a.from === undefined ? undefined : heldRanges(a.from);
+    // null (any address) is read as no ranges, as a list's row reads it: an add that sent ranges then refuses it unconfirmed
+    if (from === undefined && a.from !== undefined)
+        return null;
     const attributes = a.attributes === undefined ? undefined : attributesOf(a.attributes);
     if (attributes === null)
         return null;
     return { user: asked, id: a.id, addedAt: a.addedAt, password: a.password, database: a.database, url, psql: psqlLine(url), host: a.host, port: a.port, sslmode: a.sslmode,
-        ...role, ...(attributes !== undefined ? { attributes } : {}) };
+        ...role, ...(attributes !== undefined ? { attributes } : {}), ...(from !== undefined && from !== null ? { from } : {}) };
 }
 /** A user as disable, enable and remove name it: the name asked, its id, when it was added, and `more` times. */
 function userOf(v, asked, more) {
@@ -219,6 +244,14 @@ export function heldEnabled(json, asked, secrets) {
     const e = userOf(json.enabled, asked, []);
     return e === null ? null : { enabled: e, already: json.already };
 }
+/** `POST …/users/{user}/from`'s answer: the user asked, its ranges now (null: any address), and `already`. */
+export function heldFrom(json, asked, secrets) {
+    if (!obj(json) || typeof json.already !== "boolean" || !carriesNoSecret(json, secrets))
+        return null;
+    const c = userOf(json.changed, asked, []);
+    const from = obj(json.changed) ? heldRanges(json.changed.from) : undefined;
+    return c === null || from === undefined ? null : { changed: { ...c, from }, already: json.already };
+}
 export function heldRemoved(json, asked, secrets) {
     if (!obj(json) || !carriesNoSecret(json, secrets))
         return null;
@@ -226,8 +259,25 @@ export function heldRemoved(json, asked, secrets) {
     return r === null ? null : { removed: r };
 }
 // ------------------------------------------------------------------ the command
+/** Whether the ranges an answer carries are exactly those sent (each in its one form, in order; null: any address). */
+export const sameRanges = (got, sent) => got !== undefined && JSON.stringify(got) === JSON.stringify(sent);
+/**
+ * AN ADDRESS LIMIT THE SERVICE DID NOT CONFIRM: its 200 does not carry the ranges sent (none, null, or others). The
+ * answer is refused whole, never printed (an add's password included): the user may now connect from more addresses
+ * than asked, which only the replica's list can say, and the way out removes it or sets the ranges again.
+ */
+export function unconfirmed(r, name, sent, verb) {
+    const on = `--replica ${replicaText(r)}`;
+    const asked = sent === null ? "any address" : sent.join(", ");
+    return { message: `the service did not confirm ${name}'s address limit: its answer does not carry the ranges sent (${asked})`, code: "failed",
+        why: verb === "add" ? `the replica may have added ${name} with no limit, so it would connect from any address, and its password was not shown`
+            : `the replica may have kept ${name}'s ranges as they were, or set others`,
+        fix: verb === "add" ? `mason user list ${on} says what ${name} has; if it was made without the limit, mason user remove ${name} ${on}`
+            : `mason user list ${on} says what ${name} has now; mason user from ${name} ${sent === null ? "--any" : sent.join(" ")} ${on} sets it again, or mason user remove ${name} ${on}`,
+        next: [[`mason user list ${on}`, "the replica's users and the addresses each connects from"], [`mason user remove ${name} ${on}`, "if it was made without the limit"]] };
+}
 /** What each subcommand asked, in the words of a failure outside the contract (`unexpected`). */
-const STEP = { list: "the replica's users were asked for", add: "a user was added", disable: "a user was disabled", enable: "a user was enabled", remove: "a user was removed" };
+const STEP = { list: "the replica's users were asked for", add: "a user was added", from: "a user's address ranges were set", disable: "a user was disabled", enable: "a user was enabled", remove: "a user was removed" };
 /** `mason user <verb> … --replica <org>/<name>`: one request, its answer held and printed as the local command prints it. */
 export async function hostedUser(r, o) {
     const outStyle = serviceStyle(styleOut());
@@ -250,8 +300,10 @@ export async function hostedUser(r, o) {
     if (a.status !== 200)
         return fail(refused(a));
     const outside = () => fail(unexpected(service, a, STEP[o.verb]));
+    // the target in every answer: the replica's name in --json and in the headline
+    const on = replicaText(r);
     const print = (value, next, text) => {
-        out(o.json ? jsonText(USER, value, next) : text());
+        out(o.json ? jsonText(USER, { replica: on, ...value }, next) : text());
         return 0;
     };
     switch (o.verb) {
@@ -260,7 +312,7 @@ export async function hostedUser(r, o) {
             if (l === null)
                 return outside();
             const next = onReplica(listNext(l.users), r);
-            return print({ ...l }, next, () => listText(replicaText(r), l, NO_ROLES, next, outStyle));
+            return print({ ...l }, next, () => listText(on, l, NO_ROLES, next, outStyle));
         }
         case "add": {
             const added = heldAdded(a.json, o.name, secrets);
@@ -271,29 +323,42 @@ export async function hostedUser(r, o) {
                     fix: `mason user list --replica ${replicaText(r)} says whether it did; if so, mason user remove ${o.name} --replica ${replicaText(r)}, then add it again`,
                     next: [[`mason user list --replica ${replicaText(r)}`, "the replica's users"]] });
             }
+            // FAIL CLOSED: ranges sent must come back as sent, or the user may have been made with none (a service that does
+            // not know `from` would make it connect from any address), and its password is not shown
+            if (o.from !== undefined && o.from !== null && !sameRanges(added.from, o.from))
+                return fail(unconfirmed(r, o.name, o.from, "add"));
             const next = onReplica(addedNext(added.user, true), r);
-            return print({ ...added }, next, () => addedReport(added, { roles: NO_ROLES, listener: null, next }, outStyle));
+            return print({ ...added }, next, () => addedReport(added, { roles: NO_ROLES, listener: null, next, on }, outStyle));
+        }
+        case "from": {
+            const c = heldFrom(a.json, o.name, secrets);
+            if (c === null)
+                return outside();
+            if (!sameRanges(c.changed.from, o.from ?? null))
+                return fail(unconfirmed(r, o.name, o.from ?? null, "from"));
+            const next = onReplica(fromNext(c.changed.name, c.changed.from), r);
+            return print({ ...c }, next, () => fromReport(c, true, next, outStyle));
         }
         case "disable": {
             const d = heldDisabled(a.json, o.name, secrets);
             if (d === null)
                 return outside();
             const next = onReplica(disabledNext(d.disabled.name), r);
-            return print({ ...d }, next, () => disabledReport(d, true, next, outStyle));
+            return print({ ...d }, next, () => disabledReport(d, true, next, outStyle, on));
         }
         case "enable": {
             const e = heldEnabled(a.json, o.name, secrets);
             if (e === null)
                 return outside();
             const next = onReplica(enabledNext(e.enabled.name), r);
-            return print({ ...e }, next, () => enabledReport(e, next, outStyle));
+            return print({ ...e }, next, () => enabledReport(e, next, outStyle, on));
         }
         case "remove": {
             const x = heldRemoved(a.json, o.name, secrets);
             if (x === null)
                 return outside();
             const next = onReplica(REMOVED_NEXT, r);
-            return print({ ...x }, next, () => removedReport(x, true, next, outStyle));
+            return print({ removedUser: x.removed, ...x }, next, () => removedReport(x, true, next, outStyle, on));
         }
     }
 }