@bakers-build/addon-ports 0.6.1-next.5 → 0.6.1-next.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/README.md +1 -1
- package/dist/src/claims.d.ts +27 -12
- package/dist/src/claims.js +27 -43
- package/dist/src/config.d.ts +8 -0
- package/dist/src/config.js +31 -5
- package/dist/src/core.d.ts +3 -4
- package/dist/src/core.js +1 -1
- package/dist/src/deps-node.js +1 -1
- package/dist/src/discovery.d.ts +2 -1
- package/dist/src/discovery.js +7 -12
- package/dist/src/index.d.ts +1 -1
- package/dist/src/index.js +11 -10
- package/dist/src/service-config.js +9 -4
- package/dist/src/tools.js +5 -4
- package/dist/src/types.d.ts +121 -0
- package/dist/src/types.js +3 -3
- package/package.json +6 -6
package/README.md
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# @bakers-build/addon-ports
|
|
2
2
|
|
|
3
|
-
bakers.build ports command plugin: discover a ticket worktree's running services (
|
|
3
|
+
bakers.build ports command plugin: discover a ticket worktree's running services (claimer packages' containers, Storybook, ad-hoc listeners) and bring shareable tunnels up and down. The command half of BB-475; usable without the cockpit half.
|
|
4
4
|
|
|
5
5
|
Part of the bakers.build CLI. Install the meta package `@bakers-build/bakers` to get the `bakers` CLI with all addons. Source: https://github.com/bakers-build/bakers-build (bakers-cli/).
|
package/dist/src/claims.d.ts
CHANGED
|
@@ -1,7 +1,22 @@
|
|
|
1
|
-
import type { ClaimContext, ClaimedDiscovery, HttpProbe, RawDiscovery } from '@bakers-build/addon-ddev';
|
|
2
1
|
import { type HostDiscoveryDeps } from './discovery.js';
|
|
3
2
|
import { type ServiceRules } from './service-config.js';
|
|
4
|
-
|
|
3
|
+
import type { ClaimContext, ClaimedDiscovery, ClaimedService, HttpProbe, RawDiscovery, RawPort } from './types.js';
|
|
4
|
+
export type { ClaimContext, ClaimedDiscovery, ClaimedService, ClaimStatus, HttpProbe, TunnelRule, } from './types.js';
|
|
5
|
+
/** What a claimer's `discover` may call: a bounded command exec and a plain
|
|
6
|
+
* file read (`null` for a missing file). */
|
|
7
|
+
export type ClaimerDeps = Pick<HostDiscoveryDeps, 'run'> & ConfigFileDeps;
|
|
8
|
+
/** One claimer's own observations for a pass, plus the private `context` its
|
|
9
|
+
* `claim` reads back (merged into the `ClaimContext` it is handed). */
|
|
10
|
+
export interface ClaimerDiscovery<C extends object = object> extends RawDiscovery {
|
|
11
|
+
readonly context?: C;
|
|
12
|
+
}
|
|
13
|
+
/** The contract a claimer package exports as `claimer` (named in the ports
|
|
14
|
+
* entry's `with.claimers`). `claim` takes the raw indices it owns out of
|
|
15
|
+
* `remaining` and returns their services. */
|
|
16
|
+
export interface Claimer<C extends object = object> {
|
|
17
|
+
discover(worktree: string, deps: ClaimerDeps): Promise<ClaimerDiscovery<C>>;
|
|
18
|
+
claim(raw: readonly RawPort[], remaining: Set<number>, ctx: ClaimContext & Partial<C>): ClaimedService[];
|
|
19
|
+
}
|
|
5
20
|
/**
|
|
6
21
|
* `https://<lowercase-ticket>-<key>.<zone>` — pure, no I/O (spec: naming stays
|
|
7
22
|
* a pure exported function). Throws on an invalid ticket, key, zone or a
|
|
@@ -16,24 +31,24 @@ export declare function publicHostname(ticket: string, key: string, zone: string
|
|
|
16
31
|
export declare function inspectorPorts(cmdline: string): number[];
|
|
17
32
|
/** Run claimers in precedence order over one raw discovery pass, specific
|
|
18
33
|
* before broad: configured process entries (with the default `storybook`),
|
|
19
|
-
*
|
|
20
|
-
*
|
|
21
|
-
* `<key>-<port>`. */
|
|
22
|
-
export declare function claimServices(raw: RawDiscovery, ctx: ClaimContext, rules: ServiceRules): Promise<ClaimedDiscovery>;
|
|
23
|
-
/**
|
|
24
|
-
* `HostDiscoveryDeps` since it is
|
|
34
|
+
* the configured `claimers` in order, then the opt-in all-Node rule.
|
|
35
|
+
* A claimer's keys never change: a process claim on a key a claimer
|
|
36
|
+
* produced becomes `<key>-<port>`. */
|
|
37
|
+
export declare function claimServices(raw: RawDiscovery, ctx: ClaimContext, rules: ServiceRules, claimers?: readonly Claimer[]): Promise<ClaimedDiscovery>;
|
|
38
|
+
/** A plain file reader for claimers — kept distinct from
|
|
39
|
+
* `HostDiscoveryDeps` since it is file I/O, not a command exec. */
|
|
25
40
|
export interface ConfigFileDeps {
|
|
26
41
|
/** `null` for ENOENT; throwing is reserved for a real I/O failure. */
|
|
27
42
|
readFile(path: string): Promise<string | null>;
|
|
28
43
|
}
|
|
29
44
|
/** Compose raw lookup and claims — the `list`/`up` entry point.
|
|
30
|
-
* Host-listener discovery (process-rule candidates) stays local;
|
|
31
|
-
*
|
|
32
|
-
*
|
|
33
|
-
* directly here. */
|
|
45
|
+
* Host-listener discovery (process-rule candidates) stays local; every
|
|
46
|
+
* configured claimer discovers its own ports alongside it, and its
|
|
47
|
+
* `context` joins the `ClaimContext` all claimers are handed. */
|
|
34
48
|
export declare function discoverClaimedServices(worktree: string, deps: HostDiscoveryDeps & ConfigFileDeps, opts: {
|
|
35
49
|
readonly ticket: string;
|
|
36
50
|
readonly zone: string;
|
|
37
51
|
readonly probe: HttpProbe;
|
|
38
52
|
readonly rules: ServiceRules;
|
|
53
|
+
readonly claimers?: readonly Claimer[];
|
|
39
54
|
}): Promise<ClaimedDiscovery>;
|
package/dist/src/claims.js
CHANGED
|
@@ -2,21 +2,18 @@
|
|
|
2
2
|
// tunnel-ready services. A claimer consumes raw IDENTITIES (array indices
|
|
3
3
|
// into one `RawDiscovery` pass), never a global port number: two containers
|
|
4
4
|
// or two site rules can share a port, so "port already seen" would silently
|
|
5
|
-
// merge them. Claimers run in precedence order (configured processes,
|
|
6
|
-
// then the opt-in all-Node rule — specific
|
|
7
|
-
// what the previous claimer left in
|
|
5
|
+
// merge them. Claimers run in precedence order (configured processes, the
|
|
6
|
+
// configured claimer packages, then the opt-in all-Node rule — specific
|
|
7
|
+
// before broad); each receives only what the previous claimer left in
|
|
8
|
+
// `remaining`.
|
|
8
9
|
//
|
|
9
10
|
// This package owns naming/reconciliation and the process claimers (host
|
|
10
11
|
// processes matched by the ports addon's `services` settings, no Docker
|
|
11
12
|
// call). Which processes are tunnelled is configuration, not code here; an
|
|
12
|
-
// unmatched listener stays unclaimed — still no numeric-port fallback.
|
|
13
|
-
//
|
|
14
|
-
//
|
|
15
|
-
//
|
|
16
|
-
// `@bakers-build/addon-ddev` (operator decision 2026-10-15: ports must not fire
|
|
17
|
-
// Docker calls itself). `claimServices` below runs the process rules, then
|
|
18
|
-
// DDEV, then all-Node, over one merged raw-discovery pass.
|
|
19
|
-
import { claimDdev, discoverDdevHosts, discoverDdevPorts, parseWebExtraExposedPorts, } from '@bakers-build/addon-ddev';
|
|
13
|
+
// unmatched listener stays unclaimed — still no numeric-port fallback.
|
|
14
|
+
// Container discovery and claiming belong to claimer packages named in
|
|
15
|
+
// `with.claimers` (a `Claimer` each, see below): ports fires no `docker`
|
|
16
|
+
// call itself and knows no runtime's conventions.
|
|
20
17
|
import { discoverHostPorts } from './discovery.js';
|
|
21
18
|
import { DEFAULT_STORYBOOK, LABEL_RE, } from './service-config.js';
|
|
22
19
|
const TICKET_RE = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-\d+$/;
|
|
@@ -224,17 +221,17 @@ async function claimProcesses(raw, remaining, ctx, rules) {
|
|
|
224
221
|
}
|
|
225
222
|
/** Run claimers in precedence order over one raw discovery pass, specific
|
|
226
223
|
* before broad: configured process entries (with the default `storybook`),
|
|
227
|
-
*
|
|
228
|
-
*
|
|
229
|
-
* `<key>-<port>`. */
|
|
230
|
-
export async function claimServices(raw, ctx, rules) {
|
|
224
|
+
* the configured `claimers` in order, then the opt-in all-Node rule.
|
|
225
|
+
* A claimer's keys never change: a process claim on a key a claimer
|
|
226
|
+
* produced becomes `<key>-<port>`. */
|
|
227
|
+
export async function claimServices(raw, ctx, rules, claimers = []) {
|
|
231
228
|
const remaining = new Set(raw.ports.map((_, i) => i));
|
|
232
229
|
const processes = await claimProcesses(raw.ports, remaining, ctx, rules);
|
|
233
|
-
const
|
|
230
|
+
const claimed = claimers.flatMap((c) => c.claim(raw.ports, remaining, ctx));
|
|
234
231
|
const nodes = await processes.allNode();
|
|
235
|
-
const
|
|
232
|
+
const claimedKeys = new Set(claimed.map((s) => s.key));
|
|
236
233
|
const renamed = [...processes.services, ...nodes].map((s) => {
|
|
237
|
-
if (!
|
|
234
|
+
if (!claimedKeys.has(s.key))
|
|
238
235
|
return s;
|
|
239
236
|
const key = `${s.key}-${s.rawPorts[0].hostPort}`;
|
|
240
237
|
return { ...s, key, rules: s.rules.map((r) => ({ ...r, key })) };
|
|
@@ -243,44 +240,31 @@ export async function claimServices(raw, ctx, rules) {
|
|
|
243
240
|
.sort((a, b) => a - b)
|
|
244
241
|
.map((i) => raw.ports[i]);
|
|
245
242
|
return {
|
|
246
|
-
services: [...renamed, ...
|
|
243
|
+
services: [...renamed, ...claimed],
|
|
247
244
|
diagnostics: raw.diagnostics,
|
|
248
245
|
unclaimed,
|
|
249
246
|
};
|
|
250
247
|
}
|
|
251
248
|
/** Compose raw lookup and claims — the `list`/`up` entry point.
|
|
252
|
-
* Host-listener discovery (process-rule candidates) stays local;
|
|
253
|
-
*
|
|
254
|
-
*
|
|
255
|
-
* directly here. */
|
|
249
|
+
* Host-listener discovery (process-rule candidates) stays local; every
|
|
250
|
+
* configured claimer discovers its own ports alongside it, and its
|
|
251
|
+
* `context` joins the `ClaimContext` all claimers are handed. */
|
|
256
252
|
export async function discoverClaimedServices(worktree, deps, opts) {
|
|
257
|
-
const
|
|
253
|
+
const claimers = opts.claimers ?? [];
|
|
254
|
+
const [host, ...found] = await Promise.all([
|
|
258
255
|
discoverHostPorts(worktree, deps),
|
|
259
|
-
|
|
260
|
-
discoverDdevHosts(worktree, deps),
|
|
261
|
-
deps.readFile(`${worktree.replace(/\/+$/, '')}/.ddev/config.yaml`),
|
|
256
|
+
...claimers.map((c) => c.discover(worktree, deps)),
|
|
262
257
|
]);
|
|
263
|
-
// BB-681 review I1: a failed `ddev utility configyaml` read must leave a
|
|
264
|
-
// diagnostic, not silently drop every `web-<host>` alias claim — without
|
|
265
|
-
// one, `shouldKeepTunnelRecord` sees no evidence at all for a vanished
|
|
266
|
-
// alias record and `reap` deletes a route that may still be perfectly
|
|
267
|
-
// live, only unobserved this pass.
|
|
268
258
|
const raw = {
|
|
269
|
-
ports: [
|
|
270
|
-
diagnostics: [
|
|
271
|
-
...host.diagnostics,
|
|
272
|
-
...ddev.diagnostics,
|
|
273
|
-
...(hostsResult.ok
|
|
274
|
-
? []
|
|
275
|
-
: [{ source: 'ddev-hosts', message: hostsResult.reason }]),
|
|
276
|
-
],
|
|
259
|
+
ports: [host, ...found].flatMap((d) => d.ports),
|
|
260
|
+
diagnostics: [host, ...found].flatMap((d) => d.diagnostics),
|
|
277
261
|
};
|
|
262
|
+
const context = Object.assign({}, ...found.map((d) => d.context));
|
|
278
263
|
return claimServices(raw, {
|
|
264
|
+
...context,
|
|
279
265
|
worktree,
|
|
280
266
|
ticket: opts.ticket,
|
|
281
267
|
zone: opts.zone,
|
|
282
268
|
probe: opts.probe,
|
|
283
|
-
|
|
284
|
-
...(hostsResult.ok ? { hosts: hostsResult.hosts } : {}),
|
|
285
|
-
}, opts.rules);
|
|
269
|
+
}, opts.rules, claimers);
|
|
286
270
|
}
|
package/dist/src/config.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { Claimer } from './claims.js';
|
|
1
2
|
import { type PortsTransport } from './transport.js';
|
|
2
3
|
/** The ports addon entry's `with`, transport-agnostic: `transport.use`
|
|
3
4
|
* names the package to load; `transport.with` is whatever settings that
|
|
@@ -26,6 +27,13 @@ export declare function portsSettings(worktree: string): Promise<unknown>;
|
|
|
26
27
|
* scope lists the addon. Throws for a malformed `with` in either scope.
|
|
27
28
|
*/
|
|
28
29
|
export declare function readPortsSettings(worktree: string): Promise<unknown>;
|
|
30
|
+
/**
|
|
31
|
+
* Load the claimer packages the ports entry's `with.claimers` names, in
|
|
32
|
+
* order, from the same bases as the transport. Each module exports its
|
|
33
|
+
* `Claimer` as the named export `claimer`; an unresolvable package or a
|
|
34
|
+
* module without one throws a safe diagnostic.
|
|
35
|
+
*/
|
|
36
|
+
export declare function loadClaimers(settings: unknown, home: string): Promise<Claimer[]>;
|
|
29
37
|
/**
|
|
30
38
|
* Resolve, load and construct the configured ports transport from the ports
|
|
31
39
|
* addon entry's `with` (`settings`).
|
package/dist/src/config.js
CHANGED
|
@@ -96,6 +96,36 @@ export async function readPortsSettings(worktree) {
|
|
|
96
96
|
return undefined;
|
|
97
97
|
return found.entry.with ?? found.entry.options;
|
|
98
98
|
}
|
|
99
|
+
/** `home`, the running `bakers` host install, then `process.cwd()` — see
|
|
100
|
+
* `loadPortsTransport`. */
|
|
101
|
+
function loadBases(home) {
|
|
102
|
+
return [
|
|
103
|
+
pathToFileURL(`${home}/`).href,
|
|
104
|
+
...hostInstallBases(),
|
|
105
|
+
pathToFileURL(`${process.cwd()}/`).href,
|
|
106
|
+
];
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Load the claimer packages the ports entry's `with.claimers` names, in
|
|
110
|
+
* order, from the same bases as the transport. Each module exports its
|
|
111
|
+
* `Claimer` as the named export `claimer`; an unresolvable package or a
|
|
112
|
+
* module without one throws a safe diagnostic.
|
|
113
|
+
*/
|
|
114
|
+
export async function loadClaimers(settings, home) {
|
|
115
|
+
const names = settings?.claimers;
|
|
116
|
+
if (!Array.isArray(names))
|
|
117
|
+
return [];
|
|
118
|
+
return Promise.all(names.map(async (spec) => {
|
|
119
|
+
const resolved = resolveModuleEslintStyle(spec, loadBases(home));
|
|
120
|
+
if (resolved === undefined)
|
|
121
|
+
throw new Error(`bakers ports cannot resolve claimer package '${spec}'`);
|
|
122
|
+
const { claimer } = (await import(pathToFileURL(resolved).href));
|
|
123
|
+
if (typeof claimer?.discover !== 'function' ||
|
|
124
|
+
typeof claimer.claim !== 'function')
|
|
125
|
+
throw new Error(`ports claimer '${spec}' has no \`claimer\` export with discover and claim`);
|
|
126
|
+
return claimer;
|
|
127
|
+
}));
|
|
128
|
+
}
|
|
99
129
|
/**
|
|
100
130
|
* Resolve, load and construct the configured ports transport from the ports
|
|
101
131
|
* addon entry's `with` (`settings`).
|
|
@@ -123,11 +153,7 @@ export async function loadPortsTransport(settings, home) {
|
|
|
123
153
|
// `createRequire` as a FILE, which starts `node_modules` lookup one level
|
|
124
154
|
// too high. Same `pathToFileURL(dir + '/')` shape `load-bakers-config.ts`
|
|
125
155
|
// already uses for its own bases.
|
|
126
|
-
const resolved = resolveModuleEslintStyle(spec,
|
|
127
|
-
pathToFileURL(`${home}/`).href,
|
|
128
|
-
...hostInstallBases(),
|
|
129
|
-
pathToFileURL(`${process.cwd()}/`).href,
|
|
130
|
-
]);
|
|
156
|
+
const resolved = resolveModuleEslintStyle(spec, loadBases(home));
|
|
131
157
|
if (resolved === undefined) {
|
|
132
158
|
throw new Error(`bakers ports cannot resolve transport package '${spec}'`);
|
|
133
159
|
}
|
package/dist/src/core.d.ts
CHANGED
|
@@ -1,10 +1,9 @@
|
|
|
1
|
-
export type
|
|
2
|
-
export {
|
|
3
|
-
export { assertNoMachinePorts, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, type PortsMachineConfig, portsSettings, readPortsSettings, withProblems, } from './config.js';
|
|
1
|
+
export { type ClaimContext, type ClaimedDiscovery, type ClaimedService, type Claimer, type ClaimerDeps, type ClaimerDiscovery, type ClaimStatus, type ConfigFileDeps, claimServices, discoverClaimedServices, type HttpProbe, publicHostname, type TunnelRule, } from './claims.js';
|
|
2
|
+
export { assertNoMachinePorts, loadClaimers, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, type PortsMachineConfig, portsSettings, readPortsSettings, withProblems, } from './config.js';
|
|
4
3
|
export { discoverHostPorts, type HostDiscoveryDeps, parseSocketListeners, type SocketListener, } from './discovery.js';
|
|
5
4
|
export { type LockDeps, LockTimeoutError, nodeLockDeps, tunnelLockPath, withTunnelLock, } from './lock.js';
|
|
6
5
|
export { readTunnelState, type StateDeps } from './state.js';
|
|
7
6
|
export { assertPortsTransport, InvalidTransportModuleError, type PortsTransport, type PortsTransportFactory, } from './transport.js';
|
|
8
7
|
export { bringUp as bringUpTunnel, type OperationContext, type OpResult as TunnelOpResult, type ReapResult as TunnelReapResult, readTunnelState as readMachineTunnelRecords, reap as reapTunnels, reconcileTunnels, type TunnelOpsDeps, takeDown as takeDownTunnel, } from './tunnel-ops.js';
|
|
9
8
|
export { assertIdentity, emptyState, type MachineTunnelState, nodeTunnelStateDeps, type ReadResult, readMachineTunnelState, readValidatedMachineState, type TunnelDesiredRecord, type TunnelIdentity, TunnelIdentityMismatchError, type TunnelStateDeps, tunnelStatePath, upsertRecord, writeMachineTunnelState, } from './tunnel-state.js';
|
|
10
|
-
export type { TunnelRecord, TunnelState } from './types.js';
|
|
9
|
+
export type { RawDiagnostic, RawDiscovery, RawPort, Tri, TunnelRecord, TunnelState, } from './types.js';
|
package/dist/src/core.js
CHANGED
|
@@ -6,7 +6,7 @@
|
|
|
6
6
|
// same code the commands run; the cockpit renders their result and drives their
|
|
7
7
|
// actions.
|
|
8
8
|
export { claimServices, discoverClaimedServices, publicHostname, } from './claims.js';
|
|
9
|
-
export { assertNoMachinePorts, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, portsSettings, readPortsSettings, withProblems, } from './config.js';
|
|
9
|
+
export { assertNoMachinePorts, loadClaimers, loadPortsTransport, PORTS_NEEDS_ENTRY, PORTS_RETIRED, portsSettings, readPortsSettings, withProblems, } from './config.js';
|
|
10
10
|
export { discoverHostPorts, parseSocketListeners, } from './discovery.js';
|
|
11
11
|
export { LockTimeoutError, nodeLockDeps, tunnelLockPath, withTunnelLock, } from './lock.js';
|
|
12
12
|
export { readTunnelState } from './state.js';
|
package/dist/src/deps-node.js
CHANGED
|
@@ -43,7 +43,7 @@ export const nodeDiscoveryDeps = {
|
|
|
43
43
|
return { stdout, ok: true };
|
|
44
44
|
}
|
|
45
45
|
catch (err) {
|
|
46
|
-
// A non-zero exit still carries stdout for a command like `
|
|
46
|
+
// A non-zero exit still carries stdout for a command like `docker inspect`
|
|
47
47
|
// outside a project; hand it back so the parser can decide. `code` is
|
|
48
48
|
// the numeric exit code when the process actually ran (e.g. 127 =
|
|
49
49
|
// command not found inside the container); a spawn-level failure
|
package/dist/src/discovery.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { parseSocketListeners, type
|
|
1
|
+
import { parseSocketListeners, type SocketListener } from '@bakers-build/addon-docker-compose';
|
|
2
|
+
import type { RawDiscovery } from './types.js';
|
|
2
3
|
export { parseSocketListeners, type SocketListener };
|
|
3
4
|
/** The injected seams for host-listener discovery. */
|
|
4
5
|
export interface HostDiscoveryDeps {
|
package/dist/src/discovery.js
CHANGED
|
@@ -1,18 +1,13 @@
|
|
|
1
|
-
// BB-676 spec v2 — host-listener discovery only.
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
5
|
-
// binary beyond `ss`, no root.
|
|
1
|
+
// BB-676 spec v2 — host-listener discovery only. Container discovery belongs
|
|
2
|
+
// to the configured claimer packages (`bakers ports` must not fire `docker`
|
|
3
|
+
// itself). This file does exactly one thing: `ss -ltnpH` plus `/proc/<pid>` —
|
|
4
|
+
// no external binary beyond `ss`, no root.
|
|
6
5
|
//
|
|
7
6
|
// The parsers are pure and exported so a test drives them with captured
|
|
8
7
|
// output; the orchestrator takes an injected `run`/`processInfo` so no real
|
|
9
8
|
// socket is ever read in a test.
|
|
10
|
-
import { parseSocketListeners, } from '@bakers-build/addon-
|
|
11
|
-
//
|
|
12
|
-
// used to be reimplemented here byte-for-byte; `@bakers-build/addon-docker-compose`
|
|
13
|
-
// is the one home now (the lower-level package), re-exported through
|
|
14
|
-
// `@bakers-build/addon-ddev` because this addon may not edge to
|
|
15
|
-
// `@bakers-build/addon-docker-compose` directly (`scripts/assert-acyclic.mjs`).
|
|
9
|
+
import { parseSocketListeners, } from '@bakers-build/addon-docker-compose';
|
|
10
|
+
// `@bakers-build/addon-docker-compose` is the one home of the `ss` parser.
|
|
16
11
|
export { parseSocketListeners };
|
|
17
12
|
/** Is `path` inside `worktree` (or the worktree itself)? */
|
|
18
13
|
function underWorktree(path, worktree) {
|
|
@@ -38,7 +33,7 @@ export async function discoverHostPorts(worktree, deps) {
|
|
|
38
33
|
// netstat parity is out of scope). Rather than let a raw `ENOENT` surface
|
|
39
34
|
// as "ss -ltnpH failed" with no further context, name the real cause when
|
|
40
35
|
// we know it, so this reads as an honest platform limitation rather than a
|
|
41
|
-
// mysterious probe failure.
|
|
36
|
+
// mysterious probe failure. Container-routed services are unaffected —
|
|
42
37
|
// the Linux VM behind Docker Desktop still answers these probes fine
|
|
43
38
|
// in-container; only THIS host-process scan is skipped.
|
|
44
39
|
const host = await deps.run('ss', ['-ltnpH']);
|
package/dist/src/index.d.ts
CHANGED
|
@@ -78,7 +78,7 @@ export declare function liveTunnel(record: TunnelDesiredRecord, discovery: Claim
|
|
|
78
78
|
rule?: TunnelRule;
|
|
79
79
|
};
|
|
80
80
|
/** Keys of present records whose freshly claimed rule no longer matches
|
|
81
|
-
* them (e.g. a new container IP after
|
|
81
|
+
* them (e.g. a new container IP after a container restart). A key with no claim
|
|
82
82
|
* at all is `reap`'s business, not stale. */
|
|
83
83
|
export declare function staleKeys(records: readonly TunnelDesiredRecord[], discovery: ClaimedDiscovery): Set<string>;
|
|
84
84
|
/** BB-681 review M6: Quick's URL is a real `trycloudflare.com` allocation,
|
package/dist/src/index.js
CHANGED
|
@@ -17,7 +17,7 @@ import { execFileSync } from 'node:child_process';
|
|
|
17
17
|
import { readdirSync, readFileSync } from 'node:fs';
|
|
18
18
|
import { isAbsolute, join, relative, resolve } from 'node:path';
|
|
19
19
|
import { homeBbDir } from '@bakers-build/core';
|
|
20
|
-
import { discoverClaimedServices, loadPortsTransport, portsSettings, readPortsSettings, } from './core.js';
|
|
20
|
+
import { discoverClaimedServices, loadClaimers, loadPortsTransport, portsSettings, readPortsSettings, } from './core.js';
|
|
21
21
|
import { isOwnedByCurrentUser, listCloudflaredProcesses, nodeDeps, nodeHttpProbe, processStartTime, readLegacyTunnelPids, } from './deps-node.js';
|
|
22
22
|
import { serviceRules } from './service-config.js';
|
|
23
23
|
import { recordMatchesRule } from './tunnel-ops.js';
|
|
@@ -163,16 +163,15 @@ export function shouldKeepTunnelRecord(discovery, key) {
|
|
|
163
163
|
// when it is a whole-probe failure (`ss -ltnpH` itself failing) — the
|
|
164
164
|
// host-side equivalent of a `containerId`-less Docker diagnostic — since
|
|
165
165
|
// that blinds every host-backed no-claim record at once, same as a
|
|
166
|
-
// host-backed claimed record is kept on it above. A
|
|
167
|
-
// (BB-681 review I1)
|
|
168
|
-
//
|
|
169
|
-
//
|
|
170
|
-
// record's reap (BB-681 review N1).
|
|
166
|
+
// host-backed claimed record is kept on it above. A diagnostic carrying a
|
|
167
|
+
// `keyPrefix` (a claimer's, BB-681 review I1) blocks only keys under that
|
|
168
|
+
// prefix — it says nothing about another claim (e.g. `storybook`) in the
|
|
169
|
+
// SAME worktree, so it must not block THAT record's reap (BB-681 review N1).
|
|
171
170
|
return discovery.diagnostics.some((d) => {
|
|
172
171
|
if (d.source === 'host')
|
|
173
172
|
return d.wholePass === true;
|
|
174
|
-
if (d.
|
|
175
|
-
return key ===
|
|
173
|
+
if (d.keyPrefix !== undefined)
|
|
174
|
+
return key === d.keyPrefix || key.startsWith(`${d.keyPrefix}-`);
|
|
176
175
|
return true;
|
|
177
176
|
});
|
|
178
177
|
}
|
|
@@ -209,11 +208,13 @@ async function resolveTransport(worktree) {
|
|
|
209
208
|
/** Claim `worktree`'s services under its own ports settings; throws for a
|
|
210
209
|
* malformed settings entry (see `readPortsSettings`). */
|
|
211
210
|
async function discover(worktree, ticket, zone) {
|
|
211
|
+
const settings = await readPortsSettings(worktree);
|
|
212
212
|
return discoverClaimedServices(worktree, nodeDeps, {
|
|
213
213
|
ticket,
|
|
214
214
|
zone,
|
|
215
215
|
probe: nodeHttpProbe,
|
|
216
|
-
rules: serviceRules(
|
|
216
|
+
rules: serviceRules(settings),
|
|
217
|
+
claimers: await loadClaimers(settings, homeBbDir()),
|
|
217
218
|
});
|
|
218
219
|
}
|
|
219
220
|
/** `discover`, or print its error and set a failing exit code. */
|
|
@@ -258,7 +259,7 @@ export function liveTunnel(record, discovery) {
|
|
|
258
259
|
return rule ? { live: true, rule } : { live: true };
|
|
259
260
|
}
|
|
260
261
|
/** Keys of present records whose freshly claimed rule no longer matches
|
|
261
|
-
* them (e.g. a new container IP after
|
|
262
|
+
* them (e.g. a new container IP after a container restart). A key with no claim
|
|
262
263
|
* at all is `reap`'s business, not stale. */
|
|
263
264
|
export function staleKeys(records, discovery) {
|
|
264
265
|
const stale = new Set();
|
|
@@ -2,14 +2,15 @@
|
|
|
2
2
|
// `services` names a key and a command-line substring per service; the port is
|
|
3
3
|
// always read from the running process. `all_node` (opt-in) claims every
|
|
4
4
|
// remaining Node listener. Storybook is a shipped default entry, so every
|
|
5
|
-
// process-based service follows one rule.
|
|
5
|
+
// process-based service follows one rule. `claimers` names claimer packages
|
|
6
|
+
// (loaded by `config.ts`'s `loadClaimers`), run in order after the services.
|
|
6
7
|
/** A DNS-safe service key (one hostname label). */
|
|
7
8
|
export const LABEL_RE = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?$/;
|
|
8
9
|
export const DEFAULT_STORYBOOK = {
|
|
9
10
|
key: 'storybook',
|
|
10
11
|
match: 'storybook',
|
|
11
12
|
};
|
|
12
|
-
const WITH_KEYS = new Set(['transport', 'services', 'all_node']);
|
|
13
|
+
const WITH_KEYS = new Set(['transport', 'services', 'all_node', 'claimers']);
|
|
13
14
|
const ENTRY_KEYS = new Set(['key', 'match']);
|
|
14
15
|
const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
|
|
15
16
|
/** Every problem in a ports entry's `with`; `[]` when it is valid or absent. */
|
|
@@ -23,9 +24,13 @@ export function checkWith(value) {
|
|
|
23
24
|
if (!WITH_KEYS.has(k))
|
|
24
25
|
out.push({
|
|
25
26
|
key: k,
|
|
26
|
-
message: 'is not a ports setting (transport, services, all_node)',
|
|
27
|
+
message: 'is not a ports setting (transport, services, all_node, claimers)',
|
|
27
28
|
});
|
|
28
|
-
const { transport, services, all_node } = value;
|
|
29
|
+
const { transport, services, all_node, claimers } = value;
|
|
30
|
+
if (claimers !== undefined &&
|
|
31
|
+
(!Array.isArray(claimers) ||
|
|
32
|
+
!claimers.every((c) => typeof c === 'string' && c !== '')))
|
|
33
|
+
out.push({ key: 'claimers', message: 'must be an array of package names' });
|
|
29
34
|
if (transport !== undefined) {
|
|
30
35
|
if (!isObject(transport))
|
|
31
36
|
out.push({ key: 'transport', message: 'must be an object' });
|
package/dist/src/tools.js
CHANGED
|
@@ -7,11 +7,11 @@ import { existsSync, realpathSync } from 'node:fs';
|
|
|
7
7
|
import { homeBbDir } from '@bakers-build/core';
|
|
8
8
|
import { servicesToShare, shareAll } from './claim-share.js';
|
|
9
9
|
import { discoverClaimedServices } from './claims.js';
|
|
10
|
-
import { assertNoMachinePorts, bringUpTunnel, loadPortsTransport, readMachineTunnelRecords, reapTunnels, takeDownTunnel, withProblems, } from './core.js';
|
|
10
|
+
import { assertNoMachinePorts, bringUpTunnel, loadClaimers, loadPortsTransport, readMachineTunnelRecords, reapTunnels, takeDownTunnel, withProblems, } from './core.js';
|
|
11
11
|
import { nodeDeps, nodeHttpProbe, nodeTunnelOpsDeps } from './deps-node.js';
|
|
12
12
|
import { currentBranch, liveTunnel, resolveTicketIdentifier, selectService, staleKeys, } from './index.js';
|
|
13
13
|
import { serviceRules } from './service-config.js';
|
|
14
|
-
/**
|
|
14
|
+
/** Container labels carry the real path; discovery matches it exactly. */
|
|
15
15
|
function canonicalPath(path) {
|
|
16
16
|
try {
|
|
17
17
|
return realpathSync(path);
|
|
@@ -53,7 +53,7 @@ export function portsTools(deps) {
|
|
|
53
53
|
const worktree = canonicalPath(req.worktreePath);
|
|
54
54
|
const ticket = ticketOf(req, worktree);
|
|
55
55
|
const lines = [];
|
|
56
|
-
// A container IP reused by another
|
|
56
|
+
// A container IP reused by another project after a container restart
|
|
57
57
|
// would serve that project under a stale route, so every `up` first
|
|
58
58
|
// re-checks every recorded route machine-wide, exactly like `reap`.
|
|
59
59
|
const recheck = await reapAll(transport, req.signal);
|
|
@@ -163,11 +163,12 @@ export function toolsFor(options) {
|
|
|
163
163
|
};
|
|
164
164
|
}
|
|
165
165
|
},
|
|
166
|
-
discover: (worktree, ticket, zone) => discoverClaimedServices(worktree, nodeDeps, {
|
|
166
|
+
discover: async (worktree, ticket, zone) => discoverClaimedServices(worktree, nodeDeps, {
|
|
167
167
|
ticket,
|
|
168
168
|
zone,
|
|
169
169
|
probe: nodeHttpProbe,
|
|
170
170
|
rules: serviceRules(options),
|
|
171
|
+
claimers: await loadClaimers(options, homeBbDir()),
|
|
171
172
|
}),
|
|
172
173
|
readRecords: (worktree) => readMachineTunnelRecords(worktree, homeBbDir(), nodeTunnelOpsDeps),
|
|
173
174
|
bringUp: (rule, ctx) => bringUpTunnel(rule, ctx, nodeTunnelOpsDeps),
|
package/dist/src/types.d.ts
CHANGED
|
@@ -16,3 +16,124 @@ export interface TunnelRecord {
|
|
|
16
16
|
export interface TunnelState {
|
|
17
17
|
readonly tunnels: readonly TunnelRecord[];
|
|
18
18
|
}
|
|
19
|
+
/** One OBSERVATION, not yet a claimed service. A port alone is not an
|
|
20
|
+
* identity (two containers, two site rules can share one). `RawPort`
|
|
21
|
+
* carries every piece of evidence a claimer needs, and a missing probe is
|
|
22
|
+
* `unknown` — never collapsed into `false` — so a permission-denied Docker
|
|
23
|
+
* query cannot read as "this is dead" and revoke a route that is actually
|
|
24
|
+
* still live. */
|
|
25
|
+
export type Tri = boolean | 'unknown';
|
|
26
|
+
export interface RawPort {
|
|
27
|
+
readonly worktree: string;
|
|
28
|
+
readonly containerId?: string;
|
|
29
|
+
readonly containerPort?: number;
|
|
30
|
+
readonly protocol?: 'tcp' | 'udp';
|
|
31
|
+
readonly hostAddress?: string;
|
|
32
|
+
readonly hostPort?: number;
|
|
33
|
+
/** The in-container bind address a listening socket reported, when known —
|
|
34
|
+
* used to tell Docker's embedded DNS resolver (`127.0.0.11`) apart from a
|
|
35
|
+
* real service when picking a dead claim's "what IS listening" sibling. */
|
|
36
|
+
readonly address?: string;
|
|
37
|
+
readonly pid?: number;
|
|
38
|
+
readonly cmdline?: string;
|
|
39
|
+
readonly cwd?: string;
|
|
40
|
+
readonly cwdDeleted?: boolean;
|
|
41
|
+
/** The container's IP on its project network, when it has one. */
|
|
42
|
+
readonly containerIp?: string;
|
|
43
|
+
/** The router-side port of an `HTTP_EXPOSE`/`HTTPS_EXPOSE` mapping. */
|
|
44
|
+
readonly routerPort?: number;
|
|
45
|
+
/** Which `*_EXPOSE` var produced this row's router mapping — the only
|
|
46
|
+
* reliable signal for the target scheme (B): a port that only appears in
|
|
47
|
+
* `HTTP_EXPOSE` must be dialled over plain HTTP, never HTTPS. */
|
|
48
|
+
readonly exposeScheme?: 'http' | 'https';
|
|
49
|
+
readonly virtualHost?: string;
|
|
50
|
+
/** A service-type label, when a project sets one — the more specific
|
|
51
|
+
* naming source than `composeService` when it exists. */
|
|
52
|
+
readonly serviceType?: string;
|
|
53
|
+
/** The `com.docker.compose.service` label (`web`, `mailpit`, `phpmyadmin`,
|
|
54
|
+
* `opensearch`, …) — naming evidence for the claimer. */
|
|
55
|
+
readonly composeService?: string;
|
|
56
|
+
/** `supervisorctl`'s `group:name`, e.g. `webextradaemons:xhgui`. */
|
|
57
|
+
readonly daemon?: string;
|
|
58
|
+
readonly daemonStatus?: 'RUNNING' | 'STOPPED' | 'EXITED' | 'UNKNOWN';
|
|
59
|
+
readonly containerState?: 'running' | 'stopped' | 'unknown';
|
|
60
|
+
/** A real socket was observed bound to this port. */
|
|
61
|
+
readonly listening: Tri;
|
|
62
|
+
/** A router rule claims this port, regardless of whether it listens. */
|
|
63
|
+
readonly exposed: Tri;
|
|
64
|
+
/** The host-bound port `docker inspect`'s `NetworkSettings.Ports` maps this
|
|
65
|
+
* `containerPort` to (BB-500 passthrough target), when published. */
|
|
66
|
+
readonly hostBoundPort?: number;
|
|
67
|
+
}
|
|
68
|
+
export interface RawDiagnostic {
|
|
69
|
+
/** `'claimer'`: reported by a configured claimer package, uninterpreted. */
|
|
70
|
+
readonly source: 'host' | 'docker' | 'web-sockets' | 'supervisor' | 'claimer';
|
|
71
|
+
readonly message: string;
|
|
72
|
+
/** Scopes a no-claim record's reap block to keys `keyPrefix` and
|
|
73
|
+
* `keyPrefix-*`; without it a non-host diagnostic blocks every key. */
|
|
74
|
+
readonly keyPrefix?: string;
|
|
75
|
+
/** D: the container this diagnostic is about, when it is about one in
|
|
76
|
+
* particular — see `ComposeDiagnostic.containerId` (`@bakers-build/addon-docker-compose`)
|
|
77
|
+
* for why this narrows reap's blast radius instead of widening it. */
|
|
78
|
+
readonly containerId?: string;
|
|
79
|
+
/** C: true when this `source: 'host'` diagnostic means the WHOLE host
|
|
80
|
+
* probe (`ss -ltnpH`) failed, blinding every host-backed service at once
|
|
81
|
+
* — the host-side equivalent of a `containerId`-less Docker diagnostic.
|
|
82
|
+
* A per-listener host diagnostic (e.g. "no visible owner") is about one
|
|
83
|
+
* socket, not the whole probe, and must not carry this flag. */
|
|
84
|
+
readonly wholePass?: boolean;
|
|
85
|
+
}
|
|
86
|
+
export interface RawDiscovery {
|
|
87
|
+
readonly ports: readonly RawPort[];
|
|
88
|
+
readonly diagnostics: readonly RawDiagnostic[];
|
|
89
|
+
}
|
|
90
|
+
export interface TunnelRule {
|
|
91
|
+
readonly key: string;
|
|
92
|
+
readonly service: string;
|
|
93
|
+
readonly hostHeader?: string;
|
|
94
|
+
readonly insecureTls?: boolean;
|
|
95
|
+
/** Plain-HTTP origin of the service container itself
|
|
96
|
+
* (`http://<container IP>:<containerPort>`), reachable with the public
|
|
97
|
+
* Host kept; only transports that can dial container IPs (frp) use it. */
|
|
98
|
+
readonly direct?: string;
|
|
99
|
+
}
|
|
100
|
+
export type ClaimStatus = 'healthy' | 'dead' | 'stopped' | 'not-exposed' | 'unknown';
|
|
101
|
+
export interface ClaimedService {
|
|
102
|
+
readonly key: string;
|
|
103
|
+
/** The claimer that owns this service — `'process'` (a configured ports
|
|
104
|
+
* rule), `'node'` (the all-Node rule) or a claimer package's own name. */
|
|
105
|
+
readonly claim: string;
|
|
106
|
+
readonly status: ClaimStatus;
|
|
107
|
+
/** A local address worth opening on this machine. */
|
|
108
|
+
readonly local: string;
|
|
109
|
+
/** Set when the service is shareable but with a known gap (e.g. no login). */
|
|
110
|
+
readonly limitation?: string;
|
|
111
|
+
/** The raw evidence this claim rests on, for `list` and diagnostics. */
|
|
112
|
+
readonly rawPorts: readonly RawPort[];
|
|
113
|
+
/** Empty unless `status === 'healthy'`. */
|
|
114
|
+
readonly rules: readonly TunnelRule[];
|
|
115
|
+
}
|
|
116
|
+
export interface ClaimedDiscovery {
|
|
117
|
+
readonly services: readonly ClaimedService[];
|
|
118
|
+
/** Surfaced raw-discovery diagnostics — a caller (reap) must be able to
|
|
119
|
+
* tell "nothing is here" from "the probe itself could not see", so a
|
|
120
|
+
* denied Docker query cannot read as every service having vanished. */
|
|
121
|
+
readonly diagnostics: readonly RawDiagnostic[];
|
|
122
|
+
/** Every raw identity no claimer picked up — `list` shows these dimmed,
|
|
123
|
+
* literally "no addon" (spec): visible, but never shareable. */
|
|
124
|
+
readonly unclaimed: readonly RawPort[];
|
|
125
|
+
}
|
|
126
|
+
/** A single bounded, non-redirecting HTTP probe — injected, never a real fetch here. */
|
|
127
|
+
export type HttpProbe = (url: string, opts: {
|
|
128
|
+
readonly timeoutMs: number;
|
|
129
|
+
}) => Promise<{
|
|
130
|
+
readonly ok: boolean;
|
|
131
|
+
readonly status: number;
|
|
132
|
+
readonly body: string;
|
|
133
|
+
} | null>;
|
|
134
|
+
export interface ClaimContext {
|
|
135
|
+
readonly worktree: string;
|
|
136
|
+
readonly ticket: string;
|
|
137
|
+
readonly zone: string;
|
|
138
|
+
readonly probe: HttpProbe;
|
|
139
|
+
}
|
package/dist/src/types.js
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
// captured command output and substituted process spawning, and never starts
|
|
6
6
|
// a tunnel or reads a real socket table.
|
|
7
7
|
//
|
|
8
|
-
//
|
|
9
|
-
//
|
|
10
|
-
// `@bakers-build/addon-
|
|
8
|
+
// `RawPort`/`RawDiagnostic`/`RawDiscovery` and the claim contract
|
|
9
|
+
// (`ClaimedService`/`TunnelRule`/`ClaimContext`/…) are owned here; claimer
|
|
10
|
+
// packages import them from `@bakers-build/addon-ports/core`.
|
|
11
11
|
export {};
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@bakers-build/addon-ports",
|
|
3
|
-
"version": "0.6.1-next.
|
|
4
|
-
"description": "bakers.build ports command plugin: discover a ticket worktree's running services (
|
|
3
|
+
"version": "0.6.1-next.6",
|
|
4
|
+
"description": "bakers.build ports command plugin: discover a ticket worktree's running services (claimer packages' containers, Storybook, ad-hoc listeners) and bring shareable tunnels up and down. The command half of BB-475; usable without the cockpit half.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
7
7
|
"exports": {
|
|
@@ -23,15 +23,15 @@
|
|
|
23
23
|
"directory": "bakers-cli/addons/ports"
|
|
24
24
|
},
|
|
25
25
|
"dependencies": {
|
|
26
|
-
"@bakers-build/addon-
|
|
26
|
+
"@bakers-build/addon-docker-compose": "^0.6.1-next.6",
|
|
27
27
|
"commander": "^12.1.0"
|
|
28
28
|
},
|
|
29
29
|
"peerDependencies": {
|
|
30
|
-
"@bakers-build/conductor": "^0.6.1-next.
|
|
31
|
-
"@bakers-build/core": "^0.6.1-next.
|
|
30
|
+
"@bakers-build/conductor": "^0.6.1-next.6",
|
|
31
|
+
"@bakers-build/core": "^0.6.1-next.6"
|
|
32
32
|
},
|
|
33
33
|
"bakersBuild": {
|
|
34
|
-
"commit": "
|
|
34
|
+
"commit": "12b97ff4aa2422d69dab286141f3234609f32351",
|
|
35
35
|
"channel": "next"
|
|
36
36
|
}
|
|
37
37
|
}
|