@sixb/deploy-ssh 0.2.5 → 0.2.7

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 (64) hide show
  1. package/README.md +51 -42
  2. package/dist/check/index.d.ts +24 -0
  3. package/dist/check/index.d.ts.map +1 -0
  4. package/dist/check/judge.d.ts +23 -0
  5. package/dist/check/judge.d.ts.map +1 -0
  6. package/dist/index.js +599 -1102
  7. package/dist/index.js.map +10 -15
  8. package/dist/layout.d.ts +91 -18
  9. package/dist/layout.d.ts.map +1 -1
  10. package/dist/operations.d.ts +5 -2
  11. package/dist/operations.d.ts.map +1 -1
  12. package/dist/plan.d.ts +25 -0
  13. package/dist/plan.d.ts.map +1 -0
  14. package/dist/render.d.ts +20 -10
  15. package/dist/render.d.ts.map +1 -1
  16. package/dist/server/manifest.d.ts +15 -3
  17. package/dist/server/manifest.d.ts.map +1 -1
  18. package/dist/server/release-host.d.ts +4 -0
  19. package/dist/server/release-host.d.ts.map +1 -0
  20. package/dist/server/release.d.ts +46 -0
  21. package/dist/server/release.d.ts.map +1 -0
  22. package/dist/server/state.d.ts +2 -0
  23. package/dist/server/state.d.ts.map +1 -1
  24. package/dist/server/supervisor.d.ts +12 -4
  25. package/dist/server/supervisor.d.ts.map +1 -1
  26. package/dist/ssh-target.d.ts +3 -18
  27. package/dist/ssh-target.d.ts.map +1 -1
  28. package/dist/transport.d.ts.map +1 -1
  29. package/package.json +3 -3
  30. package/src/bootstrap.sh +93 -0
  31. package/src/check/index.ts +117 -0
  32. package/src/check/judge.ts +299 -0
  33. package/src/check/probe.sh +99 -0
  34. package/src/layout.ts +117 -34
  35. package/src/operations.ts +104 -61
  36. package/src/plan.ts +59 -0
  37. package/src/render.ts +128 -31
  38. package/src/server/cli.ts +26 -9
  39. package/src/server/manifest.ts +42 -4
  40. package/src/server/release-host.ts +81 -0
  41. package/src/server/release.ts +738 -0
  42. package/src/server/state.ts +3 -1
  43. package/src/server/supervisor.ts +127 -55
  44. package/src/sh.d.ts +4 -0
  45. package/src/ssh-target.ts +46 -227
  46. package/src/transport.ts +28 -12
  47. package/dist/access.d.ts +0 -11
  48. package/dist/access.d.ts.map +0 -1
  49. package/dist/check.d.ts +0 -31
  50. package/dist/check.d.ts.map +0 -1
  51. package/dist/ci.d.ts +0 -27
  52. package/dist/ci.d.ts.map +0 -1
  53. package/dist/keys.d.ts +0 -13
  54. package/dist/keys.d.ts.map +0 -1
  55. package/dist/scripts.d.ts +0 -38
  56. package/dist/scripts.d.ts.map +0 -1
  57. package/dist/setup.d.ts +0 -32
  58. package/dist/setup.d.ts.map +0 -1
  59. package/src/access.ts +0 -107
  60. package/src/check.ts +0 -231
  61. package/src/ci.ts +0 -88
  62. package/src/keys.ts +0 -57
  63. package/src/scripts.ts +0 -323
  64. package/src/setup.ts +0 -203
package/src/layout.ts CHANGED
@@ -1,74 +1,157 @@
1
1
  import { posix } from "node:path"
2
+ import type { DeployHttpServiceName } from "@sixb/core/deploy"
3
+
4
+ /** The read-only token a deploy pulls `.env` with, for a project with a source. */
5
+ export const ENV_TOKEN_FILE = "env-token"
2
6
 
3
7
  /**
4
- * Where a deployment lives on its server. Everything but the Bun binaries and the Caddy route
5
- * sits in one directory in the deploy user's home, so projects under one user never share files.
6
- *
7
- * ~/<name>/code the deployed commit; the project is `code/<projectPath>`
8
- * ~/<name>/env-token the read-only token a deploy pulls `.env` with, if it has a source
9
- * ~/<name>/deploy lock, uploads, file list, release record, process manifest, ctl
10
- * ~/<name>/run supervisor state, control requests, and logs
11
- * ~/.sixb/bun/<v> Bun, shared by the user's projects that pin the same version
8
+ * A deployment runs in one of two slots. A release starts in the idle one, beside the live one,
9
+ * and takes traffic once it is healthy.
12
10
  */
13
- export const ENV_TOKEN_FILE = "env-token"
11
+ export type DeploySlot = "blue" | "green"
14
12
 
13
+ export const SLOTS: readonly DeploySlot[] = ["blue", "green"]
14
+
15
+ /** The loopback ports each slot's HTTP services listen on. Caddy forwards to the live slot's. */
16
+ export const SLOT_PORTS = {
17
+ blue: { app: 3001, api: 3002 },
18
+ green: { app: 3011, api: 3012 },
19
+ } as const satisfies Record<DeploySlot, Record<DeployHttpServiceName, number>>
20
+
21
+ export function otherSlot(slot: DeploySlot): DeploySlot {
22
+ return slot === "blue" ? "green" : "blue"
23
+ }
24
+
25
+ /**
26
+ * Where a deployment lives on its server: one folder in the deploy account's home, plus Bun, the
27
+ * slot service and the Caddy routes.
28
+ *
29
+ * ~/<name>/releases/<id> immutable releases: code, node_modules, .sixb/dist, .env
30
+ * ~/<name>/current the live release
31
+ * ~/<name>/code `current`, for scripts and older tools that look here
32
+ * ~/<name>/shared/.env the `.env` kept on the server, for a project without a source
33
+ * ~/<name>/env-token the token a deploy pulls `.env` with, for a project with one
34
+ * ~/<name>/deploy/ lock, uploads, release record, live slot, slot launchers, ctl
35
+ * ~/<name>/run/<slot>/ each slot's supervisor state, control requests and logs
36
+ * ~/.sixb/bun/<version>/ Bun, shared by releases on the same version
37
+ */
15
38
  export interface DeploymentLayout {
39
+ readonly name: string
40
+ readonly home: string
16
41
  readonly root: string
42
+ readonly releasesDir: string
43
+ readonly currentLink: string
17
44
  readonly code: string
45
+ readonly sharedEnv: string
18
46
  readonly envToken: string
19
- readonly project: string
20
47
  readonly deployDir: string
21
48
  readonly incomingDir: string
49
+ readonly runsDir: string
22
50
  readonly lock: string
23
- readonly fileList: string
24
- readonly manifest: string
25
51
  readonly releaseRecord: string
26
- /** Runs the server half of this package with the project's Bun and manifest. */
52
+ /** Names the live slot. */
53
+ readonly liveSlotFile: string
54
+ /** What `status`, `logs` and the other operations run: the live release's server half. */
27
55
  readonly ctl: string
56
+ readonly unitDir: string
57
+ /** The slot service's template, instantiated as `sixb-<name>@blue` and `sixb-<name>@green`. */
58
+ readonly unitTemplate: string
59
+ readonly caddyDir: string
60
+ readonly caddySnippet: string
61
+ }
62
+
63
+ export interface SlotLayout {
64
+ readonly slot: DeploySlot
65
+ readonly unit: string
66
+ readonly manifest: string
67
+ /** What the slot's service runs: its release's supervisor, with its Bun. */
68
+ readonly launcher: string
28
69
  readonly runDir: string
29
70
  readonly logDir: string
30
- readonly bunDir: string
31
- readonly bun: string
32
- readonly unitName: string
71
+ }
72
+
73
+ /** A deployment from before slots: one service, one manifest. Adopted by its first slot deploy. */
74
+ export interface LegacyLayout {
33
75
  readonly unit: string
34
- readonly caddyDir: string
35
- readonly caddySnippet: string
76
+ readonly unitPath: string
77
+ readonly manifest: string
36
78
  }
37
79
 
80
+ /** Where a deployment lives: under the home of the account it runs as, whichever that is. */
38
81
  export function deploymentLayout(input: {
39
82
  readonly home: string
40
83
  readonly user: string
41
84
  readonly name: string
42
- readonly projectPath: string
43
- readonly bunVersion: string
44
- }): DeploymentLayout {
85
+ }) {
45
86
  const root = posix.join(input.home, input.name)
46
- const code = posix.join(root, "code")
47
87
  const deployDir = posix.join(root, "deploy")
48
- const runDir = posix.join(root, "run")
49
- const bunDir = posix.join(input.home, ".sixb", "bun", input.bunVersion)
50
- const unitName = `sixb-${input.name}.service`
88
+ const unitDir = posix.join(input.home, ".config", "systemd", "user")
89
+ // Each account writes routes only in its own folder, which the server's Caddyfile imports.
51
90
  const caddyDir = posix.join("/etc/caddy/sixb.d", input.user)
52
-
53
91
  return {
92
+ name: input.name,
93
+ home: input.home,
54
94
  root,
55
- code,
95
+ releasesDir: posix.join(root, "releases"),
96
+ currentLink: posix.join(root, "current"),
97
+ code: posix.join(root, "code"),
98
+ sharedEnv: posix.join(root, "shared", ".env"),
56
99
  envToken: posix.join(root, ENV_TOKEN_FILE),
57
- project: posix.join(code, input.projectPath),
58
100
  deployDir,
59
101
  incomingDir: posix.join(deployDir, "incoming"),
102
+ runsDir: posix.join(deployDir, "runs"),
60
103
  lock: posix.join(deployDir, "lock"),
61
- fileList: posix.join(deployDir, "files.txt"),
62
- manifest: posix.join(deployDir, "processes.json"),
63
104
  releaseRecord: posix.join(deployDir, "release.json"),
105
+ liveSlotFile: posix.join(deployDir, "live-slot"),
64
106
  ctl: posix.join(deployDir, "ctl"),
107
+ unitDir,
108
+ unitTemplate: posix.join(unitDir, `sixb-${input.name}@.service`),
109
+ caddyDir,
110
+ caddySnippet: posix.join(caddyDir, `${input.name}.caddy`),
111
+ } satisfies DeploymentLayout
112
+ }
113
+
114
+ export function slotLayout(layout: DeploymentLayout, slot: DeploySlot): SlotLayout {
115
+ const runDir = posix.join(layout.root, "run", slot)
116
+ return {
117
+ slot,
118
+ unit: `sixb-${layout.name}@${slot}.service`,
119
+ manifest: posix.join(layout.deployDir, `${slot}.json`),
120
+ launcher: posix.join(layout.deployDir, slot),
65
121
  runDir,
66
122
  logDir: posix.join(runDir, "logs"),
123
+ }
124
+ }
125
+
126
+ export function legacyLayout(layout: DeploymentLayout): LegacyLayout {
127
+ const unit = `sixb-${layout.name}.service`
128
+ return {
129
+ unit,
130
+ unitPath: posix.join(layout.unitDir, unit),
131
+ manifest: posix.join(layout.deployDir, "processes.json"),
132
+ }
133
+ }
134
+
135
+ export interface ReleaseLayout {
136
+ readonly id: string
137
+ readonly root: string
138
+ /** The project inside the release: its root, or a folder of a monorepo. */
139
+ readonly project: string
140
+ readonly bunDir: string
141
+ readonly bun: string
142
+ }
143
+
144
+ export function releaseLayout(
145
+ layout: DeploymentLayout,
146
+ input: { readonly id: string; readonly projectPath: string; readonly bunVersion: string }
147
+ ): ReleaseLayout {
148
+ const root = posix.join(layout.releasesDir, input.id)
149
+ const bunDir = posix.join(layout.home, ".sixb", "bun", input.bunVersion)
150
+ return {
151
+ id: input.id,
152
+ root,
153
+ project: posix.join(root, input.projectPath),
67
154
  bunDir,
68
155
  bun: posix.join(bunDir, "bun"),
69
- unitName,
70
- unit: posix.join(input.home, ".config", "systemd", "user", unitName),
71
- caddyDir,
72
- caddySnippet: posix.join(caddyDir, `${input.name}.caddy`),
73
156
  }
74
157
  }
package/src/operations.ts CHANGED
@@ -1,3 +1,4 @@
1
+ /// <reference path="./sh.d.ts" />
1
2
  import { randomUUID } from "node:crypto"
2
3
  import type {
3
4
  DeployContext,
@@ -8,93 +9,135 @@ import type {
8
9
  DeploySource,
9
10
  DeployStatus,
10
11
  } from "@sixb/core/deploy"
11
- import { deploymentLayout } from "./layout"
12
- import {
13
- renderDeployScript,
14
- renderPrepareScript,
15
- renderReceiveScript,
16
- STEP_MARKER,
17
- } from "./scripts"
12
+ import bootstrap from "./bootstrap.sh" with { type: "text" }
13
+ import { deriveReleaseId, parseEvent, type ReleasePlan, releaseStepLabels } from "./plan"
18
14
  import { stripTerminalControl } from "./server/logs"
19
15
  import { shellQuote } from "./shell"
20
16
  import { RemoteScriptError, type RemoteShell } from "./transport"
21
17
 
22
18
  const NOT_DEPLOYED = "__SIXB_NOT_DEPLOYED__"
23
19
 
24
- /** Uploads the source, then runs the release on the server as one locked script. */
20
+ /**
21
+ * Uploads the source and the plan, starts the release on the server detached from this
22
+ * connection, and follows its log until it ends. A dropped connection leaves the deploy running.
23
+ */
25
24
  export async function deployRelease(
26
25
  shell: RemoteShell,
27
- user: string,
28
26
  release: DeployRelease,
29
27
  source: DeploySource,
30
28
  context: DeployContext
31
29
  ): Promise<void> {
32
- const prepared = await capture(shell, renderPrepareScript(release.name, source.commit))
33
- const [home, incoming] = prepared
34
- if (!home || !incoming) {
35
- throw new Error("[SshTarget] The server did not report its home directory.")
30
+ const record = {
31
+ commit: source.commit,
32
+ ref: source.ref,
33
+ deployedAt: new Date().toISOString(),
34
+ deployedBy: context.deployedBy,
36
35
  }
36
+ const releaseId = deriveReleaseId(record)
37
+ const [home, incoming] = await capture(
38
+ shell,
39
+ [
40
+ `root="$HOME"/${shellQuote(release.name)}`,
41
+ 'mkdir -p "$root/deploy/incoming" "$root/deploy/runs"',
42
+ // Run logs hold all the build and migration output: for the deploy account alone.
43
+ 'chmod 700 "$root/deploy/runs"',
44
+ `incoming="$(mktemp -d "$root/deploy/incoming/${releaseId}.XXXXXX")"`,
45
+ // `mktemp` makes it 0700, and tar passes the mode of the upload's `.` on to the release.
46
+ 'chmod 755 "$incoming"',
47
+ `printf '%s\n%s\n' "$HOME" "$incoming"`,
48
+ ].join("\n")
49
+ )
50
+ if (!home || !incoming)
51
+ throw new Error("[SshTarget] The server did not report its home directory.")
37
52
 
38
- const layout = deploymentLayout({
39
- home,
40
- user,
41
- name: release.name,
42
- projectPath: source.projectPath,
43
- bunVersion: release.bunVersion,
44
- })
45
- const { labels, script } = renderDeployScript({
46
- release,
47
- layout,
48
- incoming,
49
- record: {
50
- commit: source.commit,
51
- ref: source.ref,
52
- deployedAt: new Date().toISOString(),
53
- deployedBy: context.deployedBy,
54
- },
55
- })
56
- context.report({ type: "steps", labels: ["Upload source", ...labels] })
57
-
53
+ const labels = releaseStepLabels(release)
54
+ context.report({ type: "steps", labels })
58
55
  context.report({ type: "step", index: 0, status: "running" })
59
56
  for (const archive of source.archives) {
60
- await shell.run(renderReceiveScript(incoming, archive.path), { stdin: archive.open() })
57
+ const directory = archive.path === "." ? incoming : `${incoming}/${archive.path}`
58
+ await shell.run(
59
+ `mkdir -p ${shellQuote(directory)} && tar -x -f - -C ${shellQuote(directory)}`,
60
+ { stdin: archive.open() }
61
+ )
62
+ }
63
+ const runs = `${home}/${release.name}/deploy/runs`
64
+ const plan: ReleasePlan = {
65
+ version: 1,
66
+ release,
67
+ record,
68
+ releaseId,
69
+ projectPath: source.projectPath,
61
70
  }
71
+ const files = { plan: `${runs}/${releaseId}.json`, script: `${runs}/${releaseId}.sh` }
72
+ await upload(shell, files.plan, JSON.stringify(plan))
73
+ await upload(shell, files.script, bootstrap)
62
74
  context.report({ type: "step", index: 0, status: "done" })
63
75
 
64
- await runReportingSteps(shell, script, context)
76
+ const log = `${runs}/${releaseId}.log`
77
+ const args = [
78
+ release.name,
79
+ releaseId,
80
+ source.projectPath,
81
+ release.bunVersion,
82
+ incoming,
83
+ files.plan,
84
+ ]
85
+ const [pid] = await capture(
86
+ shell,
87
+ `setsid nohup bash ${[files.script, ...args].map(shellQuote).join(" ")} > ${shellQuote(log)} 2>&1 < /dev/null & echo $!`
88
+ )
89
+ await follow(shell, { pid: pid ?? "", log, labels, context })
65
90
  }
66
91
 
67
- /** Runs the deploy script, turning its step markers into progress and the rest into output. */
68
- async function runReportingSteps(
92
+ /** Reads the release's log as it grows, until the release ends, and reports its progress. */
93
+ async function follow(
69
94
  shell: RemoteShell,
70
- script: string,
71
- context: DeployContext
95
+ input: {
96
+ readonly pid: string
97
+ readonly log: string
98
+ readonly labels: readonly string[]
99
+ readonly context: DeployContext
100
+ }
72
101
  ): Promise<void> {
73
- const run = shell.run(script, {
74
- onLine: (line) => {
75
- const [marker, index, status] = line.split("\t")
76
- if (marker === STEP_MARKER && (status === "start" || status === "done")) {
77
- const step = Number(index) + 1
78
- context.report({
79
- type: "step",
80
- index: step,
81
- status: status === "start" ? "running" : "done",
82
- })
83
- } else {
84
- const output = stripTerminalControl(line)
85
- if (output.trim()) context.report({ type: "output", line: output })
86
- }
87
- },
88
- })
102
+ const { context, labels } = input
103
+ let exit: number | null = null
104
+ let failure: string | null = null
89
105
  try {
90
- await run
106
+ await shell.run(
107
+ `tail -n +1 -F --pid=${shellQuote(input.pid)} ${shellQuote(input.log)} 2> /dev/null`,
108
+ {
109
+ onLine: (line, stream) => {
110
+ if (stream !== "stdout") return
111
+ const event = parseEvent(line)
112
+ if (event && "exit" in event) {
113
+ exit = event.exit
114
+ } else if (event) {
115
+ const index = labels.indexOf(event.step)
116
+ if (index === -1) context.report({ type: "output", line: event.step })
117
+ else context.report({ type: "step", index, status: event.status })
118
+ } else {
119
+ const output = stripTerminalControl(line)
120
+ if (output.startsWith("[SshTarget] ")) failure = output
121
+ if (output.trim()) context.report({ type: "output", line: output })
122
+ }
123
+ },
124
+ }
125
+ )
91
126
  } catch (error) {
92
- // The step's output already reached `report`; repeating it here would print it twice.
93
- if (error instanceof RemoteScriptError && error.exitCode !== 255) {
94
- throw new Error(`[SshTarget] The step exited with code ${error.exitCode}.`)
95
- }
96
- throw error
127
+ throw new Error(
128
+ `[SshTarget] Lost the connection while following the deploy, which carries on on the server. \`sixb deploy status\` shows the release once it ends; its log is ${input.log}.`,
129
+ { cause: error }
130
+ )
97
131
  }
132
+ if (exit === 0) return
133
+ // The step's output already reached `report`; the error repeats only its conclusion.
134
+ throw new Error(failure ?? `[SshTarget] The deploy ended with code ${exit ?? "unknown"}.`)
135
+ }
136
+
137
+ async function upload(shell: RemoteShell, path: string, content: string): Promise<void> {
138
+ await shell.run(`umask 077 && cat > ${shellQuote(path)}`, {
139
+ stdin: new Blob([content]).stream(),
140
+ })
98
141
  }
99
142
 
100
143
  export async function readStatus(shell: RemoteShell, name: string): Promise<DeployStatus> {
package/src/plan.ts ADDED
@@ -0,0 +1,59 @@
1
+ import type { DeployCommand, DeployRecord, DeployRelease } from "@sixb/core/deploy"
2
+
3
+ /** What the laptop sends the server's runner: the release, and how it was asked for. */
4
+ export interface ReleasePlan {
5
+ readonly version: 1
6
+ readonly release: DeployRelease
7
+ readonly record: DeployRecord
8
+ readonly releaseId: string
9
+ readonly projectPath: string
10
+ }
11
+
12
+ /** Starts every progress line, so the laptop tells events from a command's output (RFC 7464). */
13
+ export const EVENT_PREFIX = "\u001e"
14
+
15
+ export type ReleaseEvent =
16
+ | { readonly step: string; readonly status: "running" | "done" }
17
+ | { readonly exit: number }
18
+
19
+ export function event(value: ReleaseEvent): string {
20
+ return `${EVENT_PREFIX}${JSON.stringify(value)}`
21
+ }
22
+
23
+ export function parseEvent(line: string): ReleaseEvent | null {
24
+ if (!line.startsWith(EVENT_PREFIX)) return null
25
+ try {
26
+ return JSON.parse(line.slice(EVENT_PREFIX.length)) as ReleaseEvent
27
+ } catch {
28
+ return null
29
+ }
30
+ }
31
+
32
+ /** The steps a deploy runs, in order: the upload, then what the server does. */
33
+ export function releaseStepLabels(release: DeployRelease): string[] {
34
+ return [
35
+ "Upload source",
36
+ "Prepare release",
37
+ `Install Bun ${release.bunVersion}`,
38
+ "Install dependencies",
39
+ ...(release.steps.env ? [commandLabel(release.steps.env)] : []),
40
+ ...release.steps.build.map(commandLabel),
41
+ ...release.steps.beforeStart.map(commandLabel),
42
+ "Start new release",
43
+ "Check services",
44
+ "Update routes",
45
+ "Move singletons",
46
+ "Retire previous release",
47
+ ]
48
+ }
49
+
50
+ export function commandLabel(command: DeployCommand): string {
51
+ return [command.program, ...command.args].join(" ")
52
+ }
53
+
54
+ /** A release folder's name: when, to the millisecond, then which commit. */
55
+ export function deriveReleaseId(record: DeployRecord): string {
56
+ const stamp = record.deployedAt.replace(/[-:.]/g, "").slice(0, 18)
57
+ const sha = record.commit.slice(0, 12).replace(/[^a-zA-Z0-9_-]/g, "")
58
+ return `${stamp}Z-${sha || "release"}`
59
+ }