@sixb/deploy-ssh 0.2.0 → 0.2.6

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.
package/src/server/cli.ts CHANGED
@@ -3,6 +3,7 @@ import { readFile } from "node:fs/promises"
3
3
  import type { DeployRecord, DeployStatus } from "@sixb/core/deploy"
4
4
  import { followLogFiles, type LogLine, readRecentLogLines, renderProcessLogLine } from "./logs"
5
5
  import { loadProcessManifest, type ProcessManifest, statePath } from "./manifest"
6
+ import { runScript } from "./run"
6
7
  import { isMissing, isPidRunning, readProcessState } from "./state"
7
8
  import { runSupervisor, type SupervisorCommand, sendSupervisorCommand } from "./supervisor"
8
9
 
@@ -11,9 +12,12 @@ import { runSupervisor, type SupervisorCommand, sendSupervisorCommand } from "./
11
12
  * script, which pins the Bun version and manifest. `sixb deploy` reaches it over SSH.
12
13
  *
13
14
  * supervise run the deployment's processes (the systemd unit's command)
14
- * status [--json] [--check] --check exits 1 unless every process is running
15
+ * status [--json] [--check] [--candidate]
15
16
  * logs [service] [--tail n] [--follow]
16
17
  * restart|start|stop [service]
18
+ * stage <candidate-manifest>
19
+ * activate|discard
20
+ * run <staged> <path> [args...] run an uploaded script with `sixb run`; see ./run.ts
17
21
  */
18
22
  const argv = process.argv.slice(2)
19
23
 
@@ -25,9 +29,20 @@ try {
25
29
  }
26
30
 
27
31
  async function main(): Promise<void> {
32
+ // A script's arguments are anything, `--manifest` included; `ctl` appends the real one last.
33
+ if (argv[0] === "run") {
34
+ const [, staged, path, ...args] = argv.slice(0, -2)
35
+ const manifestPath = argv.at(-1)
36
+ if (argv.at(-2) !== "--manifest" || !manifestPath || !staged || !path) {
37
+ throw new Error("[SshTarget] Usage: run <staged> <path> [args...] --manifest <path>")
38
+ }
39
+ const manifest = await loadProcessManifest(manifestPath)
40
+ return process.exit(await runScript({ manifest, staged, path, args }))
41
+ }
42
+
28
43
  const manifestPath = option("--manifest")
29
44
  if (!manifestPath) throw new Error("[SshTarget] --manifest is required.")
30
- const [command, service] = positionals()
45
+ const [command, arg] = positionals()
31
46
 
32
47
  switch (command) {
33
48
  case "supervise":
@@ -37,7 +52,7 @@ async function main(): Promise<void> {
37
52
  case "status":
38
53
  return status(await loadProcessManifest(manifestPath))
39
54
  case "logs":
40
- return logs(await loadProcessManifest(manifestPath), service)
55
+ return logs(await loadProcessManifest(manifestPath), arg)
41
56
  case "restart":
42
57
  case "start":
43
58
  case "stop":
@@ -45,10 +60,22 @@ async function main(): Promise<void> {
45
60
  await sendSupervisorCommand(
46
61
  await loadProcessManifest(manifestPath),
47
62
  command satisfies SupervisorCommand,
48
- service
63
+ { service: arg }
49
64
  )
50
65
  )
51
66
  return
67
+ case "stage":
68
+ if (!arg) throw new Error("[SshTarget] Usage: stage <candidate-manifest> --manifest <path>")
69
+ console.log(
70
+ await sendSupervisorCommand(await loadProcessManifest(manifestPath), "stage", {
71
+ manifestPath: arg,
72
+ })
73
+ )
74
+ return
75
+ case "activate":
76
+ case "discard":
77
+ console.log(await sendSupervisorCommand(await loadProcessManifest(manifestPath), command))
78
+ return
52
79
  default:
53
80
  throw new Error(`[SshTarget] Unknown command '${command ?? ""}'.`)
54
81
  }
@@ -57,11 +84,12 @@ async function main(): Promise<void> {
57
84
  async function status(manifest: ProcessManifest): Promise<void> {
58
85
  const state = await readProcessState(statePath(manifest))
59
86
  const running = state !== null && isPidRunning(state.supervisorPid)
87
+ const sourceInstances = flag("--candidate") ? (state?.staged ?? []) : (state?.instances ?? [])
60
88
  const report: DeployStatus = {
61
89
  release: await readRelease(manifest.releasePath),
62
90
  running,
63
91
  processes: running
64
- ? state.instances.map((instance) => ({
92
+ ? sourceInstances.map((instance) => ({
65
93
  service: instance.service,
66
94
  instance: instance.instance,
67
95
  status: instance.status,
@@ -81,13 +109,19 @@ async function status(manifest: ProcessManifest): Promise<void> {
81
109
  (process) => process.status !== "running" || process.restarts > 0
82
110
  )
83
111
  if (!running) console.error("The supervisor is not running.")
112
+ else if (flag("--candidate") && report.processes.length === 0) {
113
+ console.error("No candidate processes are staged.")
114
+ }
84
115
  for (const process of down) {
85
116
  const label =
86
117
  process.instance === 0 ? process.service : `${process.service}#${process.instance}`
87
- const state = process.status === "running" ? `restarted ${process.restarts}x` : process.status
88
- console.error(`${label} ${state}${process.lastError ? `: ${process.lastError}` : ""}`)
118
+ const stateText =
119
+ process.status === "running" ? `restarted ${process.restarts}x` : process.status
120
+ console.error(`${label} ${stateText}${process.lastError ? `: ${process.lastError}` : ""}`)
121
+ }
122
+ if (!running || down.length > 0 || (flag("--candidate") && report.processes.length === 0)) {
123
+ process.exit(1)
89
124
  }
90
- if (!running || down.length > 0) process.exit(1)
91
125
  return
92
126
  }
93
127
  console.log(JSON.stringify(report))
@@ -1,10 +1,15 @@
1
1
  import { readFile } from "node:fs/promises"
2
2
  import { resolve } from "node:path"
3
+ import type { DeploySlot } from "../layout"
4
+
5
+ export type ProcessServiceKind = "http" | "singleton" | "workers" | "script"
3
6
 
4
7
  /** What the supervisor runs for one deployment, written by `sixb deploy` on each deploy. */
5
8
  export interface ProcessManifest {
6
9
  readonly version: 1
7
10
  readonly name: string
11
+ /** Which port pair (`blue` or `green`) this release's HTTP services bind. */
12
+ readonly slot?: DeploySlot
8
13
  /** The project directory every process starts in. */
9
14
  readonly cwd: string
10
15
  /** Supervisor state, control requests, and logs live here. */
@@ -12,11 +17,17 @@ export interface ProcessManifest {
12
17
  readonly logDir: string
13
18
  /** Written by the deploy; read back by `status`. */
14
19
  readonly releasePath: string
20
+ /**
21
+ * The environment every service starts from, before its own additions: what `ctl run` gives a
22
+ * script. Absent from deployments made before scripts could run.
23
+ */
24
+ readonly env?: Readonly<Record<string, string>>
15
25
  readonly services: readonly ProcessServiceManifest[]
16
26
  }
17
27
 
18
28
  export interface ProcessServiceManifest {
19
29
  readonly name: string
30
+ readonly kind?: ProcessServiceKind
20
31
  readonly processName: string
21
32
  readonly command: string
22
33
  readonly args: readonly string[]
@@ -27,6 +38,13 @@ export interface ProcessServiceManifest {
27
38
  readonly maxMemory?: string
28
39
  }
29
40
 
41
+ const SERVICE_KINDS: readonly ProcessServiceKind[] = ["http", "singleton", "workers", "script"]
42
+
43
+ export function isOverlapSafeService(service: ProcessServiceManifest): boolean {
44
+ if (service.kind) return service.kind === "http" || service.kind === "workers"
45
+ return service.name === "api" || service.name === "app" || service.name === "workers"
46
+ }
47
+
30
48
  export async function loadProcessManifest(path: string): Promise<ProcessManifest> {
31
49
  return parseProcessManifest(JSON.parse(await readFile(path, "utf8")), path)
32
50
  }
@@ -49,14 +67,17 @@ export function parseProcessManifest(value: unknown, source = "process manifest"
49
67
  if (!Array.isArray(manifest.services)) {
50
68
  throw new Error(`[SshTarget] ${source}.services must be an array`)
51
69
  }
70
+ const slot = parseSlot(manifest.slot, `${source}.slot`)
52
71
 
53
72
  return {
54
73
  version: 1,
55
74
  name: string(manifest.name, `${source}.name`),
75
+ ...(slot === undefined ? {} : { slot }),
56
76
  cwd: string(manifest.cwd, `${source}.cwd`),
57
77
  runDir: string(manifest.runDir, `${source}.runDir`),
58
78
  logDir: string(manifest.logDir, `${source}.logDir`),
59
79
  releasePath: string(manifest.releasePath, `${source}.releasePath`),
80
+ ...(manifest.env === undefined ? {} : { env: environment(manifest.env, `${source}.env`) }),
60
81
  services: manifest.services.map((service, index) =>
61
82
  parseService(service, `${source}.services[${index}]`)
62
83
  ),
@@ -68,19 +89,16 @@ function parseService(value: unknown, source: string): ProcessServiceManifest {
68
89
  if (!Array.isArray(service.args) || service.args.some((arg) => typeof arg !== "string")) {
69
90
  throw new Error(`[SshTarget] ${source}.args must be an array of strings`)
70
91
  }
71
- const env = record(service.env, `${source}.env`)
72
- for (const [key, variable] of Object.entries(env)) {
73
- if (typeof variable !== "string") {
74
- throw new Error(`[SshTarget] ${source}.env.${key} must be a string`)
75
- }
76
- }
92
+ const env = environment(service.env, `${source}.env`)
93
+ const kind = parseKind(service.kind, `${source}.kind`)
77
94
 
78
95
  return {
79
96
  name: string(service.name, `${source}.name`),
97
+ ...(kind === undefined ? {} : { kind }),
80
98
  processName: string(service.processName, `${source}.processName`),
81
99
  command: string(service.command, `${source}.command`),
82
100
  args: service.args,
83
- env: env as Record<string, string>,
101
+ env,
84
102
  instances: positiveInteger(service.instances, `${source}.instances`),
85
103
  killTimeoutMs: positiveInteger(service.killTimeoutMs, `${source}.killTimeoutMs`),
86
104
  restartDelayMs: positiveInteger(service.restartDelayMs, `${source}.restartDelayMs`),
@@ -90,6 +108,29 @@ function parseService(value: unknown, source: string): ProcessServiceManifest {
90
108
  }
91
109
  }
92
110
 
111
+ function parseSlot(value: unknown, source: string): DeploySlot | undefined {
112
+ if (value === undefined) return undefined
113
+ if (value === "blue" || value === "green") return value
114
+ throw new Error(`[SshTarget] ${source} must be 'blue' or 'green'`)
115
+ }
116
+
117
+ function parseKind(value: unknown, source: string): ProcessServiceKind | undefined {
118
+ if (value === undefined) return undefined
119
+ if (typeof value === "string" && (SERVICE_KINDS as readonly string[]).includes(value)) {
120
+ return value as ProcessServiceKind
121
+ }
122
+ throw new Error(`[SshTarget] ${source} must be one of: ${SERVICE_KINDS.join(", ")}`)
123
+ }
124
+
125
+ function environment(value: unknown, source: string): Record<string, string> {
126
+ const env = record(value, source)
127
+ for (const [key, variable] of Object.entries(env)) {
128
+ if (typeof variable !== "string")
129
+ throw new Error(`[SshTarget] ${source}.${key} must be a string`)
130
+ }
131
+ return env as Record<string, string>
132
+ }
133
+
93
134
  function record(value: unknown, source: string): Record<string, unknown> {
94
135
  if (typeof value !== "object" || value === null || Array.isArray(value)) {
95
136
  throw new Error(`[SshTarget] ${source} must be an object`)
@@ -104,7 +145,7 @@ function string(value: unknown, source: string): string {
104
145
  return value
105
146
  }
106
147
 
107
- function positiveInteger(value: unknown, source: string): number {
148
+ function positiveInteger(value: unknown, source: number | string): number {
108
149
  if (!Number.isInteger(value) || (value as number) < 1) {
109
150
  throw new Error(`[SshTarget] ${source} must be a positive integer`)
110
151
  }
@@ -0,0 +1,246 @@
1
+ import { createHash } from "node:crypto"
2
+ import { mkdir, readdir, readFile, realpath, rm, rmdir, stat, writeFile } from "node:fs/promises"
3
+ import { constants } from "node:os"
4
+ import { dirname, join, relative, resolve } from "node:path"
5
+ import type { ProcessManifest } from "./manifest"
6
+ import { isPidRunning } from "./state"
7
+
8
+ /**
9
+ * `ctl run <staged> <path> [args...]`: puts an uploaded script at `path` in the deployed project and
10
+ * runs `sixb run` on it there, so its imports resolve against the deployed code, with the
11
+ * environment the deployment's services start from. The caller holds the deploy lock shared for
12
+ * the whole run, so no deploy replaces that code or migrates its storage underneath. Resolves with
13
+ * the exit code to end with.
14
+ *
15
+ * absent write it, and delete it afterwards
16
+ * identical run the deployed file in place
17
+ * different refuse: the deployed file is someone's committed work
18
+ *
19
+ * One run per path at a time: a second run of the same new file would find the first one's copy,
20
+ * and the first one's cleanup would delete it underneath the second. Each run marks its path, and
21
+ * whether it wrote the file, so a later run removes what a killed one left in the deployed code.
22
+ */
23
+ export async function runScript(input: {
24
+ readonly manifest: ProcessManifest
25
+ readonly staged: string
26
+ readonly path: string
27
+ readonly args: readonly string[]
28
+ }): Promise<number> {
29
+ const { manifest, staged, path } = input
30
+ try {
31
+ assertProjectPath(path)
32
+ if (!manifest.env) {
33
+ throw new Error(
34
+ `[SshTarget] ${manifest.name} was deployed before sixb run could run scripts on it. Deploy it again.`
35
+ )
36
+ }
37
+ const project = manifest.cwd
38
+ const marks = join(manifest.runDir, "scripts")
39
+ await removeAbandoned(marks, project)
40
+ const mark = await claimPath(marks, path)
41
+ try {
42
+ const target = resolve(project, path)
43
+ const created = await placeScript(project, target, path, await readFile(staged))
44
+ if (created) await mark.wrote(await stat(target))
45
+ try {
46
+ return await runSixb(project, path, input.args, manifest.env)
47
+ } finally {
48
+ if (created) await removeCreated(target, created)
49
+ }
50
+ } finally {
51
+ await mark.release()
52
+ }
53
+ } finally {
54
+ await rm(staged, { force: true })
55
+ }
56
+ }
57
+
58
+ /** A path relative to the project with forward slashes, which `sixb run` records as given. */
59
+ function assertProjectPath(path: string): void {
60
+ if (
61
+ path === "" ||
62
+ path.startsWith("/") ||
63
+ path.includes("\\") ||
64
+ path.includes("\0") ||
65
+ path.split("/").some((segment) => segment === "" || segment === "." || segment === "..")
66
+ ) {
67
+ throw new Error(`[SshTarget] '${path}' is not a path inside the project.`)
68
+ }
69
+ }
70
+
71
+ /** What a run records about its path while it runs. */
72
+ interface Mark {
73
+ readonly pid: number
74
+ readonly path: string
75
+ /** The file the run wrote, so it is the run's to remove while it is still that file. */
76
+ readonly wrote?: { readonly ino: number; readonly mtimeMs: number }
77
+ }
78
+
79
+ /**
80
+ * Marks `path` as running under this process's id until `release`. A mark whose process is gone
81
+ * was left by a run that was killed: `removeAbandoned` clears it first.
82
+ */
83
+ async function claimPath(
84
+ marks: string,
85
+ path: string
86
+ ): Promise<{ wrote(file: Mark["wrote"]): Promise<void>; release(): Promise<void> }> {
87
+ const file = join(marks, `${createHash("sha256").update(path).digest("hex")}.json`)
88
+ const record = (wrote?: Mark["wrote"]) =>
89
+ JSON.stringify({ pid: process.pid, path, ...(wrote ? { wrote } : {}) } satisfies Mark)
90
+ try {
91
+ await writeFile(file, record(), { flag: "wx" })
92
+ } catch (error) {
93
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error
94
+ throw new Error(`[SshTarget] ${path} is already running on the deployment.`)
95
+ }
96
+ return {
97
+ wrote: (written) =>
98
+ writeFile(file, record(written && { ino: written.ino, mtimeMs: written.mtimeMs })),
99
+ release: () => rm(file, { force: true }),
100
+ }
101
+ }
102
+
103
+ /**
104
+ * Clears the marks of runs whose process is gone, removing each file such a run wrote unless
105
+ * something has replaced it since, such as a deploy of the same path.
106
+ */
107
+ async function removeAbandoned(marks: string, project: string): Promise<void> {
108
+ await mkdir(marks, { recursive: true })
109
+ for (const name of await readdir(marks)) {
110
+ const file = join(marks, name)
111
+ const mark = await readMark(file)
112
+ if (mark && isPidRunning(mark.pid)) continue
113
+ if (mark?.wrote) {
114
+ try {
115
+ assertProjectPath(mark.path)
116
+ const target = resolve(project, mark.path)
117
+ const current = await stat(target)
118
+ if (current.ino === mark.wrote.ino && current.mtimeMs === mark.wrote.mtimeMs) {
119
+ await rm(target, { force: true })
120
+ }
121
+ } catch {
122
+ // Gone already, or a mark this code did not write: nothing to remove.
123
+ }
124
+ }
125
+ await rm(file, { force: true })
126
+ }
127
+ }
128
+
129
+ async function readMark(file: string): Promise<Mark | null> {
130
+ try {
131
+ const mark = JSON.parse(await readFile(file, "utf8")) as Partial<Mark>
132
+ if (typeof mark.pid !== "number" || typeof mark.path !== "string") return null
133
+ const wrote = mark.wrote
134
+ return typeof wrote?.ino === "number" && typeof wrote.mtimeMs === "number"
135
+ ? { pid: mark.pid, path: mark.path, wrote: { ino: wrote.ino, mtimeMs: wrote.mtimeMs } }
136
+ : { pid: mark.pid, path: mark.path }
137
+ } catch {
138
+ return null
139
+ }
140
+ }
141
+
142
+ /** Where the script was written, for cleanup: the first directory it had to make. */
143
+ interface Created {
144
+ readonly firstDirectory: string | null
145
+ }
146
+
147
+ async function placeScript(
148
+ project: string,
149
+ target: string,
150
+ path: string,
151
+ source: Buffer
152
+ ): Promise<Created | null> {
153
+ // Checked before anything is made: a symlinked directory in the deployed code must not carry
154
+ // the script, or the directories made for it, out of the project.
155
+ const existing = await nearestExisting(dirname(target))
156
+ if (relative(await realpath(project), await realpath(existing)).startsWith("..")) {
157
+ throw new Error(`[SshTarget] '${path}' leads outside the deployed project.`)
158
+ }
159
+ const firstDirectory = existing === dirname(target) ? null : firstMissing(target, existing)
160
+ await mkdir(dirname(target), { recursive: true })
161
+
162
+ try {
163
+ await writeFile(target, source, { flag: "wx", mode: 0o600 })
164
+ return { firstDirectory }
165
+ } catch (error) {
166
+ if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error
167
+ }
168
+
169
+ const deployed = await readFile(target)
170
+ if (!deployed.equals(source)) {
171
+ throw new Error(
172
+ `[SshTarget] The deployed ${path} differs from yours. Rename your copy, or deploy it first.`
173
+ )
174
+ }
175
+ return null
176
+ }
177
+
178
+ async function nearestExisting(directory: string): Promise<string> {
179
+ let current = directory
180
+ while (!(await stat(current).catch(() => null)) && dirname(current) !== current) {
181
+ current = dirname(current)
182
+ }
183
+ return current
184
+ }
185
+
186
+ /** The directory just below `existing` on the way to `target`. */
187
+ function firstMissing(target: string, existing: string): string {
188
+ let current = dirname(target)
189
+ while (dirname(current) !== existing) current = dirname(current)
190
+ return current
191
+ }
192
+
193
+ async function removeCreated(target: string, created: Created): Promise<void> {
194
+ await rm(target, { force: true })
195
+ if (!created.firstDirectory) return
196
+ // Only directories left empty: whatever the script wrote next to itself stays.
197
+ for (let current = dirname(target); ; current = dirname(current)) {
198
+ const removed = await rmdir(current).then(
199
+ () => true,
200
+ () => false
201
+ )
202
+ if (!removed || current === created.firstDirectory) return
203
+ }
204
+ }
205
+
206
+ /**
207
+ * The project's own `sixb run`, on this Bun, with the environment the release's services start
208
+ * from; the project's `.env` fills in the rest, as it does for them. It shares the terminal, so
209
+ * Ctrl-C reaches it from there. A dropped connection hangs up only the session leader, which is
210
+ * this process, so the hangup is passed on, as is a SIGTERM sent here.
211
+ */
212
+ async function runSixb(
213
+ project: string,
214
+ path: string,
215
+ args: readonly string[],
216
+ env: Readonly<Record<string, string>>
217
+ ): Promise<number> {
218
+ const child = Bun.spawn(
219
+ [process.execPath, join(project, "node_modules", ".bin", "sixb"), "run", path, ...args],
220
+ {
221
+ cwd: project,
222
+ stdio: ["inherit", "inherit", "inherit"],
223
+ env: {
224
+ ...process.env,
225
+ ...env,
226
+ PATH: `${dirname(process.execPath)}:${process.env.PATH ?? ""}`,
227
+ },
228
+ }
229
+ )
230
+ const ignore = () => {}
231
+ const hangUp = () => child.kill("SIGHUP")
232
+ const terminate = () => child.kill("SIGTERM")
233
+ process.on("SIGINT", ignore)
234
+ process.on("SIGHUP", hangUp)
235
+ process.on("SIGTERM", terminate)
236
+ try {
237
+ const exitCode = await child.exited
238
+ const signal = child.signalCode
239
+ if (signal === null) return exitCode
240
+ return 128 + (typeof signal === "number" ? signal : (constants.signals[signal] ?? 0))
241
+ } finally {
242
+ process.off("SIGINT", ignore)
243
+ process.off("SIGHUP", hangUp)
244
+ process.off("SIGTERM", terminate)
245
+ }
246
+ }
@@ -1,4 +1,5 @@
1
1
  import { readFile, rename, writeFile } from "node:fs/promises"
2
+ import type { DeploySlot } from "../layout"
2
3
 
3
4
  export type ProcessInstanceStatus = "starting" | "running" | "stopping" | "stopped" | "exited"
4
5
 
@@ -8,7 +9,12 @@ export interface ProcessState {
8
9
  readonly name: string
9
10
  readonly supervisorPid: number
10
11
  readonly updatedAt: string
12
+ readonly slot?: DeploySlot
11
13
  readonly instances: readonly ProcessInstanceState[]
14
+ /** Overlap-safe instances of a candidate release waiting to cut over. */
15
+ readonly staged?: readonly ProcessInstanceState[]
16
+ /** Release `cwd`s still held by background-draining processes after a cutover. */
17
+ readonly retiringCwds?: readonly string[]
12
18
  }
13
19
 
14
20
  export interface ProcessInstanceState {
@@ -66,7 +72,7 @@ export function parseProcessState(value: unknown, source = "process state"): Pro
66
72
  if (!state || state.version !== 1 || !Array.isArray(state.instances)) {
67
73
  throw new Error(`[SshTarget] ${source} is not a supervisor state file`)
68
74
  }
69
- for (const instance of state.instances) {
75
+ for (const instance of [...state.instances, ...(state.staged ?? [])]) {
70
76
  if (!STATUSES.includes(instance.status)) {
71
77
  throw new Error(`[SshTarget] ${source} has an instance with status '${instance.status}'`)
72
78
  }
@@ -84,5 +90,5 @@ export function isPidRunning(pid: number): boolean {
84
90
  }
85
91
 
86
92
  export function isMissing(error: unknown): boolean {
87
- return error instanceof Error && "code" in error && error.code === "ENOENT"
93
+ return (error as NodeJS.ErrnoException | null)?.code === "ENOENT"
88
94
  }