@powerhousedao/portle 6.2.3-dev.79 → 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 +55 -15
- package/dist/index.d.mts +71 -2
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +2 -2
- package/dist/runner-DjoiJrWX.d.mts +308 -0
- package/dist/runner-DjoiJrWX.d.mts.map +1 -0
- package/dist/subgraph-6lmwvcN4.mjs +1210 -0
- package/dist/subgraph-6lmwvcN4.mjs.map +1 -0
- package/dist/switchboard.d.mts +21 -6
- package/dist/switchboard.d.mts.map +1 -1
- package/dist/switchboard.mjs +67 -14
- package/dist/switchboard.mjs.map +1 -1
- package/package.json +5 -5
- package/dist/subgraph-D7PtSa_n.mjs +0 -141
- package/dist/subgraph-D7PtSa_n.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -16,10 +16,19 @@ runner: {
|
|
|
16
16
|
},
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
## What
|
|
19
|
+
## What runs where
|
|
20
20
|
|
|
21
|
-
|
|
22
|
-
|
|
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
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
38
|
-
|
|
39
|
-
|
|
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
|
-
|
|
42
|
-
|
|
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
|
-
##
|
|
82
|
+
## For a customer zone
|
|
45
83
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
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:
|
|
145
|
+
export declare function createPortleSubgraph({ api, runner }: PortleSubgraphDeps): ISubgraph;
|
|
77
146
|
//#endregion
|
|
78
|
-
export type
|
|
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
|
package/dist/index.d.mts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.mts","names":[],"sources":["../src/gate.ts","../src/subgraph.ts"],"mappings":"
|
|
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
|
|
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"}
|