@powerhousedao/portle 6.2.3-dev.78 → 6.2.3-dev.80

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 CHANGED
@@ -16,10 +16,19 @@ runner: {
16
16
  },
17
17
  ```
18
18
 
19
- ## What it does today
19
+ ## What runs where
20
20
 
21
- It mounts the `portle` subgraph with one query, `portleReadiness`, which
22
- reports the **publication gate** check by check:
21
+ Portle hosts the relay (frps), the authoritative DNS for every site zone and
22
+ the control plane. This plugin runs the site side on the machine next to the
23
+ switchboard: **frpc** keeps one outbound tunnel to the relay, **Caddy** holds
24
+ the private key and the wildcard certificate (obtained by DNS-01 through the
25
+ relay's DNS) and terminates TLS locally, forwarding `app.<zone>` to Connect and
26
+ `api.<zone>` to the Switchboard. The relay never decrypts anything.
27
+
28
+ ## The publication gate
29
+
30
+ The plugin brings the tunnel up only for a host that is locked down, and only
31
+ for one of its admins. `portleReadiness` reports the gate check by check:
23
32
 
24
33
  | Check | Passes when |
25
34
  |---|---|
@@ -30,19 +39,50 @@ reports the **publication gate** check by check:
30
39
  | `admins` | `ADMINS` lists at least one address |
31
40
  | `caller` | the caller is one of those addresses |
32
41
 
33
- Every check carries the setting to change when it fails. The report also
34
- carries warnings that no setting can clear, such as the project's own
35
- subgraphs having to guard their resolvers themselves.
42
+ Every failing check carries the setting to change. The report also carries
43
+ warnings no setting can clear, such as the project's own subgraphs having to
44
+ guard their resolvers themselves. The gate is judged on the host's resolved
45
+ settings, not on environment variable names, so a setting that is inert under
46
+ the active policy never counts.
47
+
48
+ It is an interlock, not security: what makes it meaningful is that the same
49
+ plugin owns the tunnel, so "published" implies "locked down" for as long as the
50
+ plugin is the thing publishing. At boot the tunnel comes back only when the
51
+ operator left it running **and** the host still passes the gate.
52
+
53
+ ## The `portle` subgraph
54
+
55
+ Under an `OPEN` policy `portleReadiness` answers everyone (there is no admin to
56
+ tell apart) and everything else is refused. Under any other policy every field
57
+ is for listed admins only.
58
+
59
+ ```graphql
60
+ query { portleReadiness { publishable checks { id ok detail fix } me { address isAdmin } } }
61
+ query { portleStatus { enrolled siteZone delegation { zone nameservers } settings { upstreams { label target } autostart } binaries { frpc caddy } tunnel { state frpc { running pid restarts } caddy { running } } urls } }
62
+
63
+ mutation { portleEnrol(controlPlaneUrl: "https://cp.portle.host", token: "…") { siteZone delegation { nameservers } } }
64
+ mutation { portleConfigure(appUpstream: "127.0.0.1:2540", upstreams: [{ label: "api", target: "127.0.0.1:7540" }]) { urls } }
65
+ mutation { portleStart { tunnel { state } } } # refused unless every readiness check passes for the caller
66
+ mutation { portleStop { tunnel { state } } }
67
+ ```
68
+
69
+ ## On disk
36
70
 
37
- The gate is judged on the host's resolved authorization settings, not on
38
- environment variable names, so a setting that is inert under the active
39
- policy never counts for or against.
71
+ Everything lives under the project's `.ph/portle/`: `enrollment.json` (the
72
+ site's identity and secrets, mode 600), `site.json` (the operator's choices and
73
+ `autostart`), the rendered `frpc.toml`, `Caddyfile` and `certs/`, Caddy's data
74
+ directory `caddy/` (the certificate, which must persist) and `logs/`.
40
75
 
41
- Under an `OPEN` policy the query answers everyone (there is no admin to tell
42
- apart); under any other policy only a listed admin may ask.
76
+ The two executables are looked up in this order: `PORTLE_FRPC_BIN` /
77
+ `PORTLE_CADDY_BIN`, then `~/.ph/portle/bin/`, then the PATH. The Caddy must
78
+ be Portle's build with the `rfc2136` and `acmedns` DNS modules; a stock Caddy
79
+ starts but cannot obtain the certificate. Fetching them from the control
80
+ plane's release endpoint is the next step.
43
81
 
44
- ## What follows
82
+ ## For a customer zone
45
83
 
46
- Enrolment with the relay, and the site tunnel (frpc and Caddy under the
47
- plugin's supervision) that comes up only while the gate passes. See the plan
48
- in the Powerhouse workspace.
84
+ The zone (`dev.example.com`) must be delegated to the relay's nameservers
85
+ before Caddy's first start, or the CA caches a negative answer for an hour.
86
+ `portleStatus.delegation` names the records to create. The relay's site agent
87
+ waits for the delegation on its own; this plugin reports it and the studio
88
+ UI will poll it.
package/dist/index.d.mts CHANGED
@@ -1,3 +1,4 @@
1
+ import { C as EnrollmentResponse, D as resolveBinaries, E as portleBinDir, S as writeSiteSettings, T as BinaryLocations, _ as projectRootOf, a as SettingsPatch, b as stateDirOf, c as Supervised, d as SupervisedStatus, f as DEFAULT_SITE_SETTINGS, g as SiteSettings, h as SITE_FILE, i as PortleRunnerLike, l as SupervisedLike, m as PORTLE_DIR, n as PortleRunner, o as TunnelState, p as ENROLLMENT_FILE, r as PortleRunnerDeps, s as TunnelStatus, t as EnrolInput, u as SupervisedOptions, v as readEnrollment, w as BINARY_ENV, x as writeEnrollment, y as readSiteSettings } from "./runner-DjoiJrWX.mjs";
1
2
  import { API, Context, ISubgraph } from "@powerhousedao/reactor-api";
2
3
  //#region src/gate.d.ts
3
4
  /**
@@ -50,6 +51,11 @@ export declare function isListedAdmin(admins: readonly string[], address: string
50
51
  export declare function evaluateGate(facts: GateFacts, caller: {
51
52
  address?: string;
52
53
  } | undefined): GateReport;
54
+ /**
55
+ * The gate without the caller: what the host itself must satisfy before the
56
+ * tunnel may come up unattended at boot. The caller check is per request.
57
+ */
58
+ export declare function bootGatePasses(facts: GateFacts): boolean;
53
59
  //#endregion
54
60
  //#region src/subgraph.d.ts
55
61
  /** The slice of the switchboard's API object the subgraph reads. */
@@ -68,13 +74,76 @@ type PortleReadiness = GateReport & {
68
74
  };
69
75
  };
70
76
  export declare function readiness(api: PortleApi, ctx: Context): PortleReadiness;
77
+ /** Every other field: a listed admin on a host that is not OPEN. */
78
+ export declare function requireAdmin(api: PortleApi, ctx: Context): GateFacts;
79
+ type WireUpstream = {
80
+ label: string;
81
+ target: string;
82
+ };
83
+ /** The GraphQL shape of a status: maps become lists, exits flatten. */
84
+ export declare function toWireStatus(status: TunnelStatus, delegated?: boolean | null): {
85
+ stateDir: string;
86
+ enrolled: boolean;
87
+ siteId: string | null;
88
+ siteZone: string | null;
89
+ zoneKind: string | null;
90
+ binaries: BinaryLocations;
91
+ urls: string[];
92
+ delegation: {
93
+ zone: string;
94
+ nameservers: string[];
95
+ delegated: boolean | null;
96
+ } | null;
97
+ settings: {
98
+ controlPlaneUrl: string;
99
+ appUpstream: string;
100
+ dns01Mode: "rfc2136" | "acmedns";
101
+ listen: {
102
+ https: number;
103
+ http: number;
104
+ };
105
+ autostart: boolean;
106
+ rewriteHostHeader: boolean;
107
+ sameOrigin: boolean;
108
+ upstreams: WireUpstream[];
109
+ } | null;
110
+ tunnel: {
111
+ state: TunnelState;
112
+ frpc: {
113
+ name: string;
114
+ command: string;
115
+ running: boolean;
116
+ pid: number | null;
117
+ startedAt: string | null;
118
+ restarts: number;
119
+ lastExitCode: number | null;
120
+ lastExitSignal: string | null;
121
+ lastExitAt: string | null;
122
+ } | null;
123
+ caddy: {
124
+ name: string;
125
+ command: string;
126
+ running: boolean;
127
+ pid: number | null;
128
+ startedAt: string | null;
129
+ restarts: number;
130
+ lastExitCode: number | null;
131
+ lastExitSignal: string | null;
132
+ lastExitAt: string | null;
133
+ } | null;
134
+ };
135
+ };
136
+ interface PortleSubgraphDeps {
137
+ api: PortleApi;
138
+ runner: PortleRunnerLike;
139
+ }
71
140
  /**
72
141
  * The `portle` subgraph as a plain `ISubgraph`: no reactor reads, no setup,
73
142
  * so it needs none of `BaseSubgraph` and keeps the plugin free of runtime
74
143
  * imports from reactor-api.
75
144
  */
76
- export declare function createPortleSubgraph(api: PortleApi): ISubgraph;
145
+ export declare function createPortleSubgraph({ api, runner }: PortleSubgraphDeps): ISubgraph;
77
146
  //#endregion
78
- export type { GateCheck, GateCheckId, GateFacts, GateReport, PortleApi, PortlePolicy, PortleReadiness };
147
+ export { BINARY_ENV, type BinaryLocations, DEFAULT_SITE_SETTINGS, ENROLLMENT_FILE, type EnrolInput, type EnrollmentResponse, type GateCheck, type GateCheckId, type GateFacts, type GateReport, PORTLE_DIR, type PortleApi, type PortlePolicy, type PortleReadiness, PortleRunner, type PortleRunnerDeps, type PortleRunnerLike, type PortleSubgraphDeps, SITE_FILE, type SettingsPatch, type SiteSettings, Supervised, type SupervisedLike, type SupervisedOptions, type SupervisedStatus, type TunnelState, type TunnelStatus, portleBinDir, projectRootOf, readEnrollment, readSiteSettings, resolveBinaries, stateDirOf, writeEnrollment, writeSiteSettings };
79
148
  export {};
80
149
  //# sourceMappingURL=index.d.mts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.mts","names":[],"sources":["../src/gate.ts","../src/subgraph.ts"],"mappings":";;;;;;;;;;;;;;;;;;KAiBY;;UAGK;EACf,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;UAGe;EACf,IAAI;EACJ;;EAEA;;EAEA;;KAGU;UASK;;EAEf;EACA,QAAQ;;EAER,UAAU;;;wBAII,cACd,2BACA;wBAUc,aACd,OAAO,WACP;EAAU;gBACT;;;;KC/DS,YAAY,KACtB;;EAIA;;qBAGW;qBAEA,kCAAc;;wBA+BX,YAAY,KAAK,YAAY;KAWjC,kBAAkB;EAC5B;IAAM;IAAwB;;;wBAGhB,UAAU,KAAK,WAAW,KAAK,UAAU;;;;;;wBAoBzC,qBAAqB,KAAK,YAAY"}
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/gate.ts","../src/subgraph.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAiBY;;UAGK;EACf,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;UAGe;EACf,IAAI;EACJ;;EAEA;;EAEA;;KAGU;UASK;;EAEf;EACA,QAAQ;;EAER,UAAU;;;wBAII,cACd,2BACA;wBAUc,aACd,OAAO,WACP;EAAU;gBACT;;;;;wBA6Fa,eAAe,OAAO;;;;KC3J1B,YAAY,KACtB;;EAIA;;qBAGW;qBAEA,kCAAc;;wBA+IX,YAAY,KAAK,YAAY;KAWjC,kBAAkB;EAC5B;IAAM;IAAwB;;;wBAOhB,UAAU,KAAK,WAAW,KAAK,UAAU;;wBAczC,aAAa,KAAK,WAAW,KAAK,UAAU;KAavD;EAAiB;EAAe;;;wBAGrB,aACd,QAAQ,cACR;;;;;;YADQ;;;;;;;;;;;;;;;;;;;;;IA2BJ;IACA;;;;;;;;;;;IACA;;;;;;;;;;;;;UAKW;EACf,KAAK;EACL,QAAQ;;;;;;;wBAQM,uBACd,KACA,UACC,qBAAqB"}
package/dist/index.mjs CHANGED
@@ -1,2 +1,2 @@
1
- import { a as readiness, i as portleTypeDefs, n as createPortleSubgraph, o as evaluateGate, r as gateFactsOf, s as isListedAdmin, t as PORTLE_SUBGRAPH_NAME } from "./subgraph-D7PtSa_n.mjs";
2
- export { PORTLE_SUBGRAPH_NAME, createPortleSubgraph, evaluateGate, gateFactsOf, isListedAdmin, portleTypeDefs, readiness };
1
+ import { C as BINARY_ENV, S as isListedAdmin, T as resolveBinaries, _ as stateDirOf, a as readiness, b as bootGatePasses, c as PortleRunner, d as ENROLLMENT_FILE, f as PORTLE_DIR, g as readSiteSettings, h as readEnrollment, i as portleTypeDefs, l as Supervised, m as projectRootOf, n as createPortleSubgraph, o as requireAdmin, p as SITE_FILE, r as gateFactsOf, s as toWireStatus, t as PORTLE_SUBGRAPH_NAME, u as DEFAULT_SITE_SETTINGS, v as writeEnrollment, w as portleBinDir, x as evaluateGate, y as writeSiteSettings } from "./subgraph-6lmwvcN4.mjs";
2
+ export { BINARY_ENV, DEFAULT_SITE_SETTINGS, ENROLLMENT_FILE, PORTLE_DIR, PORTLE_SUBGRAPH_NAME, PortleRunner, SITE_FILE, Supervised, bootGatePasses, createPortleSubgraph, evaluateGate, gateFactsOf, isListedAdmin, portleBinDir, portleTypeDefs, projectRootOf, readEnrollment, readSiteSettings, readiness, requireAdmin, resolveBinaries, stateDirOf, toWireStatus, writeEnrollment, writeSiteSettings };
@@ -0,0 +1,308 @@
1
+ import { spawn } from "node:child_process";
2
+ //#region src/binaries.d.ts
3
+ /**
4
+ * Where the two executables come from, in order:
5
+ * 1. `PORTLE_FRPC_BIN` / `PORTLE_CADDY_BIN` (an explicit path wins, and only it is tried);
6
+ * 2. `~/.ph/portle/bin/<name>` (where the release download will put them);
7
+ * 3. the PATH.
8
+ * The Caddy must be Portle's own build (rfc2136 + acme-dns modules); a stock
9
+ * Caddy on the PATH starts but cannot obtain the certificate.
10
+ */
11
+ interface BinaryLocations {
12
+ frpc: string | null;
13
+ caddy: string | null;
14
+ /** Every path that was looked at, for the status report. */
15
+ searched: string[];
16
+ }
17
+ interface ResolveBinariesOptions {
18
+ env?: NodeJS.ProcessEnv;
19
+ home?: string;
20
+ platform?: NodeJS.Platform;
21
+ exists?: (path: string) => boolean;
22
+ }
23
+ declare const BINARY_ENV: {
24
+ readonly frpc: "PORTLE_FRPC_BIN";
25
+ readonly caddy: "PORTLE_CADDY_BIN";
26
+ };
27
+ declare function portleBinDir(home: string, platform?: NodeJS.Platform): string;
28
+ declare function resolveBinaries(options?: ResolveBinariesOptions): BinaryLocations;
29
+ //#endregion
30
+ //#region src/delegation.d.ts
31
+ type ResolveNs = (zone: string) => Promise<string[]>;
32
+ type DelegationCheckOptions = {
33
+ /** Resolver attempts before a failure is reported; default 4. */
34
+ attempts?: number;
35
+ /** First retry delay, doubled per attempt; default 1000 ms. */
36
+ delayMs?: number;
37
+ sleep?: (ms: number) => Promise<void>;
38
+ };
39
+ //#endregion
40
+ //#region src/site/hostnames.d.ts
41
+ type ZoneKind = "customer" | "shared";
42
+ //#endregion
43
+ //#region src/site/types.d.ts
44
+ /**
45
+ * What the control plane answers to `POST /v1/enroll`. Vendored from
46
+ * site-relay (`packages/shared/src/types.ts` at df26ab8); the secrets in it
47
+ * live only in the plugin's state directory, mode 600.
48
+ */
49
+ interface EnrollmentResponse {
50
+ siteId: string;
51
+ siteSecret: string;
52
+ /** The DNS name the site lives under: `*.<siteZone>` is its wildcard. */
53
+ siteZone: string;
54
+ zoneKind: ZoneKind;
55
+ /**
56
+ * For a customer zone: the delegation the customer must create at their DNS
57
+ * provider (`<zone> NS <nameserver>` for each nameserver). Null for shared.
58
+ */
59
+ delegation: {
60
+ zone: string;
61
+ nameservers: string[];
62
+ } | null;
63
+ frp: {
64
+ serverAddr: string;
65
+ serverPort: number;
66
+ token: string;
67
+ /** PEM bundle the site must trust for the frps control connection. */
68
+ caPem: string;
69
+ serverName: string;
70
+ };
71
+ dns: {
72
+ tsigKeyName: string;
73
+ tsigAlgorithm: string;
74
+ tsigSecret: string;
75
+ /** host:port of the authoritative server that accepts RFC2136 updates. */
76
+ server: string;
77
+ /** Resolvers Caddy should use to check that the challenge TXT is visible. */
78
+ resolvers: string[];
79
+ };
80
+ /** HTTPS fallback for DNS-01 (acme-dns protocol served by the control plane). */
81
+ acmeDns: {
82
+ baseUrl: string;
83
+ username: string;
84
+ password: string;
85
+ fullDomain: string;
86
+ subdomain: string;
87
+ };
88
+ acme: {
89
+ caUrl?: string;
90
+ caRootPem?: string;
91
+ email: string;
92
+ };
93
+ }
94
+ //#endregion
95
+ //#region src/state.d.ts
96
+ /**
97
+ * Everything the plugin keeps on disk lives under `<project>/.ph/portle/`:
98
+ *
99
+ * enrollment.json the site's identity and secrets (mode 600)
100
+ * site.json the operator's choices: what the tunnel exposes, autostart
101
+ * frpc.toml, Caddyfile, certs/ rendered on every start (mode 600)
102
+ * caddy/ Caddy's data dir: the certificate, which must persist
103
+ * logs/ frpc.log, caddy.log
104
+ */
105
+ declare const PORTLE_DIR: string;
106
+ declare const ENROLLMENT_FILE = "enrollment.json";
107
+ declare const SITE_FILE = "site.json";
108
+ /** The operator's choices, kept beside the enrolment. */
109
+ interface SiteSettings {
110
+ /** The control plane the site enrolled with (needed for `ask` and acme-dns). */
111
+ controlPlaneUrl: string;
112
+ /** host:port every name proxies to unless `upstreams` names its label. */
113
+ appUpstream: string;
114
+ /** Per-label upstreams, e.g. `{ api: "127.0.0.1:7540", app: "127.0.0.1:2540" }`. */
115
+ upstreams: Record<string, string>;
116
+ /** rfc2136 straight to the relay's PowerDNS, or the acme-dns HTTPS fallback. */
117
+ dns01Mode: "rfc2136" | "acmedns";
118
+ /**
119
+ * The local ports Caddy listens on. 443/80 is what the LAN path needs; a
120
+ * machine that cannot bind them (another server, macOS without root)
121
+ * can use high ports and still be reached through the relay.
122
+ */
123
+ listen: {
124
+ https: number;
125
+ http: number;
126
+ };
127
+ /**
128
+ * Send the upstream's own host:port as the Host header instead of the
129
+ * public name. Dev servers that check the Host header (Vite's
130
+ * `server.allowedHosts`) refuse the public name otherwise.
131
+ */
132
+ rewriteHostHeader?: boolean;
133
+ /**
134
+ * Publish Connect and the switchboard on ONE origin: the `app` label also
135
+ * serves the switchboard's paths (proxied to the `api` upstream) and a
136
+ * runtime config in which the switchboard's local origin is replaced by
137
+ * the public one. Needs both the `app` and `api` labels. Default on.
138
+ */
139
+ sameOrigin?: boolean;
140
+ /** Bring the tunnel up at boot when the gate passes. Set by start, cleared by stop. */
141
+ autostart: boolean;
142
+ }
143
+ /**
144
+ * The project root the switchboard serves: the directory of its config file
145
+ * when the host passed one, else the working directory.
146
+ */
147
+ declare function projectRootOf(options: {
148
+ configFile?: unknown;
149
+ } | undefined): string;
150
+ declare function stateDirOf(projectRoot: string): string;
151
+ declare function readEnrollment(stateDir: string): EnrollmentResponse | null;
152
+ declare function writeEnrollment(stateDir: string, enrollment: EnrollmentResponse): void;
153
+ declare const DEFAULT_SITE_SETTINGS: Omit<SiteSettings, "controlPlaneUrl">;
154
+ declare function readSiteSettings(stateDir: string): SiteSettings | null;
155
+ declare function writeSiteSettings(stateDir: string, settings: SiteSettings): void;
156
+ //#endregion
157
+ //#region src/supervisor.d.ts
158
+ /**
159
+ * One long-running child (frpc, Caddy) kept alive by the plugin: started
160
+ * hidden, logged to a file, restarted with backoff when it dies, and stopped
161
+ * as a process tree. Mirrors host-core's spawn conventions (`windowsHide`,
162
+ * SIGTERM then SIGKILL after a timeout).
163
+ */
164
+ interface SupervisedOptions {
165
+ name: string;
166
+ command: string;
167
+ args: string[];
168
+ cwd: string;
169
+ /** Appended to; stdout and stderr of every run. */
170
+ logFile: string;
171
+ env?: NodeJS.ProcessEnv;
172
+ /** Restart delay after a death: doubles from `initialMs` up to `maxMs`, resets after a healthy run. */
173
+ backoff?: {
174
+ initialMs: number;
175
+ maxMs: number;
176
+ };
177
+ /** A run longer than this resets the backoff. */
178
+ healthyAfterMs?: number;
179
+ stopTimeoutMs?: number;
180
+ platform?: NodeJS.Platform;
181
+ spawnImpl?: typeof spawn;
182
+ onEvent?: (event: SupervisedEvent) => void;
183
+ }
184
+ type SupervisedEvent = {
185
+ type: "started";
186
+ name: string;
187
+ pid: number;
188
+ } | {
189
+ type: "exited";
190
+ name: string;
191
+ code: number | null;
192
+ signal: string | null;
193
+ restarting: boolean;
194
+ delayMs: number;
195
+ } | {
196
+ type: "stopped";
197
+ name: string;
198
+ } | {
199
+ type: "spawn-failed";
200
+ name: string;
201
+ error: string;
202
+ };
203
+ interface SupervisedStatus {
204
+ name: string;
205
+ command: string;
206
+ running: boolean;
207
+ pid: number | null;
208
+ startedAt: string | null;
209
+ restarts: number;
210
+ lastExit: {
211
+ code: number | null;
212
+ signal: string | null;
213
+ at: string;
214
+ } | null;
215
+ }
216
+ interface SupervisedLike {
217
+ start(): void;
218
+ stop(): Promise<void>;
219
+ status(): SupervisedStatus;
220
+ }
221
+ declare class Supervised implements SupervisedLike {
222
+ #private;
223
+ constructor(options: SupervisedOptions);
224
+ status(): SupervisedStatus;
225
+ start(): void;
226
+ stop(): Promise<void>;
227
+ }
228
+ //#endregion
229
+ //#region src/runner.d.ts
230
+ type TunnelState = "down" | "up" | "degraded";
231
+ interface TunnelStatus {
232
+ stateDir: string;
233
+ enrolled: boolean;
234
+ siteId: string | null;
235
+ siteZone: string | null;
236
+ zoneKind: string | null;
237
+ delegation: {
238
+ zone: string;
239
+ nameservers: string[];
240
+ } | null;
241
+ settings: SiteSettings | null;
242
+ binaries: BinaryLocations;
243
+ tunnel: {
244
+ state: TunnelState;
245
+ frpc: SupervisedStatus | null;
246
+ caddy: SupervisedStatus | null;
247
+ };
248
+ /** The public names this site serves, from its labels. */
249
+ urls: string[];
250
+ }
251
+ interface EnrolInput {
252
+ controlPlaneUrl: string;
253
+ token: string;
254
+ }
255
+ type SettingsPatch = Partial<Pick<SiteSettings, "appUpstream" | "upstreams" | "dns01Mode" | "listen" | "rewriteHostHeader" | "sameOrigin">>;
256
+ /** What the subgraph and the hooks drive; the class below is the real one. */
257
+ interface PortleRunnerLike {
258
+ status(): TunnelStatus;
259
+ /** True/false for a customer zone; null when the site needs no delegation. */
260
+ checkDelegation(): Promise<boolean | null>;
261
+ enrol(input: EnrolInput): Promise<TunnelStatus>;
262
+ configure(patch: SettingsPatch): TunnelStatus;
263
+ start(): Promise<TunnelStatus>;
264
+ /** Stops both processes; clears `autostart` unless `keepAutostart` (a host shutdown). */
265
+ stop(options?: StopOptions): Promise<TunnelStatus>;
266
+ }
267
+ interface StopOptions {
268
+ /** The host is going down, not the operator's wish: the tunnel comes back at the next boot. */
269
+ keepAutostart?: boolean;
270
+ }
271
+ interface PortleRunnerDeps extends ResolveBinariesOptions {
272
+ stateDir: string;
273
+ fetchImpl?: typeof fetch;
274
+ resolveNs?: ResolveNs;
275
+ /** Retry policy of the delegation check (tests shorten it). */
276
+ delegationCheck?: DelegationCheckOptions;
277
+ createSupervised?: (options: SupervisedOptions) => SupervisedLike;
278
+ log?: (msg: string, detail?: Record<string, unknown>) => void;
279
+ }
280
+ declare class PortleRunner implements PortleRunnerLike {
281
+ #private;
282
+ constructor(deps: PortleRunnerDeps);
283
+ get stateDir(): string;
284
+ status(): TunnelStatus;
285
+ /** For status: a resolver that cannot answer reads as not delegated (yet). */
286
+ checkDelegation(): Promise<boolean | null>;
287
+ enrol(input: EnrolInput): Promise<TunnelStatus>;
288
+ configure(patch: SettingsPatch): TunnelStatus;
289
+ /** Writes the CA files, frpc.toml and the Caddyfile for the current enrolment and settings. */
290
+ render(): {
291
+ frpcConfig: string;
292
+ caddyfile: string;
293
+ certsDir: string;
294
+ };
295
+ /**
296
+ * Brings the tunnel up. A customer zone must be delegated first: Caddy
297
+ * would otherwise ask the CA for a name the CA cannot resolve, and the
298
+ * negative answer is cached for an hour.
299
+ */
300
+ start(): Promise<TunnelStatus>;
301
+ stop(options?: StopOptions): Promise<TunnelStatus>;
302
+ /** Whether the operator asked for the tunnel to come up at boot. */
303
+ wantsAutostart(): boolean;
304
+ }
305
+ //#endregion
306
+ export { EnrollmentResponse as C, resolveBinaries as D, portleBinDir as E, writeSiteSettings as S, BinaryLocations as T, projectRootOf as _, SettingsPatch as a, stateDirOf as b, Supervised as c, SupervisedStatus as d, DEFAULT_SITE_SETTINGS as f, SiteSettings as g, SITE_FILE as h, PortleRunnerLike as i, SupervisedLike as l, PORTLE_DIR as m, PortleRunner as n, TunnelState as o, ENROLLMENT_FILE as p, PortleRunnerDeps as r, TunnelStatus as s, EnrolInput as t, SupervisedOptions as u, readEnrollment as v, BINARY_ENV as w, writeEnrollment as x, readSiteSettings as y };
307
+ export {};
308
+ //# sourceMappingURL=runner-DjoiJrWX.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runner-DjoiJrWX.d.mts","names":[],"sources":["../src/binaries.ts","../src/delegation.ts","../src/site/hostnames.ts","../src/site/types.ts","../src/state.ts","../src/supervisor.ts","../src/runner.ts"],"mappings":";;;;;;;;;;UAWiB;EACf;EACA;;EAEA;;UAGe;EACf,MAAM,OAAO;EACb;EACA,WAAW,OAAO;EAClB,UAAU;;cAGC;WACX;WACA;;iBAGc,aACd,cACA,WAAU,OAAO;iBAUH,gBACd,UAAS,yBACR;;;KCzBS,aAAa,iBAAiB;KAoC9B;;EAEV;;EAEA;EACA,SAAS,eAAe;;;;KC/Cd;;;;;;;;UCNK;EACf;EACA;;EAEA;EACA,UAAU;;;;;EAKV;IAAc;IAAc;;EAC5B;IACE;IACA;IACA;;IAEA;IACA;;EAEF;IACE;IACA;IACA;;IAEA;;IAEA;;;EAGF;IACE;IACA;IACA;IACA;IACA;;EAEF;IACE;IACA;IACA;;;;;;;;;;;;;;cC1BS;cACA;cACA;;UAGI;;EAEf;;EAEA;;EAEA,WAAW;;EAEX;;;;;;EAMA;IAAU;IAAe;;;;;;;EAMzB;;;;;;;EAOA;;EAEA;;;;;;iBAOc,cACd;EAAW;;iBAQG,WAAW;iBAqBX,eAAe,mBAAmB;iBAYlC,gBACd,kBACA,YAAY;cASD,uBAAuB,KAAK;iBAUzB,iBAAiB,mBAAmB;iBAapC,kBACd,kBACA,UAAU;;;;;;;;;UCjIK;EACf;EACA;EACA;EACA;;EAEA;EACA,MAAM,OAAO;;EAEb;IAAY;IAAmB;;;EAE/B;EACA;EACA,WAAW,OAAO;EAClB,mBAAmB;EACnB,WAAW,OAAO;;KAGR;EACN;EAAiB;EAAc;;EAE/B;EACA;EACA;EACA;EACA;EACA;;EAEA;EAAiB;;EACjB;EAAsB;EAAc;;UAEzB;EACf;EACA;EACA;EACA;EACA;EACA;EACA;IAAY;IAAqB;IAAuB;;;UAGzC;EACf;EACA,QAAQ;EACR,UAAU;;cAGC,sBAAsB;;EAkBjC,YAAY,SAAS;EAWrB,UAAU;EAcV;EAMM,QAAQ;;;;KCpEJ;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;IAAc;IAAc;;EAC5B,UAAU;EACV,UAAU;EACV;IACE,OAAO;IACP,MAAM;IACN,OAAO;;;EAGT;;UAGe;EACf;EACA;;KAGU,gBAAgB,QAC1B,KACE;;UAWa;EACf,UAAU;;EAEV,mBAAmB;EACnB,MAAM,OAAO,aAAa,QAAQ;EAClC,UAAU,OAAO,gBAAgB;EACjC,SAAS,QAAQ;;EAEjB,KAAK,UAAU,cAAc,QAAQ;;UAGtB;;EAEf;;UAGe,yBAAyB;EACxC;EACA,mBAAmB;EACnB,YAAY;;EAEZ,kBAAkB;EAClB,oBAAoB,SAAS,sBAAsB;EACnD,OAAO,aAAa,SAAS;;cAGlB,wBAAwB;;EAKnC,YAAY,MAAM;MAId;EAIJ,UAAU;;EA8BJ,mBAAmB;EAenB,MAAM,OAAO,aAAa,QAAQ;EA8BxC,UAAU,OAAO,gBAAgB;;EA6BjC;IACE;IACA;IACA;;;;;;;EAyFI,SAAS,QAAQ;EA4FjB,KAAK,UAAS,cAAmB,QAAQ;;EAsB/C"}