@mason-data/cli 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (111) hide show
  1. package/README.md +90 -71
  2. package/dist/src/api/error.js +3 -0
  3. package/dist/src/api/postgres/catalog.js +222 -13
  4. package/dist/src/api/postgres/encode.js +3 -1
  5. package/dist/src/api/postgres/explain.js +3 -2
  6. package/dist/src/api/postgres/protocol.js +39 -23
  7. package/dist/src/api/postgres/server.js +1173 -207
  8. package/dist/src/api/postgres/translate.js +81 -9
  9. package/dist/src/api/request-log.js +18 -5
  10. package/dist/src/cdc/poll.js +5 -5
  11. package/dist/src/cli/background.js +29 -6
  12. package/dist/src/cli/cancel.js +75 -0
  13. package/dist/src/cli/command.js +1 -0
  14. package/dist/src/cli/commands.js +622 -183
  15. package/dist/src/cli/control.js +59 -0
  16. package/dist/src/cli/demo.js +19 -10
  17. package/dist/src/cli/dev.js +351 -111
  18. package/dist/src/cli/doctor.js +20 -10
  19. package/dist/src/cli/guides.js +79 -31
  20. package/dist/src/cli/init.js +119 -58
  21. package/dist/src/cli/machine.js +12 -11
  22. package/dist/src/cli/main.js +3 -3
  23. package/dist/src/cli/mcp.js +29 -20
  24. package/dist/src/cli/metrics.js +79 -0
  25. package/dist/src/cli/pg-tls.js +13 -3
  26. package/dist/src/cli/pg-url.js +4 -0
  27. package/dist/src/cli/pin.js +13 -12
  28. package/dist/src/cli/preflight.js +8 -7
  29. package/dist/src/cli/project.js +43 -4
  30. package/dist/src/cli/readiness.js +38 -4
  31. package/dist/src/cli/registry.js +53 -34
  32. package/dist/src/cli/replication-checks.js +7 -5
  33. package/dist/src/cli/replication-mode.js +105 -26
  34. package/dist/src/cli/request-filter.js +134 -0
  35. package/dist/src/cli/roles.js +584 -0
  36. package/dist/src/cli/run-server.js +483 -41
  37. package/dist/src/cli/runs.js +1 -1
  38. package/dist/src/cli/security.js +10 -8
  39. package/dist/src/cli/serve.js +144 -42
  40. package/dist/src/cli/share-run.js +286 -0
  41. package/dist/src/cli/share.js +286 -0
  42. package/dist/src/cli/source-edit.js +65 -13
  43. package/dist/src/cli/sources.js +287 -38
  44. package/dist/src/cli/supervise.js +12 -1
  45. package/dist/src/cli/sync.js +55 -25
  46. package/dist/src/cli/tunnel.js +200 -0
  47. package/dist/src/cli/ui.js +9 -6
  48. package/dist/src/cli/usage.js +128 -0
  49. package/dist/src/cli/user.js +496 -40
  50. package/dist/src/cli/version.js +9 -7
  51. package/dist/src/demo/seed.js +3 -0
  52. package/dist/src/duck/cancel.js +10 -1
  53. package/dist/src/duck/events.js +134 -0
  54. package/dist/src/duck/executor-worker.js +18 -9
  55. package/dist/src/duck/executor.js +43 -30
  56. package/dist/src/duck/explain.js +56 -46
  57. package/dist/src/duck/extensions.js +160 -0
  58. package/dist/src/duck/functions.js +13 -14
  59. package/dist/src/duck/gaps.js +17 -8
  60. package/dist/src/duck/grants.js +176 -0
  61. package/dist/src/duck/history.js +123 -0
  62. package/dist/src/duck/kept.js +6 -6
  63. package/dist/src/duck/plan.js +102 -25
  64. package/dist/src/duck/publication.js +6 -6
  65. package/dist/src/duck/requests.js +265 -93
  66. package/dist/src/duck/rewrite.js +25 -5
  67. package/dist/src/duck/row-filter.js +649 -0
  68. package/dist/src/duck/store.js +156 -120
  69. package/dist/src/duck/stream.js +10 -5
  70. package/dist/src/duck/sync.js +835 -268
  71. package/dist/src/duck/types.js +6 -5
  72. package/dist/src/duck/usage.js +324 -0
  73. package/dist/src/duck/users.js +64 -15
  74. package/dist/src/duck/verified.js +3 -0
  75. package/dist/src/duck/views.js +2 -3
  76. package/dist/src/lib/database-name.js +62 -0
  77. package/dist/src/lib/dotenv.js +17 -4
  78. package/dist/src/lib/log-buffer.js +68 -0
  79. package/dist/src/lib/pg-numeric.js +5 -2
  80. package/dist/src/lib/project-version.js +23 -23
  81. package/dist/src/lib/table-sync.js +267 -0
  82. package/dist/src/web/app.css +706 -66
  83. package/dist/src/web/app.js +327 -410
  84. package/dist/src/web/charts.js +229 -0
  85. package/dist/src/web/index.html +82 -18
  86. package/dist/src/web/pages/queries.js +192 -0
  87. package/dist/src/web/pages/status.js +446 -0
  88. package/dist/src/web/pages/syncs.js +155 -0
  89. package/dist/src/web/pages/tables.js +434 -0
  90. package/dist/src/web/pages/usage.js +397 -0
  91. package/dist/src/web/pages/users.js +218 -0
  92. package/dist/src/web/shared.js +568 -0
  93. package/dist/src/web/vendor/README.md +25 -0
  94. package/dist/src/web/vendor/geist-1.7.2/Geist-Variable.woff2 +0 -0
  95. package/dist/src/web/vendor/geist-1.7.2/GeistMono-Variable.woff2 +0 -0
  96. package/dist/src/web/vendor/geist-1.7.2/LICENSE.txt +92 -0
  97. package/dist/src/web/vendor/lucide-1.56.0/LICENSE.txt +43 -0
  98. package/dist/src/web/vendor/lucide-1.56.0/chart-column.mjs +29 -0
  99. package/dist/src/web/vendor/lucide-1.56.0/layout-dashboard.mjs +29 -0
  100. package/dist/src/web/vendor/lucide-1.56.0/logs.mjs +34 -0
  101. package/dist/src/web/vendor/lucide-1.56.0/menu.mjs +28 -0
  102. package/dist/src/web/vendor/lucide-1.56.0/square-terminal.mjs +28 -0
  103. package/dist/src/web/vendor/lucide-1.56.0/table.mjs +29 -0
  104. package/dist/src/web/vendor/lucide-1.56.0/users.mjs +29 -0
  105. package/dist/src/web/vendor/lucide-1.56.0/x.mjs +27 -0
  106. package/dist/src/web/vendor/uplot-1.6.32/LICENSE.txt +21 -0
  107. package/dist/src/web/vendor/uplot-1.6.32/uPlot.esm.js +6140 -0
  108. package/dist/src/web/vendor/uplot-1.6.32/uPlot.min.css +1 -0
  109. package/dist/src/web/vendor/zilla-slab-5.3.0/LICENSE.txt +93 -0
  110. package/dist/src/web/vendor/zilla-slab-5.3.0/zilla-slab-latin-700-normal.woff2 +0 -0
  111. package/package.json +10 -3
@@ -1,3 +1,17 @@
1
+ /**
2
+ * WHAT A STATEMENT IS, from Postgres 18's own parse tree (parser.ts), decided by node kind, never by text:
3
+ *
4
+ * - a SELECT that reads any table outside pg_catalog / information_schema: DuckDB's (`duckdb`), planned by the
5
+ * catalog Postgres and rewritten (src/duck/plan.ts) — the text here is only what the plan is made from;
6
+ * - a CATALOG statement (one that reads only `pg_catalog` / `information_schema`, or no table at all: `SELECT
7
+ * version()`, `SELECT 1`): forwarded by the server to the Postgres inside the process (catalog.ts), which answers it
8
+ * as Postgres;
9
+ * - a SESSION statement (`SET`, `SHOW`, `BEGIN` / `COMMIT`, `DISCARD`, `DEALLOCATE`): the server's;
10
+ * - an EXPLAIN: the statement it explains, classified as it would be alone (src/api/postgres/explain.ts);
11
+ * - anything else: REFUSED BY NAME (`Unsupported`), with its position in the statement, a SQLSTATE and the way
12
+ * out, never passed through on a guess. The switch has no default branch that accepts.
13
+ */
14
+ import { gapMark } from "../../duck/gaps.js";
1
15
  /** A statement, or a part of one, this listener does not answer: named, placed, with a SQLSTATE and the way out. */
2
16
  export class Unsupported extends Error {
3
17
  /** 0-based offset into the statement's text, or null when the whole statement is meant */
@@ -5,11 +19,14 @@ export class Unsupported extends Error {
5
19
  /** `0A000` feature not supported; `42601` syntax; `25006` read only; `22023` an invalid value */
6
20
  sqlstate;
7
21
  hint;
8
- constructor(message, offset, sqlstate = "0A000", hint) {
22
+ /** the registry entry that refused it (src/duck/gaps.ts): the request log's `gap`; null for any other refusal */
23
+ gap;
24
+ constructor(message, offset, sqlstate = "0A000", hint, gap = null) {
9
25
  super(message);
10
26
  this.offset = offset;
11
27
  this.sqlstate = sqlstate;
12
28
  this.hint = hint;
29
+ this.gap = gap;
13
30
  }
14
31
  }
15
32
  const kindOf = (n) => Object.keys(n)[0] ?? "";
@@ -40,6 +57,14 @@ function collect(n, kind, out = []) {
40
57
  }
41
58
  const INFORMATION_SCHEMA = "information_schema";
42
59
  const PG_CATALOG = "pg_catalog";
60
+ /** Postgres's IsTransactionExitStmt: what a failed block still accepts. `ROLLBACK TO` and `PREPARE TRANSACTION` are among
61
+ * them, each then refused here for being what it is, a savepoint or a prepared transaction, never for the block. */
62
+ export function endsFailedBlock(stmt) {
63
+ if (kindOf(stmt) !== "TransactionStmt")
64
+ return false;
65
+ const k = bodyOf(stmt).kind;
66
+ return k === "TRANS_STMT_COMMIT" || k === "TRANS_STMT_ROLLBACK" || k === "TRANS_STMT_ROLLBACK_TO" || k === "TRANS_STMT_PREPARE";
67
+ }
43
68
  // ------------------------------------------------------------------ entry
44
69
  /** A statement other than a SELECT or an EXPLAIN (`duckTranslate` takes those): the session's, or refused by name. */
45
70
  function sessionStatement(stmt) {
@@ -51,10 +76,10 @@ function sessionStatement(stmt) {
51
76
  const k = bodyOf(stmt).kind;
52
77
  const tag = k === "TRANS_STMT_BEGIN" ? "BEGIN" : k === "TRANS_STMT_START" ? "START TRANSACTION" : k === "TRANS_STMT_COMMIT" ? "COMMIT" : k === "TRANS_STMT_ROLLBACK" ? "ROLLBACK" : null;
53
78
  if (tag === null)
54
- throw new Unsupported(`${String(k).replace("TRANS_STMT_", "").toLowerCase()}: this connection is read-only and has no transactions; BEGIN, COMMIT and ROLLBACK are accepted and do nothing`, null);
79
+ throw new Unsupported(`${String(k).replace("TRANS_STMT_", "").toLowerCase()}: this connection is read-only and has no savepoints or prepared transactions; BEGIN, COMMIT and ROLLBACK are accepted, and a ROLLBACK undoes the block's SETs`, null);
55
80
  return { kind: "transaction", tag };
56
81
  }
57
- case "DiscardStmt": return { kind: "discard" };
82
+ case "DiscardStmt": return { kind: "discard", target: String(bodyOf(stmt).target ?? "DISCARD_ALL").replace(/^DISCARD_/, "") };
58
83
  case "DeallocateStmt": return { kind: "deallocate" };
59
84
  case "InsertStmt":
60
85
  case "UpdateStmt":
@@ -73,7 +98,7 @@ function sessionStatement(stmt) {
73
98
  case "CreateFunctionStmt":
74
99
  case "CreateSchemaStmt":
75
100
  case "VacuumStmt":
76
- throw new Unsupported(`${kind.replace(/Stmt$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}: this is a read-only copy of the database's tables; only SELECT, SET, SHOW and the transaction no-ops are accepted`, null, "25006");
101
+ throw new Unsupported(`${kind.replace(/Stmt$/, "").replace(/([a-z])([A-Z])/g, "$1 $2").toUpperCase()}: these are the database's tables, synced and read-only; only SELECT, SET, SHOW and the transaction no-ops are accepted`, null, "25006");
77
102
  case "PrepareStmt":
78
103
  case "ExecuteStmt": throw new Unsupported(`${kind === "PrepareStmt" ? "PREPARE" : "EXECUTE"} is not supported: use the protocol's prepared statements (every driver does)`, null);
79
104
  default:
@@ -90,6 +115,9 @@ function sessionStatement(stmt) {
90
115
  * (a review finding).
91
116
  */
92
117
  export function duckTranslate(stmt, text) {
118
+ const configured = setConfig(stmt);
119
+ if (configured !== null)
120
+ return configured;
93
121
  const kind = kindOf(stmt);
94
122
  // an EXPLAIN is the statement it explains (src/api/postgres/explain.ts, src/duck/explain.ts): its options read, then
95
123
  // that statement classified as it would be alone, by the server
@@ -109,6 +137,47 @@ export function duckTranslate(stmt, text) {
109
137
  return { kind: "catalog" };
110
138
  return { kind: "duckdb", sql: text, names: pgColumnNames(s) };
111
139
  }
140
+ /**
141
+ * `set_config(name, value, is_local)` IS A SET, and a session's SET is the listener's: forwarded, it ran on the catalog's
142
+ * ONE connection, as its superuser, outside any transaction, so its value stayed for EVERY session — `set_config(
143
+ * 'search_path', 'zzz', false)` moved the catalog's resolution of `current_setting` and `version()` to Postgres's own,
144
+ * and a `myapp.x` one session set another read (a review finding of #46). So every call of it is the session's or
145
+ * refused, wherever it is in the statement (an EXPLAIN ANALYZE's included): alone in a SELECT of no table, its
146
+ * arguments literals (what a tool sends: pgAdmin's `bytea_output`, an ORM's `search_path`), it is `SET name = value`,
147
+ * or `SET LOCAL` under `is_local`, answered as the function's row; any other form is the `set-config-forms` gap. null:
148
+ * no call of it.
149
+ */
150
+ function setConfig(stmt) {
151
+ const named = (n) => {
152
+ const parts = strings(bodyOf(n).funcname);
153
+ return parts[parts.length - 1] === "set_config" && (parts.length === 1 || (parts.length === 2 && parts[0] === PG_CATALOG));
154
+ };
155
+ const calls = collect(stmt, "FuncCall").filter(named);
156
+ if (calls.length === 0)
157
+ return null;
158
+ const refuse = (at) => {
159
+ throw new Unsupported(`set_config() is answered by Mason only alone in a SELECT, with literal arguments (${gapMark("set-config-forms")})`, at, "0A000", "write SET name = 'value', or SELECT set_config('name', 'value', false) on its own", "set-config-forms");
160
+ };
161
+ const at = loc(calls[0]);
162
+ if (kindOf(stmt) !== "SelectStmt")
163
+ return refuse(at);
164
+ const s = bodyOf(stmt);
165
+ if (Object.keys(s).some((k) => k !== "targetList" && k !== "limitOption" && k !== "op") || s.op !== "SETOP_NONE")
166
+ return refuse(at);
167
+ const targets = (s.targetList ?? []);
168
+ const target = targets.length === 1 ? bodyOf(targets[0]) : null;
169
+ if (target?.val === undefined || kindOf(target.val) !== "FuncCall" || !named(target.val))
170
+ return refuse(at);
171
+ const call = bodyOf(target.val);
172
+ if (Object.keys(call).some((k) => k !== "funcname" && k !== "args" && k !== "funcformat" && k !== "location"))
173
+ return refuse(at);
174
+ const args = (call.args ?? []).map((a) => kindOf(a) === "A_Const" ? bodyOf(a) : null);
175
+ const text = (c) => typeof c?.sval?.sval === "string" ? c.sval.sval : null;
176
+ const [name, value, local] = [text(args[0] ?? null), text(args[1] ?? null), args[2]?.boolval];
177
+ if (args.length !== 3 || name === null || value === null || local === undefined)
178
+ return refuse(at);
179
+ return { kind: "set_config", name: name.toLowerCase(), value, local: local.boolval === true, column: target.name ?? "set_config" };
180
+ }
112
181
  /**
113
182
  * THE NAMES POSTGRES GIVES A SELECT'S RESULT COLUMNS (`FigureColname`, src/backend/parser/parse_target.c), where DuckDB
114
183
  * gives others (`count(*)` is `count_star()`, `sum(x)` is `sum(x)`; Postgres says `count`, `sum`): an alias as written,
@@ -212,12 +281,15 @@ function figureColname(n) {
212
281
  }
213
282
  function setStatement(s) {
214
283
  const name = String(s.name ?? "").toLowerCase();
215
- if (s.kind === "VAR_RESET" || s.kind === "VAR_SET_DEFAULT")
216
- return { kind: "set", name, value: null, local: s.is_local === true };
284
+ if (s.kind === "VAR_RESET")
285
+ return { kind: "set", name, value: null, local: false, tag: "RESET" };
286
+ if (s.kind === "VAR_SET_DEFAULT")
287
+ return { kind: "set", name, value: null, local: s.is_local === true, tag: "SET" };
217
288
  if (s.kind === "VAR_RESET_ALL")
218
- return { kind: "set", name: "all", value: null, local: false };
289
+ return { kind: "set", name: "all", value: null, local: false, tag: "RESET" };
290
+ // SET TRANSACTION is for the transaction alone, whichever way it is spelt; SET SESSION CHARACTERISTICS is the session's
219
291
  if (s.kind === "VAR_SET_MULTI")
220
- return { kind: "set", name, value: "", local: s.is_local === true }; // SET SESSION CHARACTERISTICS …
292
+ return { kind: "set", name, value: "", local: name === "transaction", tag: "SET" };
221
293
  if (s.kind !== "VAR_SET_VALUE")
222
294
  throw new Unsupported(`SET ${name}: ${String(s.kind)} is not supported`, s.location ?? null);
223
295
  const parts = (s.args ?? []).map((a) => {
@@ -230,7 +302,7 @@ function setStatement(s) {
230
302
  }
231
303
  throw new Unsupported(`SET ${name}: a value of kind ${kindOf(a)} is not supported (a literal is)`, loc(a));
232
304
  });
233
- return { kind: "set", name, value: parts.join(", "), local: s.is_local === true };
305
+ return { kind: "set", name, value: parts.join(", "), local: s.is_local === true, tag: "SET" };
234
306
  }
235
307
  function constText(c) {
236
308
  if (c.sval !== undefined)
@@ -8,17 +8,30 @@
8
8
  import * as crypto from "node:crypto";
9
9
  /** Fail closed on the storage side: never let one request bloat the ledger. */
10
10
  export const MAX_STORED_PAYLOAD_BYTES = 64 * 1024;
11
+ /** The SQLSTATE of a cancelled statement: a CancelRequest, `mason cancel`, or a statement_timeout (Postgres's 57014). */
12
+ export const CANCELLED_SQLSTATE = "57014";
13
+ /** The SQLSTATE classes whose fault is Mason's or the machine's: XX internal, 53 resources, 57 an operator's, 58 system. */
14
+ export const FAILED_CLASSES = ["XX", "53", "57", "58"];
15
+ export const OUTCOMES = ["ok", "refused", "failed", "cancelled"];
11
16
  /**
12
- * A Postgres-listener statement's outcome in a word, from the SQLSTATE it was sent: `failed` where the fault is Mason's
13
- * or the machine's (classes XX internal, 53 resources, 57 a timeout or a cancel, 58 system), `refused` for the
14
- * statement's own, `ok` for none. Read by the listener's refusal line (server.ts `refusalLine`) and the request log
15
- * (src/duck/requests.ts) alike.
17
+ * A Postgres-listener statement's outcome in a word, from the SQLSTATE it was sent: `cancelled` for 57014 (a cancel or a
18
+ * timeout), `failed` where the fault is Mason's or the machine's (FAILED_CLASSES), `refused` for the statement's own,
19
+ * `ok` for none. Read by the listener's refusal line (server.ts `refusalLine`) and the request log (src/duck/requests.ts)
20
+ * alike; the ledger's filter and summary read the SAME rule as SQL (`outcomeSql`), held equal by tests/duck-requests.test.ts.
16
21
  */
17
22
  export function outcomeOf(sqlstate) {
18
23
  if (sqlstate === null || sqlstate === undefined || sqlstate === "")
19
24
  return "ok";
20
- return /^(XX|53|57|58)/.test(sqlstate) ? "failed" : "refused";
25
+ if (sqlstate === CANCELLED_SQLSTATE)
26
+ return "cancelled";
27
+ return FAILED_CLASSES.some((c) => sqlstate.startsWith(c)) ? "failed" : "refused";
21
28
  }
29
+ /** `outcomeOf` as a SQL expression over a SQLSTATE column: the one rule, for the ledger's filters and summary. */
30
+ export function outcomeSql(column) {
31
+ return `CASE WHEN ${column} IS NULL OR ${column} = '' THEN 'ok' WHEN ${column} = '${CANCELLED_SQLSTATE}' THEN 'cancelled' ` +
32
+ `WHEN left(${column}, 2) IN (${FAILED_CLASSES.map((c) => `'${c}'`).join(", ")}) THEN 'failed' ELSE 'refused' END`;
33
+ }
34
+ export const statusOf = (o) => o === "ok" ? "completed" : o === "cancelled" ? "cancelled" : "failed";
22
35
  /**
23
36
  * The caller's identity WITHOUT the credential: a truncated SHA-256 of what was presented. Distinct callers stay
24
37
  * distinguishable and repeat callers stay correlatable, while the secret itself is never written down — the log must
@@ -56,11 +56,11 @@ export function xminBeforeHolds(current, watermark) {
56
56
  return current >= watermark && current - watermark < 2n ** 30n;
57
57
  }
58
58
  /**
59
- * The wait before the next poll: MASON_POLL_MS, or four times what the last poll took when that is longer, so a
60
- * source whose tables take a while to read spends at most a fifth of its time on polls. Never sooner than either
61
- * (the test server: a cap of a minute polled a 22 M-row production table every 74 s for 6.5 hours under
62
- * MASON_POLL_MS=3600000, and a poll of 20 s every 60 s is a third of the source's time): the database's load decides,
63
- * and a slow poll's freshness is said by its own timing line.
59
+ * The wait before the next poll: the table's interval (its sync:, src/lib/table-sync.ts), or four times what the last
60
+ * poll took when that is longer, so a table that takes a while to read costs at most a fifth of the source's time.
61
+ * Never sooner than either (the test server: a cap of a minute polled a 22 M-row production table every 74 s for 6.5
62
+ * hours under an hourly interval, and a poll of 20 s every 60 s is a third of the source's time): the database's load
63
+ * decides, and a slow poll's freshness is said by its own timing line.
64
64
  */
65
65
  export function nextPollDelayMs(pollMs, lastPollMs) {
66
66
  return Math.max(pollMs, 4 * lastPollMs);
@@ -19,11 +19,15 @@ import { fileURLToPath } from "node:url";
19
19
  import { runnable } from "../lib/runnable.js";
20
20
  import { READY, STEP_MARK } from "./dev.js";
21
21
  import { liveRun } from "./runs.js";
22
- import { projectSource, theProject } from "./project.js";
22
+ import { projectSource, startSettingRefusal, theProject } from "./project.js";
23
23
  import { runListenerSettings } from "./pg-tls.js";
24
24
  import { demoChangesRefusal, demoPort } from "./demo.js";
25
+ import { recordRefusal } from "./replication-mode.js";
26
+ import { shownPath } from "./sources.js";
25
27
  import { endText, failed, jsonText, nextBlock } from "./command.js";
28
+ import { historyDaysSetting } from "../duck/history.js";
26
29
  import { DEV } from "./registry.js";
30
+ import { UI } from "./ui.js";
27
31
  import { out as styleOut, stepRenderer } from "./style.js";
28
32
  import { postgresLink, withoutPlaceholders } from "./pg-url.js";
29
33
  const say = (m) => { process.stdout.write(`${m}\n`); };
@@ -32,11 +36,13 @@ const SUPERVISE = path.join(path.dirname(fileURLToPath(import.meta.url)), "super
32
36
  /** The commands to run next, as `mason start` prints them once the run is up: one a line, what each does beside it
33
37
  * (not `mason status | mason logs | mason stop` on one line). */
34
38
  export const NEXT_STEPS = [
39
+ // the web page first: a first-time user's most useful next step (the run serves it; mason ui opens it, signed in)
40
+ ["mason ui", UI.summary],
35
41
  ["mason tables", "the database's tables, and what you can add"],
36
- ["mason add <table>", "copy a table into Mason"],
42
+ ["mason add <table>", "sync a table into Mason"],
37
43
  ["mason user add <name>", "a user for a BI tool or your app: its password and URL, printed once"],
38
44
  ["mason status", "what Mason is doing"],
39
- ["mason logs", "its log: every copy, poll and statement"],
45
+ ["mason logs", "its log: every sync, poll and statement"],
40
46
  ["mason stop", "stop Mason; the next mason start resumes where it stopped"],
41
47
  ];
42
48
  /** The ports a demo project's database takes (its URL's port, read as the run reads it), for the API's choice to avoid;
@@ -68,10 +74,27 @@ export async function devInBackground(args, o) {
68
74
  say(nextBlock([["mason status", "what it is doing"], ["mason stop", "stop it"]]));
69
75
  return 0;
70
76
  }
71
- // a demo project with --replication (src/cli/demo.ts): refused here too, where it is read, before a run is spawned
72
- const demoRefused = demoChangesRefusal(t.project.config, o.changes ?? null);
77
+ // a demo project whose sources file says sync: replication (src/cli/demo.ts): refused here too, where it is read,
78
+ // before a run is spawned — the sources file as the run reads it (a file it cannot read is the run's to say, in its checklist)
79
+ const src = projectSource(t.project);
80
+ const file = "message" in src ? null : src;
81
+ const shown = file === null ? "" : shownPath(t.project.root, file.file);
82
+ const demoRefused = demoChangesRefusal(t.project.config, file, shown);
73
83
  if (demoRefused)
74
84
  return failed("start", demoRefused, { json: o.json });
85
+ // a setting a start refuses, here where the person (or --json) reads it, by the run's own list (src/cli/project.ts)
86
+ const setting = startSettingRefusal(t.project, process.env, { serve: false });
87
+ if (setting !== null)
88
+ return failed("start", setting, { json: o.json });
89
+ // the history's days (MASON_HISTORY_DAYS, a number of days; the old MASON_REQUEST_LOG_DAYS refused), by the run's own
90
+ // check (src/duck/history.ts), refused here as in the run
91
+ const days = historyDaysSetting(process.env);
92
+ if (typeof days !== "number")
93
+ return failed("start", { code: "refused", ...days }, { json: o.json });
94
+ // what the config records and the file does not say (src/cli/replication-mode.ts), in the run's order: settings first
95
+ const unsaid = file === null ? null : recordRefusal(t.project.config, file, process.env, shown, "mason start");
96
+ if (unsaid !== null)
97
+ return failed("start", unsaid, { json: o.json });
75
98
  // a MASON_PG_PORT that is no port, or is held, is refused HERE, where the person (or --json) reads it, before a run is
76
99
  // spawned; the run checks again for itself (choosePgPort, src/cli/ports.ts), since a port may be taken in between.
77
100
  // A demo project's database port (its URL's, src/cli/demo.ts demoPort) is avoided as the run avoids it
@@ -166,7 +189,7 @@ export async function devInBackground(args, o) {
166
189
  continue;
167
190
  }
168
191
  if (/^\s+Web UI\s+mason ui\b/.test(l)) {
169
- steps.print(` ${st.dim("Web UI".padEnd("Postgres API".length))} ${st.cyan("mason ui")} ${st.dim("(the status page and the users, in your browser)")}`);
192
+ steps.print(` ${st.dim("Web UI".padEnd("Postgres API".length))} ${st.cyan("mason ui")} ${st.dim(`(${UI.summary})`)}`);
170
193
  continue;
171
194
  }
172
195
  // a demo project's line (src/cli/dev.ts: "Demo a new order lands every <n> s: …"), in the same column
@@ -0,0 +1,75 @@
1
+ /**
2
+ * `mason cancel <session>`: stops the statement a session of the Postgres API is running, exactly as a client's own
3
+ * cancel (the protocol's CancelRequest) stops it — the listener's one path (src/api/postgres/server.ts `interrupt`),
4
+ * through the run's `POST /api/cancel` (src/cli/run-server.ts). The client is told 57014 "canceling statement due to
5
+ * user request", and the request log records it as cancelled. `mason logs --running` lists the sessions.
6
+ */
7
+ import { failed, jsonText, parseCommand, reportText } from "./command.js";
8
+ import { out as styleOut } from "./style.js";
9
+ import { callRun } from "./control.js";
10
+ import { reach } from "./state.js";
11
+ import { guarded, oneLine, runFailure, spanText } from "./commands.js";
12
+ const out = (m) => { process.stdout.write(`${m}\n`); };
13
+ export const CANCEL_USAGE = `usage: mason cancel <session> [--statement <n>] [--json]
14
+
15
+ Stops the statement a session of the Postgres API is running now, as the client's own cancel would: the client is
16
+ told "canceling statement due to user request" (SQLSTATE 57014), its session stays open, and the request log keeps
17
+ the statement as cancelled. mason logs --running lists the statements running now, with their sessions and numbers.
18
+
19
+ mason logs --running
20
+ mason cancel 12 --statement 340
21
+ mason cancel 12
22
+
23
+ --statement <n> only that statement (its number in mason logs --running): if it ended and the session runs
24
+ another, nothing is cancelled and the answer says so. Without it, whatever the session runs now
25
+ is stopped, as a client's own cancel stops it.
26
+ --json as data: { cancelled: { session, statement, user, applicationName, method, startedAt, runningMs,
27
+ rows, query, queryTruncated } (the statement it stopped), next }
28
+ `;
29
+ export const CANCEL = {
30
+ needs: "run",
31
+ name: "cancel",
32
+ summary: "stop the statement a session of the Postgres API is running, as the client's cancel would: mason cancel 12",
33
+ usage: CANCEL_USAGE,
34
+ options: { statement: { type: "string" }, json: { type: "boolean" } },
35
+ json: ["cancelled", "next"],
36
+ };
37
+ export async function cancel(argv) {
38
+ const f = parseCommand(CANCEL, argv);
39
+ if (typeof f === "number")
40
+ return f;
41
+ const json = f.values.json === true;
42
+ const running = ["mason logs --running", "the statements running now, with their sessions"];
43
+ if (f.positionals.length !== 1 || !/^[1-9]\d*$/.test(f.positionals[0])) {
44
+ return failed("cancel", { message: f.positionals.length === 0 ? "name the session: mason cancel <session>" : `${f.positionals.join(" ")} is not a session's number`,
45
+ code: "usage", fix: "mason logs --running lists each statement running with its session", next: [running], usage: CANCEL_USAGE }, { json });
46
+ }
47
+ const session = Number(f.positionals[0]);
48
+ const statement = f.values.statement;
49
+ if (statement !== undefined && (typeof statement !== "string" || !/^[1-9]\d*$/.test(statement))) {
50
+ return failed("cancel", { message: `--statement ${String(statement)} is not a statement's number`, code: "usage",
51
+ fix: "mason logs --running lists each statement running with its number", next: [running], usage: CANCEL_USAGE }, { json });
52
+ }
53
+ const w = await reach(CANCEL, json);
54
+ if (w === null || !("run" in w))
55
+ return 1;
56
+ const run = w.run;
57
+ return guarded("cancel", json, async () => {
58
+ const r = await callRun(run, "POST", "/api/cancel", { session, ...(statement !== undefined ? { statement: Number(statement) } : {}) });
59
+ if (r.status !== 200)
60
+ return failed("cancel", runFailure(r, [running]), { json });
61
+ const c = r.body.cancelled;
62
+ const next = [[`mason logs --requests --outcome cancelled -n 5`, "the statements cancelled, this one among them once it ended"], running];
63
+ if (json) {
64
+ out(jsonText(CANCEL, { cancelled: c }, next));
65
+ return 0;
66
+ }
67
+ out(reportText({
68
+ headline: `Cancelled session ${c.session}'s statement: it ends now, and its client gets a "canceling statement" error.`,
69
+ details: [["Statement", oneLine(c.query) || "(no statement)"], ["Client", `${c.applicationName || "(no application_name)"}${c.user ? ` (user ${c.user})` : ""}`],
70
+ ["Running", `${spanText(c.runningMs / 1000)}, ${c.rows.toLocaleString("en-US")} row${c.rows === 1 ? "" : "s"} sent`]],
71
+ next,
72
+ }, styleOut()));
73
+ return 0;
74
+ });
75
+ }
@@ -105,6 +105,7 @@ export const FAILURE_CODES = {
105
105
  no_project: "no Mason project here or above (mason init makes one)",
106
106
  bad_config: "this folder is a Mason project whose .mason/config.json cannot be read: repair it, or move .mason/ aside and mason init",
107
107
  bad_source: "the project's sources file (mason/sources/<name>.yml) is missing or names something wrong: the file, the key and the way out are said",
108
+ bad_roles: "the project's roles file (mason/roles.yml) names something wrong: a table the sources file does not sync, a column the synced table lacks, a role with no table; the file, the key and the way out are said",
108
109
  not_running: "Mason is not running for the project (mason start)",
109
110
  unreachable: "Mason is running but does not answer (mason logs says why)",
110
111
  not_found: "a name nothing has: a table, a column, a user",