easy-devops 1.3.6 → 1.4.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 (69) hide show
  1. package/README.md +1 -0
  2. package/dist/ui/assets/index-Bu7af-Kj.css +1 -0
  3. package/dist/ui/assets/index-gndgYe3K.js +532 -0
  4. package/dist/ui/assets/socket-Bv0wCEgi.js +65 -0
  5. package/dist/ui/index.html +2 -2
  6. package/package.json +2 -2
  7. package/src/cli/index.js +8 -0
  8. package/src/cli/managers/domain-manager.js +37 -6
  9. package/src/cli/managers/nginx-manager.js +14 -5
  10. package/src/cli/managers/node-manager.js +19 -13
  11. package/src/cli/managers/ssl-manager.js +89 -26
  12. package/src/cli/menu.js +8 -2
  13. package/src/cli/menus/cleanup.js +4 -2
  14. package/src/cli/menus/dashboard.js +22 -15
  15. package/src/cli/menus/hub.js +381 -0
  16. package/src/cli/menus/runtime.js +12 -0
  17. package/src/cli/menus/service.js +28 -10
  18. package/src/cli/menus/settings.js +46 -12
  19. package/src/cli/menus/uninstall.js +13 -5
  20. package/src/cli/menus/update.js +24 -14
  21. package/src/cli/ui/page.js +123 -0
  22. package/src/core/cert-operations.js +34 -4
  23. package/src/core/cert-reader.js +67 -22
  24. package/src/core/cert-renewal.js +65 -9
  25. package/src/core/cert-suggest.js +120 -0
  26. package/src/core/cleanup.js +221 -1
  27. package/src/core/cloudflare-ips.js +161 -0
  28. package/src/core/daemon/ipc.js +1 -1
  29. package/src/core/daemon/lock.js +296 -9
  30. package/src/core/dashboardProcess.js +134 -6
  31. package/src/core/deploy/apps.js +36 -62
  32. package/src/core/deploy/deployKey.js +331 -0
  33. package/src/core/deploy/domainLink.js +280 -23
  34. package/src/core/deploy/engine.js +382 -63
  35. package/src/core/deploy/ezfile.js +496 -29
  36. package/src/core/deploy/githubApi.js +100 -13
  37. package/src/core/deploy/hubCommands.js +158 -18
  38. package/src/core/deploy/status.js +28 -1
  39. package/src/core/domains-db.js +1 -0
  40. package/src/core/hub/agent.js +238 -32
  41. package/src/core/hub/deployProgress.js +411 -0
  42. package/src/core/hubConnect.js +205 -0
  43. package/src/core/hubPermissions.js +48 -10
  44. package/src/core/jobs/bus.js +1 -1
  45. package/src/core/jobs/owner.js +268 -6
  46. package/src/core/nginx-conf-generator.js +124 -19
  47. package/src/core/notifications/claim.js +26 -3
  48. package/src/core/permissions.js +277 -59
  49. package/src/core/platform.js +48 -2
  50. package/src/core/runner.js +96 -40
  51. package/src/core/ssl/preflight.js +548 -0
  52. package/src/core/ssl/progress.js +196 -0
  53. package/src/core/ssl-issuer.js +502 -148
  54. package/src/core/validators.js +24 -0
  55. package/src/dashboard/controllers/authController.js +12 -5
  56. package/src/dashboard/controllers/deploymentsController.js +76 -11
  57. package/src/dashboard/controllers/domainsController.js +35 -1
  58. package/src/dashboard/controllers/hubController.js +4 -3
  59. package/src/dashboard/controllers/settingsController.js +73 -68
  60. package/src/dashboard/controllers/sslController.js +135 -15
  61. package/src/dashboard/public/js/app.js +42 -7
  62. package/src/dashboard/routes/deployments.js +2 -0
  63. package/src/dashboard/routes/domains.js +1 -0
  64. package/src/dashboard/server.js +42 -7
  65. package/src/dashboard/socketManager.js +19 -25
  66. package/src/dashboard/views/partials/settings-panel.ejs +29 -10
  67. package/dist/ui/assets/index-BUpPxWmp.css +0 -1
  68. package/dist/ui/assets/index-DD0JjK0Q.js +0 -475
  69. package/dist/ui/assets/socket-4tfdap-e.js +0 -65
@@ -314,8 +314,19 @@ function fromMap(map, action) {
314
314
  : undefined;
315
315
  }
316
316
 
317
+ /** The SSL mode a deploy/link payload asks for, including the legacy boolean. */
318
+ function requestedSslMode(payload) {
319
+ const ssl = payload?.ssl;
320
+ if (ssl === true) return 'issue';
321
+ if (ssl && typeof ssl === 'object' && !Array.isArray(ssl)) return ssl.mode ?? 'none';
322
+ return 'none';
323
+ }
324
+
317
325
  /**
318
- * Resolves the permission a hub command payload requires.
326
+ * Resolves the permission(s) a hub command payload requires.
327
+ *
328
+ * Usually one id. `hub:manageDeploy { action: 'linkDomain' }` needs a list:
329
+ * every id in it must be granted, and a refusal names the first missing one.
319
330
  *
320
331
  * Returns null when the command needs no permission (read-only telemetry).
321
332
  * Returns undefined for an unknown command, so the agent can refuse it rather
@@ -323,7 +334,7 @@ function fromMap(map, action) {
323
334
  *
324
335
  * @param {string} command
325
336
  * @param {Object} [payload]
326
- * @returns {string|null|undefined}
337
+ * @returns {string|string[]|null|undefined}
327
338
  */
328
339
  export function permissionForCommand(command, payload = {}) {
329
340
  switch (command) {
@@ -357,6 +368,9 @@ export function permissionForCommand(command, payload = {}) {
357
368
  renew: 'ssl.renew',
358
369
  renewAll: 'ssl.renewAll',
359
370
  issue: 'ssl.issue',
371
+ // Read-only lookup: it changes nothing, and a paired server is a
372
+ // monitored server.
373
+ suggest: null,
360
374
  delete: 'ssl.delete',
361
375
  };
362
376
  return fromMap(map, payload?.action);
@@ -374,6 +388,17 @@ export function permissionForCommand(command, payload = {}) {
374
388
  }
375
389
 
376
390
  case 'hub:manageDeploy': {
391
+ const action = payload?.action;
392
+
393
+ // Linking writes a domain config, so managing an app is not enough:
394
+ // domains.create is required too, and issuing a certificate is its own
395
+ // permission. All of them must be granted.
396
+ if (action === 'linkDomain') {
397
+ const needed = ['deploy.manage', 'domains.create'];
398
+ if (requestedSslMode(payload) === 'issue') needed.push('ssl.issue');
399
+ return needed;
400
+ }
401
+
377
402
  const map = {
378
403
  // Listing the apps and their status is monitoring, like the process
379
404
  // list: a paired server is a monitored server. No secrets are in it.
@@ -388,13 +413,14 @@ export function permissionForCommand(command, payload = {}) {
388
413
  delete: 'deploy.manage',
389
414
  deleteRelease: 'deploy.manage',
390
415
  issueToken: 'deploy.manage',
391
- linkDomain: 'deploy.manage',
416
+ regenerateKey: 'deploy.manage',
417
+ testKey: 'deploy.manage',
418
+ addKeyToGithub: 'deploy.manage',
392
419
  unlinkDomain: 'deploy.manage',
393
420
  move: 'deploy.manage',
394
421
  getEnv: 'deploy.env',
395
422
  setEnv: 'deploy.env',
396
423
  };
397
- const action = payload?.action;
398
424
  return fromMap(map, action);
399
425
  }
400
426
 
@@ -422,7 +448,7 @@ export function permissionForCommand(command, payload = {}) {
422
448
  * @param {string} command
423
449
  * @param {Object} payload
424
450
  * @param {Object<string, boolean>} permissions
425
- * @returns {{ allowed: boolean, permission: string|null, reason: string|null }}
451
+ * @returns {{ allowed: boolean, permission: string|string[]|null, reason: string|null }}
426
452
  */
427
453
  export function checkCommandAllowed(command, payload, permissions) {
428
454
  const required = permissionForCommand(command, payload);
@@ -433,14 +459,26 @@ export function checkCommandAllowed(command, payload, permissions) {
433
459
  if (required === null) {
434
460
  return { allowed: true, permission: null, reason: null };
435
461
  }
436
- if (isComingSoon(required)) {
437
- return { allowed: false, permission: required, reason: `'${required}' is not available yet.` };
462
+
463
+ const needed = Array.isArray(required) ? required : [required];
464
+ const grantedMap = normalizePermissions(permissions);
465
+
466
+ for (const permission of needed) {
467
+ if (isComingSoon(permission)) {
468
+ return { allowed: false, permission, reason: `'${permission}' is not available yet.` };
469
+ }
470
+ if (grantedMap[permission] !== true) {
471
+ return {
472
+ allowed: false,
473
+ permission,
474
+ reason: `Permission '${permission}' is disabled on this server.`,
475
+ };
476
+ }
438
477
  }
439
478
 
440
- const granted = normalizePermissions(permissions)[required] === true;
441
479
  return {
442
- allowed: granted,
480
+ allowed: true,
443
481
  permission: required,
444
- reason: granted ? null : `Permission '${required}' is disabled on this server.`,
482
+ reason: null,
445
483
  };
446
484
  }
@@ -16,7 +16,7 @@
16
16
  * ── Why the event names are the browser's names ────────────────────────────
17
17
  *
18
18
  * `nginx:status`, `domain:health`, `notification:new` and `local:changed` are
19
- * the names in docs/api-contract.md, and they are used unchanged here. A
19
+ * the names in API-CONTRACT.md, and they are used unchanged here. A
20
20
  * translation table between internal and external names would be one more
21
21
  * thing to keep in step with the contract, and the contract is the thing that
22
22
  * must not drift. So a forwarder is a one-liner: subscribe, emit the same name
@@ -59,18 +59,34 @@ export const HANDOVER_WAIT_MS = 8_000;
59
59
 
60
60
  const OWNER_FILE = 'jobs.owner';
61
61
 
62
+ /**
63
+ * How long a recovery guard left by a crashed process must sit before another
64
+ * process may clear it. Long enough that a slow but live recovery is never
65
+ * cleared out from under itself.
66
+ */
67
+ const RECOVERY_GUARD_STALE_MS = 30_000;
68
+
69
+ /**
70
+ * How long an empty, unreadable marker may exist before another process may
71
+ * treat it as abandoned: creating it is `writeFileSync(path, data, { flag:
72
+ * 'wx' })`, which creates the file and THEN writes it, so a brand-new marker is
73
+ * briefly empty. A reader in that window must not "recover" it.
74
+ */
75
+ const UNREADABLE_GRACE_MS = 2_000;
76
+
62
77
  /** @returns {string} Absolute path to the ownership marker. */
63
78
  export function ownerPath(dataDir = getDataDir()) {
64
79
  return path.join(dataDir, OWNER_FILE);
65
80
  }
66
81
 
67
82
  /**
68
- * Reads the marker without judging it.
83
+ * Reads a marker file without judging it.
84
+ * @param {string} file Absolute path to the marker
69
85
  * @returns {{ pid: number, role: string|null, at: number, heartbeatAt: number }|null}
70
86
  */
71
- export function readOwner(dataDir = getDataDir()) {
87
+ function readOwnerAt(file) {
72
88
  try {
73
- const parsed = JSON.parse(fs.readFileSync(ownerPath(dataDir), 'utf8'));
89
+ const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
74
90
  if (!Number.isInteger(parsed?.pid)) return null;
75
91
  return {
76
92
  pid: parsed.pid,
@@ -84,6 +100,29 @@ export function readOwner(dataDir = getDataDir()) {
84
100
  }
85
101
  }
86
102
 
103
+ /**
104
+ * True when an unreadable marker is a create that has not been written yet: an
105
+ * empty file younger than the grace counts as LIVE, an empty file older than it
106
+ * is a crash and may be recovered, and a non-empty file that does not parse is
107
+ * a truncated write with no live owner.
108
+ */
109
+ function isWriteInFlight(file, now) {
110
+ try {
111
+ const stat = fs.statSync(file);
112
+ return stat.size === 0 && now - stat.mtimeMs < UNREADABLE_GRACE_MS;
113
+ } catch {
114
+ return false;
115
+ }
116
+ }
117
+
118
+ /**
119
+ * Reads the marker in a data directory without judging it.
120
+ * @returns {{ pid: number, role: string|null, at: number, heartbeatAt: number }|null}
121
+ */
122
+ export function readOwner(dataDir = getDataDir()) {
123
+ return readOwnerAt(ownerPath(dataDir));
124
+ }
125
+
87
126
  /**
88
127
  * Who holds the jobs, as far as anyone else can tell.
89
128
  *
@@ -123,6 +162,21 @@ export function inspect({ dataDir = getDataDir(), now = Date.now() } = {}) {
123
162
  /**
124
163
  * Takes ownership of the jobs.
125
164
  *
165
+ * The marker is CREATED exclusively (`wx`), exactly as the daemon lock is: two
166
+ * processes racing for the jobs cannot both win, because only one open can
167
+ * create the file.
168
+ *
169
+ * Recovering a marker whose owner is gone is the subtle half, for the same
170
+ * reason as the daemon lock: deciding from `inspect()` before the race lets two
171
+ * processes both "recover" the same dead marker, and moving the file aside
172
+ * leaves the path empty long enough for a third process to create there.
173
+ *
174
+ * So recovery is serialised and the marker is only REPLACED, never removed:
175
+ * one process creates `jobs.owner.recovery` exclusively (the permission to
176
+ * recover), re-reads the marker under that guard, and replaces a dead one with
177
+ * an atomic rename of a prepared candidate. The path is never empty. Everyone
178
+ * else is refused, and the guard is removed in a `finally`.
179
+ *
126
180
  * @param {Object} opts
127
181
  * @param {string} [opts.dataDir]
128
182
  * @param {string} opts.role 'daemon' | 'dashboard'
@@ -135,8 +189,196 @@ export function claim({ dataDir = getDataDir(), role = 'unknown', now = Date.now
135
189
  return { ok: false, reason: state.reason, owner: state.owner };
136
190
  }
137
191
 
138
- write({ dataDir, role, now, at: state.mine ? state.owner.at : now });
139
- return { ok: true, recovered: state.stale };
192
+ // Refreshing our own marker is not an acquisition: keep the original `at`,
193
+ // and use the atomic rewrite that only the owner performs.
194
+ if (state.mine) {
195
+ write({ dataDir, role, now, at: state.owner.at });
196
+ return { ok: true, recovered: false };
197
+ }
198
+
199
+ const payload = { pid: process.pid, role, at: now, heartbeatAt: now };
200
+
201
+ const first = createExclusive(dataDir, payload);
202
+ if (first.ok) return { ok: true, recovered: state.stale };
203
+
204
+ if (first.code !== 'EEXIST') {
205
+ return { ok: false, reason: `could not create the jobs marker: ${first.message}`, owner: null };
206
+ }
207
+
208
+ // A marker appeared after inspect() saw none. If it is readable it is
209
+ // somebody's; an unreadable one (truncated by a crash) has no owner, so it
210
+ // falls through to the guard below, which replaces it.
211
+ if (!state.owner && !fs.existsSync(ownerPath(dataDir))) {
212
+ return { ok: false, reason: 'another process claimed the jobs first', owner: readOwner(dataDir) };
213
+ }
214
+
215
+ // Empty and just created: a `wx` create whose write has not landed yet.
216
+ if (!state.owner && isWriteInFlight(ownerPath(dataDir), now)) {
217
+ return { ok: false, reason: 'another process is writing its claim', owner: readOwner(dataDir) };
218
+ }
219
+
220
+ const guard = acquireRecoveryGuard({ dataDir, now });
221
+ if (!guard.ok) {
222
+ return { ok: false, reason: guard.reason, owner: readOwner(dataDir) };
223
+ }
224
+
225
+ try {
226
+ // Authoritative: nobody else may change the marker while we hold the guard.
227
+ const current = inspect({ dataDir, now });
228
+
229
+ if (current.held && !current.mine) {
230
+ return { ok: false, reason: current.reason, owner: current.owner };
231
+ }
232
+
233
+ if (current.mine) {
234
+ write({ dataDir, role, now, at: current.owner.at });
235
+ return { ok: true, recovered: false };
236
+ }
237
+
238
+ if (!current.owner) {
239
+ // Empty and just created is a create in flight — treat it as live.
240
+ if (isWriteInFlight(ownerPath(dataDir), now)) {
241
+ return { ok: false, reason: 'another process is writing its claim', owner: null };
242
+ }
243
+
244
+ // Unreadable or gone: a marker with no readable owner cannot be waited on
245
+ // (a crash mid-write would otherwise block the jobs for ever), so it is
246
+ // created over if it is gone, replaced under the guard if it is still
247
+ // there.
248
+ const again = createExclusive(dataDir, payload);
249
+ if (again.ok) return { ok: true, recovered: true };
250
+
251
+ if (again.code !== 'EEXIST') {
252
+ return { ok: false, reason: `could not create the jobs marker: ${again.message}`, owner: null };
253
+ }
254
+
255
+ const replaced = replaceOwner({ dataDir, payload });
256
+ return replaced.ok
257
+ ? { ok: true, recovered: true }
258
+ : { ok: false, reason: `could not replace the unreadable jobs marker: ${replaced.message}`, owner: null };
259
+ }
260
+
261
+ const replaced = replaceOwner({ dataDir, payload });
262
+ if (!replaced.ok) {
263
+ return {
264
+ ok: false,
265
+ reason: `could not replace the jobs marker: ${replaced.message}`,
266
+ owner: readOwner(dataDir),
267
+ };
268
+ }
269
+
270
+ return { ok: true, recovered: true };
271
+ } finally {
272
+ guard.release();
273
+ }
274
+ }
275
+
276
+ /**
277
+ * Creates the recovery guard exclusively, or explains why recovery may not run.
278
+ *
279
+ * @param {Object} opts
280
+ * @param {string} opts.dataDir
281
+ * @param {number} opts.now
282
+ * @returns {{ ok: true, release: () => void } | { ok: false, reason: string }}
283
+ */
284
+ function acquireRecoveryGuard({ dataDir, now }) {
285
+ const file = `${ownerPath(dataDir)}.recovery`;
286
+ const payload = { pid: process.pid, at: now };
287
+
288
+ const attempt = () => {
289
+ try {
290
+ fs.writeFileSync(file, `${JSON.stringify(payload)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
291
+ return { ok: true };
292
+ } catch (err) {
293
+ return { ok: false, code: err?.code ?? 'UNKNOWN', message: err?.message ?? String(err) };
294
+ }
295
+ };
296
+
297
+ const release = () => {
298
+ try { fs.unlinkSync(file); } catch { /* already gone */ }
299
+ };
300
+
301
+ const first = attempt();
302
+ if (first.ok) return { ok: true, release };
303
+ if (first.code !== 'EEXIST') {
304
+ return { ok: false, reason: `could not create the recovery guard: ${first.message}` };
305
+ }
306
+
307
+ // A guard left behind by a process that died mid-recovery: clear it only when
308
+ // its owner is provably gone and it is old enough not to be a slow recovery.
309
+ let existing = null;
310
+ try {
311
+ existing = JSON.parse(fs.readFileSync(file, 'utf8'));
312
+ } catch { /* unreadable: treat it as live */ }
313
+
314
+ const abandoned = Boolean(existing)
315
+ && Number.isInteger(existing.pid)
316
+ && !isPidAlive(existing.pid)
317
+ && now - (Number(existing.at) || 0) > RECOVERY_GUARD_STALE_MS;
318
+
319
+ if (!abandoned) return { ok: false, reason: 'another process is recovering the jobs marker' };
320
+
321
+ try { fs.unlinkSync(file); } catch { /* another process cleared it first */ }
322
+
323
+ const second = attempt();
324
+ return second.ok
325
+ ? { ok: true, release }
326
+ : { ok: false, reason: 'another process is recovering the jobs marker' };
327
+ }
328
+
329
+ /**
330
+ * Replaces the marker with this process's payload, atomically.
331
+ *
332
+ * A `rename` within the directory replaces the old file with the new one in one
333
+ * step, so the path is never absent and no third process can create there.
334
+ * Called only while the recovery guard is held.
335
+ *
336
+ * @param {Object} opts
337
+ * @param {string} opts.dataDir
338
+ * @param {Object} opts.payload
339
+ * @returns {{ ok: true } | { ok: false, message: string }}
340
+ */
341
+ function replaceOwner({ dataDir, payload }) {
342
+ const target = ownerPath(dataDir);
343
+ const candidate = `${target}.candidate-${process.pid}-${Math.random().toString(36).slice(2, 10)}`;
344
+ const body = `${JSON.stringify(payload)}\n`;
345
+
346
+ try {
347
+ fs.writeFileSync(candidate, body, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
348
+ } catch (err) {
349
+ return { ok: false, message: err?.message ?? String(err) };
350
+ }
351
+
352
+ const moved = renameWithRetry(candidate, target);
353
+ if (!moved.ok) {
354
+ try { fs.unlinkSync(candidate); } catch { /* already gone */ }
355
+ return { ok: false, message: moved.message };
356
+ }
357
+
358
+ return { ok: true };
359
+ }
360
+
361
+ /**
362
+ * `rename`, retried briefly while Windows refuses it.
363
+ *
364
+ * A file another process has open for reading cannot be replaced on Windows
365
+ * (EPERM/EBUSY) until that handle closes. Readers here read and close
366
+ * immediately, so a bounded retry is enough — and bounded, so a stuck file can
367
+ * never hang an acquisition.
368
+ */
369
+ function renameWithRetry(from, to, attempts = 200, waitMs = 1) {
370
+ for (let i = 0; ; i++) {
371
+ try {
372
+ fs.renameSync(from, to);
373
+ return { ok: true };
374
+ } catch (err) {
375
+ const transient = err?.code === 'EPERM' || err?.code === 'EBUSY' || err?.code === 'EACCES';
376
+ if (!transient || i >= attempts) {
377
+ return { ok: false, message: err?.message ?? String(err) };
378
+ }
379
+ Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, waitMs);
380
+ }
381
+ }
140
382
  }
141
383
 
142
384
  /**
@@ -198,11 +440,31 @@ export async function waitUntilFree({
198
440
  }
199
441
  }
200
442
 
443
+ /**
444
+ * Creates the marker exclusively, or reports why it could not.
445
+ *
446
+ * @returns {{ ok: true } | { ok: false, code: string, message: string }}
447
+ */
448
+ function createExclusive(dataDir, payload) {
449
+ try {
450
+ fs.mkdirSync(dataDir, { recursive: true });
451
+ fs.writeFileSync(ownerPath(dataDir), `${JSON.stringify(payload)}\n`, {
452
+ encoding: 'utf8',
453
+ mode: 0o600,
454
+ flag: 'wx',
455
+ });
456
+ return { ok: true };
457
+ } catch (err) {
458
+ return { ok: false, code: err?.code ?? 'UNKNOWN', message: err?.message ?? String(err) };
459
+ }
460
+ }
461
+
201
462
  /**
202
463
  * Writes the marker atomically.
203
464
  *
204
465
  * Same temp-file-and-rename as the daemon lock: a reader must never see a
205
- * half-written marker and conclude nobody owns the jobs.
466
+ * half-written marker and conclude nobody owns the jobs. Only an owner
467
+ * refreshes it this way; taking it is createExclusive() above.
206
468
  */
207
469
  function write({ dataDir, role, now, at }) {
208
470
  const payload = { pid: process.pid, role, at: at ?? now, heartbeatAt: now };
@@ -11,6 +11,7 @@ import fs from 'fs/promises';
11
11
  import path from 'path';
12
12
  import { loadConfig } from './config.js';
13
13
  import { isWindows, toNginxPath, toEscapedNginxPath } from './platform.js';
14
+ import { CLOUDFLARE_RANGES } from './cloudflare-ips.js';
14
15
 
15
16
  /**
16
17
  * How certificate paths are written into a generated config.
@@ -57,6 +58,68 @@ export function buildChallengeLocation(port = DEFAULT_ACME_CHALLENGE_PORT) {
57
58
  /** Path prefix the deploy hook answers on. Shared with core/deploy/hookServer.js. */
58
59
  export const DEPLOY_HOOK_PATH = '/.ez-deploy/';
59
60
 
61
+ /**
62
+ * File holding the single `map $http_upgrade $ezz_connection_upgrade` definition.
63
+ *
64
+ * nginx permits a `map` only in the `http` context, and a second definition of
65
+ * the same variable fails `nginx -t`. Writing it to one file in conf.d means
66
+ * every domain config can use `$ezz_connection_upgrade` without any of them
67
+ * defining it, so the map exists exactly once no matter how many domains there
68
+ * are. The leading `00-` keeps it first in conf.d's lexical include order.
69
+ */
70
+ export const WEBSOCKET_MAP_FILENAME = '00-easy-devops-websocket.conf';
71
+
72
+ /** Prefix the Socket.IO endpoint is served under. */
73
+ export const SOCKET_IO_PATH = '/socket.io/';
74
+
75
+ /** Long enough for an idle WebSocket behind Socket.IO (1 hour). */
76
+ export const SOCKET_IO_TIMEOUT = '3600s';
77
+
78
+ /**
79
+ * Content of the shared WebSocket map file.
80
+ *
81
+ * `'' ''` (empty, not `close`) is deliberate: a plain HTTP request has no
82
+ * `Upgrade` header, so nginx sends no `Connection` header at all and upstream
83
+ * keep-alive keeps working. `close` would force every ordinary request onto a
84
+ * new connection. A real WebSocket request gets `upgrade` via `default`.
85
+ *
86
+ * @returns {string}
87
+ */
88
+ export function buildWebsocketMapConf() {
89
+ return [
90
+ '# Easy DevOps — WebSocket upgrade map. Written once for ALL proxied domains;',
91
+ '# a map may only live in the http context and must not be defined twice.',
92
+ 'map $http_upgrade $ezz_connection_upgrade {',
93
+ ' default upgrade;',
94
+ " '' '';",
95
+ '}',
96
+ '',
97
+ ].join('\n');
98
+ }
99
+
100
+ /**
101
+ * Path of the shared WebSocket map file for a given nginx installation.
102
+ * @param {string} nginxDir
103
+ * @returns {string}
104
+ */
105
+ export function websocketMapPath(nginxDir) {
106
+ const join = isWindows ? path.win32.join : path.posix.join;
107
+ return join(getConfDDir(nginxDir), WEBSOCKET_MAP_FILENAME);
108
+ }
109
+
110
+ /**
111
+ * Writes the shared WebSocket map file, overwriting it with identical content
112
+ * on later calls. One file, so it can never be included twice from our side.
113
+ * @param {string} nginxDir
114
+ * @returns {Promise<string>} Path written
115
+ */
116
+ export async function ensureWebsocketMap(nginxDir) {
117
+ const confPath = websocketMapPath(nginxDir);
118
+ await fs.mkdir(path.dirname(confPath), { recursive: true });
119
+ await fs.writeFile(confPath, buildWebsocketMapConf(), 'utf8');
120
+ return confPath;
121
+ }
122
+
60
123
  /**
61
124
  * Builds the location block that exposes the deploy hook through a domain.
62
125
  *
@@ -181,9 +244,12 @@ function formatCertPath(p, style) {
181
244
 
182
245
  /** Returns the conf.d directory for domain config files. */
183
246
  export function getConfDDir(nginxDir) {
247
+ // Explicit win32/posix instead of the host default: `isWindows` is the only
248
+ // decision, so the generated location cannot depend on which OS runs the
249
+ // code (and a simulated platform in tests gets the real separators).
184
250
  return isWindows
185
- ? path.join(nginxDir, 'conf', 'conf.d')
186
- : path.join(nginxDir, 'conf.d');
251
+ ? path.win32.join(nginxDir, 'conf', 'conf.d')
252
+ : path.posix.join(nginxDir, 'conf.d');
187
253
  }
188
254
 
189
255
  /** Returns the path to nginx.conf. */
@@ -242,6 +308,7 @@ export const DOMAIN_DEFAULTS = {
242
308
  www: false,
243
309
  wildcard: false, // *.example.com server_name; forces DNS-01
244
310
  enabled: true, // false = conf file renamed to .conf.disabled
311
+ behindCloudflare: false, // true = trust CF-Connecting-IP from Cloudflare ranges
245
312
  ssl: {
246
313
  enabled: false,
247
314
  certPath: '',
@@ -285,6 +352,7 @@ export function migrateDomain(d) {
285
352
  ...d,
286
353
  wildcard: d.wildcard ?? false,
287
354
  enabled: d.enabled ?? true,
355
+ behindCloudflare: d.behindCloudflare ?? false,
288
356
  ssl: { ...DOMAIN_DEFAULTS.ssl, ...d.ssl },
289
357
  performance: { ...DOMAIN_DEFAULTS.performance, ...d.performance },
290
358
  security: { ...DOMAIN_DEFAULTS.security, ...d.security },
@@ -314,6 +382,7 @@ export function migrateDomain(d) {
314
382
  advanced: { ...DOMAIN_DEFAULTS.advanced },
315
383
  wildcard: d.wildcard ?? false,
316
384
  enabled: d.enabled ?? true,
385
+ behindCloudflare: d.behindCloudflare ?? false,
317
386
  configFile: d.configFile ?? null,
318
387
  createdAt: d.createdAt ?? new Date().toISOString(),
319
388
  updatedAt: d.updatedAt ?? new Date().toISOString(),
@@ -359,21 +428,21 @@ export function buildConf(domain, nginxDir, sslDir, options = {}) {
359
428
  try { upstreamHostHeader = new URL(backendHost).host; } catch { /* keep $host */ }
360
429
  }
361
430
 
362
- // Build proxy headers (always include standard set)
363
- let proxyHeaders = `
431
+ // Build proxy headers (always include standard set).
432
+ //
433
+ // WebSocket-ready for EVERY proxied domain: `$ezz_connection_upgrade` is empty
434
+ // for a plain request (see buildWebsocketMapConf) and `upgrade` only when the
435
+ // client asked for an upgrade. The old `Connection "upgrade"` forced every
436
+ // ordinary request to claim an upgrade, which is wrong.
437
+ const proxyHeaders = `
438
+ proxy_http_version 1.1;
439
+ proxy_set_header Upgrade $http_upgrade;
440
+ proxy_set_header Connection $ezz_connection_upgrade;
364
441
  proxy_set_header Host ${upstreamHostHeader};
365
442
  proxy_set_header X-Real-IP $remote_addr;
366
443
  proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
367
444
  proxy_set_header X-Forwarded-Proto $scheme;`;
368
445
 
369
- // Add WebSocket headers if upstreamType is 'ws'
370
- if (upstreamType === 'ws') {
371
- proxyHeaders = `
372
- proxy_http_version 1.1;
373
- proxy_set_header Upgrade $http_upgrade;
374
- proxy_set_header Connection "upgrade";${proxyHeaders}`;
375
- }
376
-
377
446
  // Build rate limiting zone name (dots → underscores)
378
447
  const rateLimitZone = name.replace(/\./g, '_').replace(/\*/g, 'wildcard');
379
448
 
@@ -461,6 +530,21 @@ ${challengeLocation}
461
530
  mainBlock.push(` listen ${listenPort};`);
462
531
  mainBlock.push(` server_name ${serverNames};`);
463
532
 
533
+ // ─── Cloudflare real IP (per domain, opt-in) ────────────────────────────────
534
+ // set_real_ip_from only says whose X-Forwarded-For/CF-Connecting-IP to
535
+ // believe. It does NOT stop a direct connection to this origin: limit ports
536
+ // 80/443 to Cloudflare's ranges at the firewall for that. The app then trusts
537
+ // exactly one proxy — for the Hub that is TRUST_PROXY=1.
538
+ if (domain.behindCloudflare === true) {
539
+ mainBlock.push(``);
540
+ mainBlock.push(` # Behind Cloudflare: trust CF-Connecting-IP only from Cloudflare ranges.`);
541
+ mainBlock.push(` # The app trusts one proxy (Hub: TRUST_PROXY=1); firewall 80/443 to these ranges to block direct origin access.`);
542
+ for (const range of CLOUDFLARE_RANGES) {
543
+ mainBlock.push(` set_real_ip_from ${range};`);
544
+ }
545
+ mainBlock.push(` real_ip_header CF-Connecting-IP;`);
546
+ }
547
+
464
548
  // When this block is the port-80 listener (SSL off) it must answer the ACME
465
549
  // challenge too. `location ^~` outranks the `location /` proxy below.
466
550
  if (!ssl?.enabled) {
@@ -506,27 +590,44 @@ ${challengeLocation}
506
590
  mainBlock.push(buildDeployHookLocation(options.deployHookPort));
507
591
  }
508
592
 
509
- // ─── Location Block ─────────────────────────────────────────────────────────
510
- mainBlock.push(``);
511
- mainBlock.push(` location / {`);
593
+ // ─── Location Blocks ────────────────────────────────────────────────────────
512
594
  // proxy_pass: full external URL → use directly (no scheme/port added)
513
595
  // local backend → build from scheme + host + port
514
596
  const proxyTarget = backendIsUrl
515
597
  ? backendHost.replace(/\/$/, '')
516
598
  : `${proxyScheme}://${backendHost}:${port}`;
517
- mainBlock.push(` proxy_pass ${proxyTarget};`);
599
+
518
600
  // Add proxy_ssl_server_name for external HTTPS upstreams (SNI — required for Vercel, Railway, etc.)
519
601
  // Only when: HTTPS URL, not an IP address, not localhost, and nginx itself is not terminating SSL
520
602
  // (if nginx has its own cert the backend connection is separate — SNI directive is irrelevant)
603
+ let needsSni = false;
521
604
  if (backendIsUrl && /^https:/i.test(backendHost) && !ssl?.enabled) {
522
605
  let upstreamHostname = '';
523
606
  try { upstreamHostname = new URL(backendHost).hostname; } catch { /* skip */ }
524
607
  const isIp = /^\d{1,3}(\.\d{1,3}){3}$/.test(upstreamHostname) || upstreamHostname.startsWith('[');
525
608
  const isLocal = upstreamHostname === 'localhost' || upstreamHostname === '127.0.0.1';
526
- if (!isIp && !isLocal) {
527
- mainBlock.push(` proxy_ssl_server_name on;`);
528
- }
609
+ needsSni = !isIp && !isLocal;
529
610
  }
611
+
612
+ // Socket.IO / WebSocket path: no buffering and long idle timeouts. `^~` makes
613
+ // it win over `location /` (and regex locations) without stopping ordinary
614
+ // HTTP on the rest of the domain.
615
+ mainBlock.push(``);
616
+ mainBlock.push(` # Socket.IO / WebSockets — long-lived, unbuffered.`);
617
+ mainBlock.push(` location ^~ ${SOCKET_IO_PATH} {`);
618
+ mainBlock.push(` proxy_pass ${proxyTarget};`);
619
+ if (needsSni) mainBlock.push(` proxy_ssl_server_name on;`);
620
+ mainBlock.push(proxyHeaders);
621
+ mainBlock.push(``);
622
+ mainBlock.push(` proxy_buffering off;`);
623
+ mainBlock.push(` proxy_read_timeout ${SOCKET_IO_TIMEOUT};`);
624
+ mainBlock.push(` proxy_send_timeout ${SOCKET_IO_TIMEOUT};`);
625
+ mainBlock.push(` }`);
626
+
627
+ mainBlock.push(``);
628
+ mainBlock.push(` location / {`);
629
+ mainBlock.push(` proxy_pass ${proxyTarget};`);
630
+ if (needsSni) mainBlock.push(` proxy_ssl_server_name on;`);
530
631
  mainBlock.push(proxyHeaders);
531
632
  mainBlock.push(``);
532
633
  mainBlock.push(` proxy_read_timeout ${performance?.readTimeout || 60}s;`);
@@ -607,6 +708,10 @@ export async function generateConf(domain, options = {}) {
607
708
  await fs.mkdir(confDir, { recursive: true });
608
709
  await fs.writeFile(confPath, confContent, 'utf8');
609
710
 
711
+ // The single WebSocket map lives in its own conf.d file, so every domain can
712
+ // reference $ezz_connection_upgrade without defining the map itself.
713
+ await ensureWebsocketMap(nginxDir);
714
+
610
715
  // Ensure nginx.conf includes conf.d
611
716
  await ensureNginxInclude(nginxDir);
612
717