@fabrika/provider-contract 0.9.0-dev.4 → 0.9.0-dev.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/package.json +13 -2
- package/src/app-cli.ts +81 -0
- package/src/conformance.ts +221 -0
- package/src/control.ts +76 -14
- package/types/src/app-cli.d.ts +46 -0
- package/types/src/conformance.d.ts +22 -0
- package/types/src/control.d.ts +73 -14
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fabrika/provider-contract",
|
|
3
|
-
"version": "0.9.0-dev.
|
|
3
|
+
"version": "0.9.0-dev.6",
|
|
4
4
|
"type": "module",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
@@ -25,6 +25,16 @@
|
|
|
25
25
|
"bun": "./src/installation.ts",
|
|
26
26
|
"types": "./types/src/installation.d.ts",
|
|
27
27
|
"default": "./src/installation.ts"
|
|
28
|
+
},
|
|
29
|
+
"./app-cli": {
|
|
30
|
+
"bun": "./src/app-cli.ts",
|
|
31
|
+
"types": "./types/src/app-cli.d.ts",
|
|
32
|
+
"default": "./src/app-cli.ts"
|
|
33
|
+
},
|
|
34
|
+
"./conformance": {
|
|
35
|
+
"bun": "./src/conformance.ts",
|
|
36
|
+
"types": "./types/src/conformance.d.ts",
|
|
37
|
+
"default": "./src/conformance.ts"
|
|
28
38
|
}
|
|
29
39
|
},
|
|
30
40
|
"scripts": {
|
|
@@ -32,6 +42,7 @@
|
|
|
32
42
|
"test": "bun test"
|
|
33
43
|
},
|
|
34
44
|
"dependencies": {
|
|
35
|
-
"@fabrika/auth-core": "0.9.0-dev.
|
|
45
|
+
"@fabrika/auth-core": "0.9.0-dev.6",
|
|
46
|
+
"@fabrika/proxy-core": "0.9.0-dev.6"
|
|
36
47
|
}
|
|
37
48
|
}
|
package/src/app-cli.ts
ADDED
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
// What a provider's `/cli` module offers the `fabrika` command for an application: `app build`, `app deploy`,
|
|
2
|
+
// `app register` and `fabrika namespace`. The command loads the module by the provider's id and never branches on it.
|
|
3
|
+
|
|
4
|
+
import type { ProviderDeploymentNamespace, ProviderNamespacePlan } from './control'
|
|
5
|
+
|
|
6
|
+
/** The runtime a contract application's generated entry is written for (`@fabrika/app/build`'s `EntryRuntime`). */
|
|
7
|
+
export type AppEntryRuntime = 'bun' | 'cloudflare'
|
|
8
|
+
|
|
9
|
+
/** What a namespace command asks of Control. The `fabrika` command holds the Control origin, the credential and the transport. */
|
|
10
|
+
export interface NamespaceControl {
|
|
11
|
+
create(namespace: ProviderDeploymentNamespace): Promise<unknown>
|
|
12
|
+
adopt(namespace: ProviderDeploymentNamespace): Promise<unknown>
|
|
13
|
+
reconcile(namespaceId: string): Promise<unknown>
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
/** A plan, or the namespace Control answered with; the `fabrika` command validates and prints either. */
|
|
17
|
+
export type NamespaceCommandResult = { readonly plan: ProviderNamespacePlan } | { readonly namespace: unknown }
|
|
18
|
+
|
|
19
|
+
export interface NamespaceCommandContext {
|
|
20
|
+
readonly source: Readonly<Record<string, string | undefined>>
|
|
21
|
+
/** Reads the Control origin and credential, and throws when either is missing: call it after every other input is checked. */
|
|
22
|
+
control(): NamespaceControl
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
export interface NamespaceCli {
|
|
26
|
+
readonly usage: string
|
|
27
|
+
/** `argv` is the command's own arguments, without the router's `--provider` and `--json`. */
|
|
28
|
+
run(subcommand: string, argv: readonly string[], context: NamespaceCommandContext): Promise<NamespaceCommandResult>
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export interface AppCli {
|
|
32
|
+
readonly provider: string
|
|
33
|
+
readonly entryRuntime: AppEntryRuntime
|
|
34
|
+
/** `fabrika app build`, after the command wrote a contract application's entry; `contract` says whether it did. */
|
|
35
|
+
build?(argv: readonly string[], context: { readonly contract: boolean }): Promise<void>
|
|
36
|
+
deploy?(argv: readonly string[]): Promise<void>
|
|
37
|
+
/** The text `fabrika app register` hands Control: the application's manifest for one environment. */
|
|
38
|
+
registrationManifest?(options: { readonly config: string; readonly env: string }): Promise<string>
|
|
39
|
+
readonly namespaces?: NamespaceCli
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
export interface AppCliModule {
|
|
43
|
+
readonly appCli: AppCli
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
const optionalFunction = (value: object, key: string): boolean => {
|
|
47
|
+
const member: unknown = Reflect.get(value, key)
|
|
48
|
+
return member === undefined || typeof member === 'function'
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
const isNamespaceCli = (value: unknown): value is NamespaceCli =>
|
|
52
|
+
typeof value === 'object'
|
|
53
|
+
&& value !== null
|
|
54
|
+
&& 'usage' in value
|
|
55
|
+
&& typeof value.usage === 'string'
|
|
56
|
+
&& 'run' in value
|
|
57
|
+
&& typeof value.run === 'function'
|
|
58
|
+
|
|
59
|
+
export const isAppCli = (value: unknown): value is AppCli =>
|
|
60
|
+
typeof value === 'object'
|
|
61
|
+
&& value !== null
|
|
62
|
+
&& 'provider' in value
|
|
63
|
+
&& typeof value.provider === 'string'
|
|
64
|
+
&& value.provider.trim() !== ''
|
|
65
|
+
&& 'entryRuntime' in value
|
|
66
|
+
&& (value.entryRuntime === 'bun' || value.entryRuntime === 'cloudflare')
|
|
67
|
+
&& optionalFunction(value, 'build')
|
|
68
|
+
&& optionalFunction(value, 'deploy')
|
|
69
|
+
&& optionalFunction(value, 'registrationManifest')
|
|
70
|
+
&& (!('namespaces' in value) || value.namespaces === undefined || isNamespaceCli(value.namespaces))
|
|
71
|
+
|
|
72
|
+
/** `specifier` names the module in the error, so an operator knows which package to upgrade. */
|
|
73
|
+
export const appCliFromModule = (value: unknown, expectedProvider: string, specifier: string): AppCli => {
|
|
74
|
+
if (typeof value !== 'object' || value === null || !('appCli' in value) || !isAppCli(value.appCli)) {
|
|
75
|
+
throw new Error(`${specifier} must export a valid \`appCli\`; a provider release older than this CLI has none`)
|
|
76
|
+
}
|
|
77
|
+
if (value.appCli.provider !== expectedProvider) {
|
|
78
|
+
throw new Error(`${specifier} provides "${value.appCli.provider}", expected "${expectedProvider}"`)
|
|
79
|
+
}
|
|
80
|
+
return value.appCli
|
|
81
|
+
}
|
|
@@ -0,0 +1,221 @@
|
|
|
1
|
+
// The cases every `ControlProvider` passes, whatever cloud it deploys to. A provider's own test file calls
|
|
2
|
+
// `describeControlProviderConformance` once with a harness over its fake cloud: the harness builds the provider and a
|
|
3
|
+
// deploy its cloud accepts, and reports what the cloud was asked to change and to stop.
|
|
4
|
+
|
|
5
|
+
import { describe, expect, test } from 'bun:test'
|
|
6
|
+
import {
|
|
7
|
+
type ControlProvider,
|
|
8
|
+
type ProviderDeployInput,
|
|
9
|
+
type ProviderDeployOutcome,
|
|
10
|
+
ProviderInvocationAbort,
|
|
11
|
+
type ProviderRunEvents,
|
|
12
|
+
} from './control'
|
|
13
|
+
import type { JsonValue } from './json'
|
|
14
|
+
|
|
15
|
+
/** What the suite hands a fake cloud: `accepted` is called once the cloud has taken the deploy's operation. */
|
|
16
|
+
export interface ConformanceCloudHooks {
|
|
17
|
+
accepted(): void
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** One provider over one fresh fake cloud. */
|
|
21
|
+
export interface ConformanceCloud {
|
|
22
|
+
readonly provider: ControlProvider
|
|
23
|
+
/** A deploy the fake cloud accepts and lets succeed. Each case sets `dryRun`, `signal` and `events` itself. */
|
|
24
|
+
readonly input: Omit<ProviderDeployInput, 'dryRun' | 'signal' | 'events'>
|
|
25
|
+
/** The credentials the provider holds itself (a cloud token, a signed URL); no event may carry one. */
|
|
26
|
+
readonly credentials: readonly string[]
|
|
27
|
+
/** Every request that changed the cloud: a write, a created resource, started work. A preview the cloud runs is none. */
|
|
28
|
+
mutations(): readonly string[]
|
|
29
|
+
/** Every request to stop or remove the deploy's work: a cancelled build or job, a deleted version. */
|
|
30
|
+
stops(): readonly string[]
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
export interface ControlProviderConformanceHarness {
|
|
34
|
+
/** Called once per case, and once per event in the lease-loss sweep. */
|
|
35
|
+
create(hooks: ConformanceCloudHooks): ConformanceCloud
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/** A secret the suite adds to every deploy; no event may carry it. */
|
|
39
|
+
const SECRET_NAME = 'CONFORMANCE_SECRET'
|
|
40
|
+
const SECRET_VALUE = 'conformance-secret-value-7f3a9c'
|
|
41
|
+
|
|
42
|
+
/** What a deploy reported through its events, as Control would have persisted it. */
|
|
43
|
+
interface Recorded {
|
|
44
|
+
readonly logs: string[]
|
|
45
|
+
readonly externalIds: Array<{ readonly id: string; readonly state?: JsonValue }>
|
|
46
|
+
readonly checkpoints: JsonValue[]
|
|
47
|
+
/** Events that hold the lease: `boundary`, `externalId` and `checkpoint`, in order. */
|
|
48
|
+
events: number
|
|
49
|
+
/** A state Control could not store as given; collected, because a provider may swallow what an event throws. */
|
|
50
|
+
readonly violations: string[]
|
|
51
|
+
}
|
|
52
|
+
|
|
53
|
+
interface Invocation {
|
|
54
|
+
readonly input: ProviderDeployInput
|
|
55
|
+
readonly recorded: Recorded
|
|
56
|
+
/** Lose the lease as Control does: the signal aborts, and every later event rejects with the same reason. */
|
|
57
|
+
loseLease(): void
|
|
58
|
+
readonly signal: AbortSignal
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
const LEASE_LOST = new ProviderInvocationAbort('lease_lost')
|
|
62
|
+
|
|
63
|
+
/** `lostAt`: the lease goes at this event (1-based), which rejects like every one after it. */
|
|
64
|
+
function invocation(cloud: ConformanceCloud, dryRun: boolean, options: { readonly lostAt?: number } = {}): Invocation {
|
|
65
|
+
const controller = new AbortController()
|
|
66
|
+
const recorded: Recorded = { logs: [], externalIds: [], checkpoints: [], events: 0, violations: [] }
|
|
67
|
+
const loseLease = (): void => {
|
|
68
|
+
if (!controller.signal.aborted) controller.abort(LEASE_LOST)
|
|
69
|
+
}
|
|
70
|
+
const held = async (): Promise<void> => {
|
|
71
|
+
recorded.events += 1
|
|
72
|
+
if (recorded.events === options.lostAt) loseLease()
|
|
73
|
+
if (controller.signal.aborted) throw controller.signal.reason
|
|
74
|
+
}
|
|
75
|
+
const stored = (kind: string, state: JsonValue): JsonValue => {
|
|
76
|
+
const parsed: JsonValue = JSON.parse(JSON.stringify(state))
|
|
77
|
+
if (!Bun.deepEquals(parsed, state, true)) recorded.violations.push(`${kind} state is not JSON as given`)
|
|
78
|
+
return parsed
|
|
79
|
+
}
|
|
80
|
+
const events: ProviderRunEvents = {
|
|
81
|
+
log: (line) => {
|
|
82
|
+
recorded.logs.push(line)
|
|
83
|
+
},
|
|
84
|
+
externalId: async (id, state) => {
|
|
85
|
+
await held()
|
|
86
|
+
recorded.externalIds.push(state === undefined ? { id } : { id, state: stored('externalId', state) })
|
|
87
|
+
},
|
|
88
|
+
checkpoint: async (state) => {
|
|
89
|
+
await held()
|
|
90
|
+
recorded.checkpoints.push(stored('checkpoint', state))
|
|
91
|
+
},
|
|
92
|
+
boundary: held,
|
|
93
|
+
}
|
|
94
|
+
const input: ProviderDeployInput = {
|
|
95
|
+
...cloud.input,
|
|
96
|
+
secrets: { ...cloud.input.secrets, [SECRET_NAME]: SECRET_VALUE },
|
|
97
|
+
dryRun,
|
|
98
|
+
signal: controller.signal,
|
|
99
|
+
events,
|
|
100
|
+
}
|
|
101
|
+
return { input, recorded, loseLease, signal: controller.signal }
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/**
|
|
105
|
+
* The deploy's outcome, or the reason it rejected with. A step a provider stops waiting for may still run, so the
|
|
106
|
+
* cloud is read only after the tasks already queued have run.
|
|
107
|
+
*/
|
|
108
|
+
async function settle(provider: ControlProvider, input: ProviderDeployInput): Promise<ProviderDeployOutcome | { readonly rejected: unknown }> {
|
|
109
|
+
let outcome: ProviderDeployOutcome | { readonly rejected: unknown }
|
|
110
|
+
try {
|
|
111
|
+
outcome = await provider.deploy(input)
|
|
112
|
+
} catch (error) {
|
|
113
|
+
outcome = { rejected: error }
|
|
114
|
+
}
|
|
115
|
+
await new Promise((resolve) => setTimeout(resolve, 0))
|
|
116
|
+
return outcome
|
|
117
|
+
}
|
|
118
|
+
|
|
119
|
+
/** No event carried a credential: the deploy's secrets, its credential managed entries, the upload bearer, the provider's own. */
|
|
120
|
+
function expectCredentialFree(cloud: ConformanceCloud, run: Invocation): void {
|
|
121
|
+
const { input } = run
|
|
122
|
+
const managed = Object.values(input.managedEnvironment).flatMap((entry) => entry.credential && entry.value !== null ? [entry.value] : [])
|
|
123
|
+
const bearer = input.artifactUpload === undefined ? [] : [input.artifactUpload.bearer]
|
|
124
|
+
const reported = JSON.stringify({ logs: run.recorded.logs, externalIds: run.recorded.externalIds, checkpoints: run.recorded.checkpoints })
|
|
125
|
+
for (const credential of [...Object.values(input.secrets), ...managed, ...bearer, ...cloud.credentials]) {
|
|
126
|
+
expect(reported).not.toContain(credential)
|
|
127
|
+
}
|
|
128
|
+
expect(run.recorded.violations).toEqual([])
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
export function describeControlProviderConformance(name: string, harness: ControlProviderConformanceHarness): void {
|
|
132
|
+
const quiet = (): ConformanceCloud => harness.create({ accepted: () => {} })
|
|
133
|
+
|
|
134
|
+
describe(`${name} conforms to ControlProvider`, () => {
|
|
135
|
+
test('a deploy succeeds, and nothing it reports carries a credential', async () => {
|
|
136
|
+
const cloud = quiet()
|
|
137
|
+
const run = invocation(cloud, false)
|
|
138
|
+
expect(await settle(cloud.provider, run.input)).toMatchObject({ state: 'succeeded' })
|
|
139
|
+
expect(cloud.mutations().length).toBeGreaterThan(0)
|
|
140
|
+
expect(cloud.stops()).toEqual([])
|
|
141
|
+
expectCredentialFree(cloud, run)
|
|
142
|
+
})
|
|
143
|
+
|
|
144
|
+
test('a dry run succeeds, changes nothing in the cloud, and reports no credential', async () => {
|
|
145
|
+
const cloud = quiet()
|
|
146
|
+
const run = invocation(cloud, true)
|
|
147
|
+
expect(await settle(cloud.provider, run.input)).toMatchObject({ state: 'succeeded' })
|
|
148
|
+
expect(cloud.mutations()).toEqual([])
|
|
149
|
+
expect(cloud.stops()).toEqual([])
|
|
150
|
+
expectCredentialFree(cloud, run)
|
|
151
|
+
})
|
|
152
|
+
|
|
153
|
+
test('an invocation whose lease is gone at its first event changes nothing in the cloud', async () => {
|
|
154
|
+
const cloud = quiet()
|
|
155
|
+
const run = invocation(cloud, false, { lostAt: 1 })
|
|
156
|
+
expect(await settle(cloud.provider, run.input)).not.toMatchObject({ state: 'succeeded' })
|
|
157
|
+
expect(cloud.mutations()).toEqual([])
|
|
158
|
+
expect(cloud.stops()).toEqual([])
|
|
159
|
+
})
|
|
160
|
+
|
|
161
|
+
test('a lease lost at any event of a deploy stops nothing, and the deploy claims no success', async () => {
|
|
162
|
+
const cloud = quiet()
|
|
163
|
+
const complete = invocation(cloud, false)
|
|
164
|
+
await settle(cloud.provider, complete.input)
|
|
165
|
+
expect(complete.recorded.events).toBeGreaterThan(0)
|
|
166
|
+
for (let lostAt = 1; lostAt <= complete.recorded.events; lostAt += 1) {
|
|
167
|
+
const lost = quiet()
|
|
168
|
+
const run = invocation(lost, false, { lostAt })
|
|
169
|
+
const outcome = await settle(lost.provider, run.input)
|
|
170
|
+
// The cloud may still finish the work; this invocation may not claim it, and may not stop it.
|
|
171
|
+
expect({ lostAt, outcome }).not.toMatchObject({ outcome: { state: 'succeeded' } })
|
|
172
|
+
expect({ lostAt, stops: lost.stops() }).toEqual({ lostAt, stops: [] })
|
|
173
|
+
expectCredentialFree(lost, run)
|
|
174
|
+
}
|
|
175
|
+
})
|
|
176
|
+
|
|
177
|
+
test('a lease lost once the cloud accepted the deploy stops nothing, in the deploy, a reconcile or a cancel', async () => {
|
|
178
|
+
let run: Invocation | undefined
|
|
179
|
+
let accepted = false
|
|
180
|
+
const cloud = harness.create({
|
|
181
|
+
accepted: () => {
|
|
182
|
+
accepted = true
|
|
183
|
+
run?.loseLease()
|
|
184
|
+
},
|
|
185
|
+
})
|
|
186
|
+
run = invocation(cloud, false)
|
|
187
|
+
const outcome = await settle(cloud.provider, run.input)
|
|
188
|
+
expect(accepted).toBe(true)
|
|
189
|
+
expect(outcome).not.toMatchObject({ state: 'succeeded' })
|
|
190
|
+
expect(cloud.stops()).toEqual([])
|
|
191
|
+
|
|
192
|
+
// Control reconciles and cancels a run by what its last owner recorded.
|
|
193
|
+
const recordedId = run.recorded.externalIds[0]
|
|
194
|
+
if (recordedId === undefined) throw new Error('the deploy recorded no external id before its operation was accepted')
|
|
195
|
+
const providerState = run.recorded.checkpoints.at(-1) ?? recordedId.state
|
|
196
|
+
const reference = {
|
|
197
|
+
runId: run.input.runId,
|
|
198
|
+
externalId: recordedId.id,
|
|
199
|
+
environment: run.input.environment,
|
|
200
|
+
signal: run.signal,
|
|
201
|
+
...(providerState === undefined ? {} : { providerState }),
|
|
202
|
+
}
|
|
203
|
+
const mutations = cloud.mutations().length
|
|
204
|
+
await cloud.provider.reconcile?.(reference).catch(() => {})
|
|
205
|
+
await cloud.provider.cancel?.(reference).catch(() => {})
|
|
206
|
+
await new Promise((resolve) => setTimeout(resolve, 0))
|
|
207
|
+
expect(cloud.stops()).toEqual([])
|
|
208
|
+
expect(cloud.mutations()).toHaveLength(mutations)
|
|
209
|
+
})
|
|
210
|
+
|
|
211
|
+
test('a registration normalizes to itself, and its envelopes survive JSON', () => {
|
|
212
|
+
const cloud = quiet()
|
|
213
|
+
const normalize = cloud.provider.normalizeRegistration
|
|
214
|
+
if (normalize === undefined) return
|
|
215
|
+
const once = normalize({ app: cloud.input.app, environment: cloud.input.environment })
|
|
216
|
+
expect(normalize(once)).toEqual(once)
|
|
217
|
+
expect(JSON.parse(JSON.stringify(once.environment.target))).toEqual(once.environment.target)
|
|
218
|
+
expect(JSON.parse(JSON.stringify(once.environment.artifact))).toEqual(once.environment.artifact)
|
|
219
|
+
})
|
|
220
|
+
})
|
|
221
|
+
}
|
package/src/control.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import type { AppSchema, ContractArtifact } from '@fabrika/auth-core'
|
|
1
|
+
import type { ApplicationObjects, AppSchema, ContractArtifact, ManagedEnvironment } from '@fabrika/auth-core'
|
|
2
|
+
import type { InstallationBrand } from '@fabrika/proxy-core/brand'
|
|
2
3
|
import type { JsonValue, ProviderEnvelope } from './json'
|
|
3
4
|
|
|
4
5
|
/** Events whose persistence and presentation belong to the control plane. */
|
|
@@ -15,8 +16,11 @@ export interface ProviderRunEvents {
|
|
|
15
16
|
boundary(): Promise<void>
|
|
16
17
|
}
|
|
17
18
|
|
|
18
|
-
/**
|
|
19
|
-
|
|
19
|
+
/**
|
|
20
|
+
* Complete platform-owned runtime state, parsed by Control (`parseManagedEnvironment`). A provider writes each entry as
|
|
21
|
+
* a secret when it is a `credential`, removes one whose value is null, and removes the stale ones `staleManagedVariables` names.
|
|
22
|
+
*/
|
|
23
|
+
export type ProviderManagedEnvironment = ManagedEnvironment
|
|
20
24
|
|
|
21
25
|
/** Provider-neutral coordinates for obtaining one app revision. */
|
|
22
26
|
export interface ProviderSource {
|
|
@@ -41,8 +45,7 @@ export interface ProviderDeploymentNamespace {
|
|
|
41
45
|
readonly target: ProviderEnvelope
|
|
42
46
|
}
|
|
43
47
|
|
|
44
|
-
|
|
45
|
-
export const FRAMEWORK_RELEASE_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/
|
|
48
|
+
export { FRAMEWORK_RELEASE_PATTERN } from '@fabrika/auth-core'
|
|
46
49
|
|
|
47
50
|
/**
|
|
48
51
|
* The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
|
|
@@ -64,6 +67,12 @@ export interface ProviderApprovedAccess {
|
|
|
64
67
|
* the framework minor it pins (ADR-0062). Its build checks with that release.
|
|
65
68
|
*/
|
|
66
69
|
readonly checker: string
|
|
70
|
+
/**
|
|
71
|
+
* The `@fabrika/app` release the application's `bun.lock` pins (`FRAMEWORK_RELEASE_PATTERN`), which a release gate
|
|
72
|
+
* reads: `checker` is this platform's patch of that minor, newer than a prerelease pin. Absent in an access Control
|
|
73
|
+
* approved before it recorded the pin.
|
|
74
|
+
*/
|
|
75
|
+
readonly framework?: string
|
|
67
76
|
}
|
|
68
77
|
|
|
69
78
|
/**
|
|
@@ -87,12 +96,18 @@ export interface ProviderEnvironment {
|
|
|
87
96
|
* application's proxy manifest entry as `crossOrigins`.
|
|
88
97
|
*/
|
|
89
98
|
readonly crossOrigins?: readonly string[]
|
|
99
|
+
/**
|
|
100
|
+
* The origin of the environment's active Operations ingest DSN, never the DSN: a contract application's proxy admits
|
|
101
|
+
* it in `connect-src`. Control sets it on a deploy; absent while the environment has no active ingest.
|
|
102
|
+
*/
|
|
103
|
+
readonly operationsOrigin?: string
|
|
90
104
|
readonly namespace?: ProviderDeploymentNamespace
|
|
91
105
|
readonly target: ProviderEnvelope
|
|
92
106
|
readonly artifact: ProviderEnvelope
|
|
93
107
|
/**
|
|
94
108
|
* The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
|
|
95
109
|
* provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
|
|
110
|
+
* Control refuses a non-dry deploy without it.
|
|
96
111
|
*/
|
|
97
112
|
readonly access?: ProviderApprovedAccess
|
|
98
113
|
}
|
|
@@ -146,11 +161,10 @@ export interface ProviderDeployInput {
|
|
|
146
161
|
/** Platform-owned runtime configuration, separate from operator-managed application vars. */
|
|
147
162
|
readonly managedEnvironment: ProviderManagedEnvironment
|
|
148
163
|
/**
|
|
149
|
-
*
|
|
150
|
-
*
|
|
151
|
-
* Absent when the app has no public origin at all, which leaves IAM's registry untouched.
|
|
164
|
+
* The object that serves the environment's ordinary traffic and the objects its ops channel reaches, as Control records
|
|
165
|
+
* them (ADR-0070 §9). A provider whose application runs in no object ignores it; absent, the provider's defaults.
|
|
152
166
|
*/
|
|
153
|
-
readonly
|
|
167
|
+
readonly applicationObjects?: ApplicationObjects
|
|
154
168
|
readonly dryRun: boolean
|
|
155
169
|
readonly sourceBinding?: ProviderSourceBinding
|
|
156
170
|
/** Optional short-lived, run-scoped Operations artifact destination. */
|
|
@@ -167,7 +181,10 @@ export interface ProviderDeployInput {
|
|
|
167
181
|
readonly events: ProviderRunEvents
|
|
168
182
|
}
|
|
169
183
|
|
|
170
|
-
/**
|
|
184
|
+
/**
|
|
185
|
+
* A terminal provider operation result. `succeeded` means the version is live: Control then writes the environment's
|
|
186
|
+
* approved IAM schema itself (ADR-0011), so a provider never calls IAM for an application.
|
|
187
|
+
*/
|
|
171
188
|
export interface ProviderTerminalOutcome {
|
|
172
189
|
readonly state: 'succeeded' | 'failed'
|
|
173
190
|
readonly exitCode?: number
|
|
@@ -230,14 +247,10 @@ export interface ProviderRunReference {
|
|
|
230
247
|
|
|
231
248
|
export interface ProviderCancelInput extends ProviderRunReference {
|
|
232
249
|
readonly signal: AbortSignal
|
|
233
|
-
/** See `ProviderDeployInput.returnOrigins`; a cancel that settles an activated deploy projects the same set. */
|
|
234
|
-
readonly returnOrigins?: readonly string[]
|
|
235
250
|
}
|
|
236
251
|
|
|
237
252
|
export interface ProviderReconcileInput extends ProviderRunReference {
|
|
238
253
|
readonly signal: AbortSignal
|
|
239
|
-
/** See `ProviderDeployInput.returnOrigins`; a provider that settles a deploy here projects the same set. */
|
|
240
|
-
readonly returnOrigins?: readonly string[]
|
|
241
254
|
/** Append a line to the run's log. */
|
|
242
255
|
log?(line: string): Promise<void>
|
|
243
256
|
}
|
|
@@ -338,6 +351,11 @@ export interface ProviderNamespaceMutationInput {
|
|
|
338
351
|
readonly namespace: ProviderDeploymentNamespace
|
|
339
352
|
/** Every app environment assigned to the namespace, read under its lease. */
|
|
340
353
|
readonly members: readonly ProviderNamespaceMember[]
|
|
354
|
+
/**
|
|
355
|
+
* The installation's client logo for the pages the namespace's proxy answers with (ADR-0066), read from IAM for this
|
|
356
|
+
* mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
|
|
357
|
+
*/
|
|
358
|
+
readonly brand?: InstallationBrand | null
|
|
341
359
|
readonly signal: AbortSignal
|
|
342
360
|
readonly events: ProviderNamespaceEvents
|
|
343
361
|
}
|
|
@@ -470,6 +488,19 @@ export interface ProviderNamespaceOperator {
|
|
|
470
488
|
present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation
|
|
471
489
|
}
|
|
472
490
|
|
|
491
|
+
/** The app-owned claims of one namespace whose resources Control is asked to confirm gone. */
|
|
492
|
+
export interface ProviderClaimedResourcesInput {
|
|
493
|
+
readonly namespace: ProviderDeploymentNamespace
|
|
494
|
+
readonly resourceKeys: readonly string[]
|
|
495
|
+
readonly signal: AbortSignal
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
/** What the provider observed for one claimed resource. */
|
|
499
|
+
export interface ProviderClaimedResource {
|
|
500
|
+
readonly resourceKey: string
|
|
501
|
+
readonly exists: boolean
|
|
502
|
+
}
|
|
503
|
+
|
|
473
504
|
/** Optional placement lifecycle owned by providers that use deployment namespaces. */
|
|
474
505
|
export interface ProviderNamespaceCapabilities {
|
|
475
506
|
normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace
|
|
@@ -486,11 +517,21 @@ export interface ProviderNamespaceCapabilities {
|
|
|
486
517
|
reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>
|
|
487
518
|
/** Absent means the namespace has no entry point that follows its members. */
|
|
488
519
|
republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>
|
|
520
|
+
/**
|
|
521
|
+
* Read-only: whether each claimed resource still exists, one answer per key. Throws when it cannot tell, so Control
|
|
522
|
+
* releases a claim only over a resource the provider confirmed gone. Absent means no claim can be released.
|
|
523
|
+
*/
|
|
524
|
+
claimedResources?(input: ProviderClaimedResourcesInput): Promise<readonly ProviderClaimedResource[]>
|
|
489
525
|
/** Absent means the provider changes no namespace in place. */
|
|
490
526
|
readonly updates?: ProviderNamespaceUpdates
|
|
491
527
|
readonly operator?: ProviderNamespaceOperator
|
|
492
528
|
}
|
|
493
529
|
|
|
530
|
+
export interface ProviderAuthoring {
|
|
531
|
+
/** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
|
|
532
|
+
readonly protectedFiles: readonly string[]
|
|
533
|
+
}
|
|
534
|
+
|
|
494
535
|
/** One call on the service of a `dev` environment, between its bootstrap runs. */
|
|
495
536
|
export interface ProviderDevEnvironmentInput {
|
|
496
537
|
readonly environment: ProviderEnvironment
|
|
@@ -527,8 +568,29 @@ export interface ControlProvider {
|
|
|
527
568
|
reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>
|
|
528
569
|
readonly secrets?: ProviderManagedSecrets
|
|
529
570
|
readonly namespaces?: ProviderNamespaceCapabilities
|
|
571
|
+
/** MCP authoring (ADR-0049): an environment of this provider can be an authoring target. Absent means none can. */
|
|
572
|
+
readonly authoring?: ProviderAuthoring
|
|
573
|
+
/**
|
|
574
|
+
* Every application environment gets `FABRIKA_PROXY_SECRET`, with or without a namespace proxy: the provider's own
|
|
575
|
+
* hop to the application carries it (Cloudflare's Worker to its Durable Object, ADR-0065). Absent means only a
|
|
576
|
+
* namespace proxy's environments get one.
|
|
577
|
+
*/
|
|
578
|
+
readonly applicationHopSecret?: true
|
|
530
579
|
/** Absent means the provider runs no `dev` environment, and Control refuses one. */
|
|
531
580
|
readonly devEnvironments?: ProviderDevEnvironments
|
|
581
|
+
/**
|
|
582
|
+
* Whether an environment at this approved access is served the ops channel through which Control reaches its object
|
|
583
|
+
* (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
|
|
584
|
+
* release logic. Absent means no environment of this provider is.
|
|
585
|
+
*/
|
|
586
|
+
opsChannel?(access: ProviderApprovedAccess): boolean
|
|
587
|
+
/**
|
|
588
|
+
* Whether the object at this approved access, served the ops channel, also holds the maintenance barrier (`state`,
|
|
589
|
+
* `migrate`) and serves Control's data operations: the daily backups, a deploy's migration phase and the side restore
|
|
590
|
+
* (ADR-0069 §3, ADR-0070). A release can serve the channel without them. Absent means no environment of this
|
|
591
|
+
* provider is.
|
|
592
|
+
*/
|
|
593
|
+
dataOperations?(access: ProviderApprovedAccess): boolean
|
|
532
594
|
/** Absent means the provider deploys public sources only. */
|
|
533
595
|
readonly source?: ProviderSourceCapabilities
|
|
534
596
|
/**
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { ProviderDeploymentNamespace, ProviderNamespacePlan } from './control';
|
|
2
|
+
/** The runtime a contract application's generated entry is written for (`@fabrika/app/build`'s `EntryRuntime`). */
|
|
3
|
+
export type AppEntryRuntime = 'bun' | 'cloudflare';
|
|
4
|
+
/** What a namespace command asks of Control. The `fabrika` command holds the Control origin, the credential and the transport. */
|
|
5
|
+
export interface NamespaceControl {
|
|
6
|
+
create(namespace: ProviderDeploymentNamespace): Promise<unknown>;
|
|
7
|
+
adopt(namespace: ProviderDeploymentNamespace): Promise<unknown>;
|
|
8
|
+
reconcile(namespaceId: string): Promise<unknown>;
|
|
9
|
+
}
|
|
10
|
+
/** A plan, or the namespace Control answered with; the `fabrika` command validates and prints either. */
|
|
11
|
+
export type NamespaceCommandResult = {
|
|
12
|
+
readonly plan: ProviderNamespacePlan;
|
|
13
|
+
} | {
|
|
14
|
+
readonly namespace: unknown;
|
|
15
|
+
};
|
|
16
|
+
export interface NamespaceCommandContext {
|
|
17
|
+
readonly source: Readonly<Record<string, string | undefined>>;
|
|
18
|
+
/** Reads the Control origin and credential, and throws when either is missing: call it after every other input is checked. */
|
|
19
|
+
control(): NamespaceControl;
|
|
20
|
+
}
|
|
21
|
+
export interface NamespaceCli {
|
|
22
|
+
readonly usage: string;
|
|
23
|
+
/** `argv` is the command's own arguments, without the router's `--provider` and `--json`. */
|
|
24
|
+
run(subcommand: string, argv: readonly string[], context: NamespaceCommandContext): Promise<NamespaceCommandResult>;
|
|
25
|
+
}
|
|
26
|
+
export interface AppCli {
|
|
27
|
+
readonly provider: string;
|
|
28
|
+
readonly entryRuntime: AppEntryRuntime;
|
|
29
|
+
/** `fabrika app build`, after the command wrote a contract application's entry; `contract` says whether it did. */
|
|
30
|
+
build?(argv: readonly string[], context: {
|
|
31
|
+
readonly contract: boolean;
|
|
32
|
+
}): Promise<void>;
|
|
33
|
+
deploy?(argv: readonly string[]): Promise<void>;
|
|
34
|
+
/** The text `fabrika app register` hands Control: the application's manifest for one environment. */
|
|
35
|
+
registrationManifest?(options: {
|
|
36
|
+
readonly config: string;
|
|
37
|
+
readonly env: string;
|
|
38
|
+
}): Promise<string>;
|
|
39
|
+
readonly namespaces?: NamespaceCli;
|
|
40
|
+
}
|
|
41
|
+
export interface AppCliModule {
|
|
42
|
+
readonly appCli: AppCli;
|
|
43
|
+
}
|
|
44
|
+
export declare const isAppCli: (value: unknown) => value is AppCli;
|
|
45
|
+
/** `specifier` names the module in the error, so an operator knows which package to upgrade. */
|
|
46
|
+
export declare const appCliFromModule: (value: unknown, expectedProvider: string, specifier: string) => AppCli;
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { type ControlProvider, type ProviderDeployInput } from './control';
|
|
2
|
+
/** What the suite hands a fake cloud: `accepted` is called once the cloud has taken the deploy's operation. */
|
|
3
|
+
export interface ConformanceCloudHooks {
|
|
4
|
+
accepted(): void;
|
|
5
|
+
}
|
|
6
|
+
/** One provider over one fresh fake cloud. */
|
|
7
|
+
export interface ConformanceCloud {
|
|
8
|
+
readonly provider: ControlProvider;
|
|
9
|
+
/** A deploy the fake cloud accepts and lets succeed. Each case sets `dryRun`, `signal` and `events` itself. */
|
|
10
|
+
readonly input: Omit<ProviderDeployInput, 'dryRun' | 'signal' | 'events'>;
|
|
11
|
+
/** The credentials the provider holds itself (a cloud token, a signed URL); no event may carry one. */
|
|
12
|
+
readonly credentials: readonly string[];
|
|
13
|
+
/** Every request that changed the cloud: a write, a created resource, started work. A preview the cloud runs is none. */
|
|
14
|
+
mutations(): readonly string[];
|
|
15
|
+
/** Every request to stop or remove the deploy's work: a cancelled build or job, a deleted version. */
|
|
16
|
+
stops(): readonly string[];
|
|
17
|
+
}
|
|
18
|
+
export interface ControlProviderConformanceHarness {
|
|
19
|
+
/** Called once per case, and once per event in the lease-loss sweep. */
|
|
20
|
+
create(hooks: ConformanceCloudHooks): ConformanceCloud;
|
|
21
|
+
}
|
|
22
|
+
export declare function describeControlProviderConformance(name: string, harness: ControlProviderConformanceHarness): void;
|
package/types/src/control.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import type { AppSchema, ContractArtifact } from '@fabrika/auth-core';
|
|
1
|
+
import type { ApplicationObjects, AppSchema, ContractArtifact, ManagedEnvironment } from '@fabrika/auth-core';
|
|
2
|
+
import type { InstallationBrand } from '@fabrika/proxy-core/brand';
|
|
2
3
|
import type { JsonValue, ProviderEnvelope } from './json';
|
|
3
4
|
/** Events whose persistence and presentation belong to the control plane. */
|
|
4
5
|
export interface ProviderRunEvents {
|
|
@@ -13,8 +14,11 @@ export interface ProviderRunEvents {
|
|
|
13
14
|
*/
|
|
14
15
|
boundary(): Promise<void>;
|
|
15
16
|
}
|
|
16
|
-
/**
|
|
17
|
-
|
|
17
|
+
/**
|
|
18
|
+
* Complete platform-owned runtime state, parsed by Control (`parseManagedEnvironment`). A provider writes each entry as
|
|
19
|
+
* a secret when it is a `credential`, removes one whose value is null, and removes the stale ones `staleManagedVariables` names.
|
|
20
|
+
*/
|
|
21
|
+
export type ProviderManagedEnvironment = ManagedEnvironment;
|
|
18
22
|
/** Provider-neutral coordinates for obtaining one app revision. */
|
|
19
23
|
export interface ProviderSource {
|
|
20
24
|
readonly repoUrl: string;
|
|
@@ -35,8 +39,7 @@ export interface ProviderDeploymentNamespace {
|
|
|
35
39
|
readonly exclusiveAppId?: string;
|
|
36
40
|
readonly target: ProviderEnvelope;
|
|
37
41
|
}
|
|
38
|
-
|
|
39
|
-
export declare const FRAMEWORK_RELEASE_PATTERN: RegExp;
|
|
42
|
+
export { FRAMEWORK_RELEASE_PATTERN } from '@fabrika/auth-core';
|
|
40
43
|
/**
|
|
41
44
|
* The access Control approved for one application environment (ADR-0050): the contract the proxy enforces and the
|
|
42
45
|
* IAM vocabulary compiled from it. A provider publishes a contract application's endpoint table and reconciles its
|
|
@@ -57,6 +60,12 @@ export interface ProviderApprovedAccess {
|
|
|
57
60
|
* the framework minor it pins (ADR-0062). Its build checks with that release.
|
|
58
61
|
*/
|
|
59
62
|
readonly checker: string;
|
|
63
|
+
/**
|
|
64
|
+
* The `@fabrika/app` release the application's `bun.lock` pins (`FRAMEWORK_RELEASE_PATTERN`), which a release gate
|
|
65
|
+
* reads: `checker` is this platform's patch of that minor, newer than a prerelease pin. Absent in an access Control
|
|
66
|
+
* approved before it recorded the pin.
|
|
67
|
+
*/
|
|
68
|
+
readonly framework?: string;
|
|
60
69
|
}
|
|
61
70
|
/**
|
|
62
71
|
* `dev`: the environment follows a workspace through a platform-owned launcher, which its provider starts instead of the
|
|
@@ -78,12 +87,18 @@ export interface ProviderEnvironment {
|
|
|
78
87
|
* application's proxy manifest entry as `crossOrigins`.
|
|
79
88
|
*/
|
|
80
89
|
readonly crossOrigins?: readonly string[];
|
|
90
|
+
/**
|
|
91
|
+
* The origin of the environment's active Operations ingest DSN, never the DSN: a contract application's proxy admits
|
|
92
|
+
* it in `connect-src`. Control sets it on a deploy; absent while the environment has no active ingest.
|
|
93
|
+
*/
|
|
94
|
+
readonly operationsOrigin?: string;
|
|
81
95
|
readonly namespace?: ProviderDeploymentNamespace;
|
|
82
96
|
readonly target: ProviderEnvelope;
|
|
83
97
|
readonly artifact: ProviderEnvelope;
|
|
84
98
|
/**
|
|
85
99
|
* The environment's approved contract, from Control's `approvedSnapshot`. Absent when nothing is approved: then a
|
|
86
100
|
* provider publishes no endpoint table and reconciles no IAM schema, whatever the artifact claims (ADR-0050).
|
|
101
|
+
* Control refuses a non-dry deploy without it.
|
|
87
102
|
*/
|
|
88
103
|
readonly access?: ProviderApprovedAccess;
|
|
89
104
|
}
|
|
@@ -130,11 +145,10 @@ export interface ProviderDeployInput {
|
|
|
130
145
|
/** Platform-owned runtime configuration, separate from operator-managed application vars. */
|
|
131
146
|
readonly managedEnvironment: ProviderManagedEnvironment;
|
|
132
147
|
/**
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
-
* Absent when the app has no public origin at all, which leaves IAM's registry untouched.
|
|
148
|
+
* The object that serves the environment's ordinary traffic and the objects its ops channel reaches, as Control records
|
|
149
|
+
* them (ADR-0070 §9). A provider whose application runs in no object ignores it; absent, the provider's defaults.
|
|
136
150
|
*/
|
|
137
|
-
readonly
|
|
151
|
+
readonly applicationObjects?: ApplicationObjects;
|
|
138
152
|
readonly dryRun: boolean;
|
|
139
153
|
readonly sourceBinding?: ProviderSourceBinding;
|
|
140
154
|
/** Optional short-lived, run-scoped Operations artifact destination. */
|
|
@@ -150,7 +164,10 @@ export interface ProviderDeployInput {
|
|
|
150
164
|
readonly signal: AbortSignal;
|
|
151
165
|
readonly events: ProviderRunEvents;
|
|
152
166
|
}
|
|
153
|
-
/**
|
|
167
|
+
/**
|
|
168
|
+
* A terminal provider operation result. `succeeded` means the version is live: Control then writes the environment's
|
|
169
|
+
* approved IAM schema itself (ADR-0011), so a provider never calls IAM for an application.
|
|
170
|
+
*/
|
|
154
171
|
export interface ProviderTerminalOutcome {
|
|
155
172
|
readonly state: 'succeeded' | 'failed';
|
|
156
173
|
readonly exitCode?: number;
|
|
@@ -190,13 +207,9 @@ export interface ProviderRunReference {
|
|
|
190
207
|
}
|
|
191
208
|
export interface ProviderCancelInput extends ProviderRunReference {
|
|
192
209
|
readonly signal: AbortSignal;
|
|
193
|
-
/** See `ProviderDeployInput.returnOrigins`; a cancel that settles an activated deploy projects the same set. */
|
|
194
|
-
readonly returnOrigins?: readonly string[];
|
|
195
210
|
}
|
|
196
211
|
export interface ProviderReconcileInput extends ProviderRunReference {
|
|
197
212
|
readonly signal: AbortSignal;
|
|
198
|
-
/** See `ProviderDeployInput.returnOrigins`; a provider that settles a deploy here projects the same set. */
|
|
199
|
-
readonly returnOrigins?: readonly string[];
|
|
200
213
|
/** Append a line to the run's log. */
|
|
201
214
|
log?(line: string): Promise<void>;
|
|
202
215
|
}
|
|
@@ -285,6 +298,11 @@ export interface ProviderNamespaceMutationInput {
|
|
|
285
298
|
readonly namespace: ProviderDeploymentNamespace;
|
|
286
299
|
/** Every app environment assigned to the namespace, read under its lease. */
|
|
287
300
|
readonly members: readonly ProviderNamespaceMember[];
|
|
301
|
+
/**
|
|
302
|
+
* The installation's client logo for the pages the namespace's proxy answers with (ADR-0066), read from IAM for this
|
|
303
|
+
* mutation; absent or null shows the fabrika mark. A provider passes it only to a proxy that can parse it.
|
|
304
|
+
*/
|
|
305
|
+
readonly brand?: InstallationBrand | null;
|
|
288
306
|
readonly signal: AbortSignal;
|
|
289
307
|
readonly events: ProviderNamespaceEvents;
|
|
290
308
|
}
|
|
@@ -400,6 +418,17 @@ export interface ProviderNamespaceOperator {
|
|
|
400
418
|
plan(input: ProviderNamespacePlanInput): ProviderNamespacePlan;
|
|
401
419
|
present(namespace: ProviderDeploymentNamespace): ProviderNamespacePresentation;
|
|
402
420
|
}
|
|
421
|
+
/** The app-owned claims of one namespace whose resources Control is asked to confirm gone. */
|
|
422
|
+
export interface ProviderClaimedResourcesInput {
|
|
423
|
+
readonly namespace: ProviderDeploymentNamespace;
|
|
424
|
+
readonly resourceKeys: readonly string[];
|
|
425
|
+
readonly signal: AbortSignal;
|
|
426
|
+
}
|
|
427
|
+
/** What the provider observed for one claimed resource. */
|
|
428
|
+
export interface ProviderClaimedResource {
|
|
429
|
+
readonly resourceKey: string;
|
|
430
|
+
readonly exists: boolean;
|
|
431
|
+
}
|
|
403
432
|
/** Optional placement lifecycle owned by providers that use deployment namespaces. */
|
|
404
433
|
export interface ProviderNamespaceCapabilities {
|
|
405
434
|
normalize(namespace: ProviderDeploymentNamespace): ProviderDeploymentNamespace;
|
|
@@ -416,10 +445,19 @@ export interface ProviderNamespaceCapabilities {
|
|
|
416
445
|
reconcile(input: ProviderNamespaceMutationInput): Promise<ProviderDeploymentNamespace>;
|
|
417
446
|
/** Absent means the namespace has no entry point that follows its members. */
|
|
418
447
|
republish?(input: ProviderNamespaceRepublishInput): Promise<ProviderNamespaceRepublishResult>;
|
|
448
|
+
/**
|
|
449
|
+
* Read-only: whether each claimed resource still exists, one answer per key. Throws when it cannot tell, so Control
|
|
450
|
+
* releases a claim only over a resource the provider confirmed gone. Absent means no claim can be released.
|
|
451
|
+
*/
|
|
452
|
+
claimedResources?(input: ProviderClaimedResourcesInput): Promise<readonly ProviderClaimedResource[]>;
|
|
419
453
|
/** Absent means the provider changes no namespace in place. */
|
|
420
454
|
readonly updates?: ProviderNamespaceUpdates;
|
|
421
455
|
readonly operator?: ProviderNamespaceOperator;
|
|
422
456
|
}
|
|
457
|
+
export interface ProviderAuthoring {
|
|
458
|
+
/** The file NAMES (no `/`) that configure the provider's deploy; a workspace changes none of them, at any depth. */
|
|
459
|
+
readonly protectedFiles: readonly string[];
|
|
460
|
+
}
|
|
423
461
|
/** One call on the service of a `dev` environment, between its bootstrap runs. */
|
|
424
462
|
export interface ProviderDevEnvironmentInput {
|
|
425
463
|
readonly environment: ProviderEnvironment;
|
|
@@ -457,8 +495,29 @@ export interface ControlProvider {
|
|
|
457
495
|
reconcile?(input: ProviderReconcileInput): Promise<ProviderReconcileOutcome>;
|
|
458
496
|
readonly secrets?: ProviderManagedSecrets;
|
|
459
497
|
readonly namespaces?: ProviderNamespaceCapabilities;
|
|
498
|
+
/** MCP authoring (ADR-0049): an environment of this provider can be an authoring target. Absent means none can. */
|
|
499
|
+
readonly authoring?: ProviderAuthoring;
|
|
500
|
+
/**
|
|
501
|
+
* Every application environment gets `FABRIKA_PROXY_SECRET`, with or without a namespace proxy: the provider's own
|
|
502
|
+
* hop to the application carries it (Cloudflare's Worker to its Durable Object, ADR-0065). Absent means only a
|
|
503
|
+
* namespace proxy's environments get one.
|
|
504
|
+
*/
|
|
505
|
+
readonly applicationHopSecret?: true;
|
|
460
506
|
/** Absent means the provider runs no `dev` environment, and Control refuses one. */
|
|
461
507
|
readonly devEnvironments?: ProviderDevEnvironments;
|
|
508
|
+
/**
|
|
509
|
+
* Whether an environment at this approved access is served the ops channel through which Control reaches its object
|
|
510
|
+
* (ADR-0069), so its deploy gets `FABRIKA_OPS_KEY_DIGESTS`. The release gate is the provider's, so core keeps no
|
|
511
|
+
* release logic. Absent means no environment of this provider is.
|
|
512
|
+
*/
|
|
513
|
+
opsChannel?(access: ProviderApprovedAccess): boolean;
|
|
514
|
+
/**
|
|
515
|
+
* Whether the object at this approved access, served the ops channel, also holds the maintenance barrier (`state`,
|
|
516
|
+
* `migrate`) and serves Control's data operations: the daily backups, a deploy's migration phase and the side restore
|
|
517
|
+
* (ADR-0069 §3, ADR-0070). A release can serve the channel without them. Absent means no environment of this
|
|
518
|
+
* provider is.
|
|
519
|
+
*/
|
|
520
|
+
dataOperations?(access: ProviderApprovedAccess): boolean;
|
|
462
521
|
/** Absent means the provider deploys public sources only. */
|
|
463
522
|
readonly source?: ProviderSourceCapabilities;
|
|
464
523
|
/**
|