@squidcloud/backend 1.0.476 → 1.0.478
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/dist/backend/src/actions.d.ts +1 -1
- package/dist/backend/src/index.d.ts +1 -0
- package/dist/backend/src/squid.service.d.ts +6 -0
- package/dist/backend/src/workspace-client.d.ts +88 -0
- package/dist/cjs/index.js +1 -1
- package/dist/esm/index.js +1 -1
- package/dist/internal-common/src/public-types-backend/mutation.public-context.d.ts +17 -4
- package/dist/internal-common/src/public-types-backend/native-query.public-context.d.ts +5 -2
- package/dist/internal-common/src/public-types-backend/query.public-context.d.ts +5 -2
- package/package.json +2 -2
|
@@ -141,7 +141,7 @@ export declare function onQueueMessage<T = unknown>(topicName: TopicName, integr
|
|
|
141
141
|
/**
|
|
142
142
|
* Decorator that marks a function as a handler for an emitted event of the given `type`.
|
|
143
143
|
*
|
|
144
|
-
* Events are emitted with
|
|
144
|
+
* Events are emitted with `squid.events().emit(...)` and delivered over core's internal event
|
|
145
145
|
* stream, so multiple subscribers may handle the same event type. The handler receives the emitted
|
|
146
146
|
* event (`{ id, type, payload }`).
|
|
147
147
|
*
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { AiStatusMessage, AuthWithApiKey, AuthWithBearer, ClientId, RunContext, SecretKey, SecretValue, Squid, SquidRegion } from '@squidcloud/client';
|
|
2
2
|
import { SquidFile } from '../../internal-common/src/public-types-backend/bundle-api.public-types';
|
|
3
3
|
import { TenantModuleId } from '../../internal-common/src/public-types-backend/bundle-data.public-types';
|
|
4
|
+
import { WorkspaceClient } from './workspace-client';
|
|
4
5
|
/**
|
|
5
6
|
* A base class for all the different types of Squid backend services. This class serves as a container
|
|
6
7
|
* for the various methods implemented in the backend in order to customize the Squid backend for an application.
|
|
@@ -34,6 +35,11 @@ export declare class SquidService {
|
|
|
34
35
|
* @returns the assets directory for your application.
|
|
35
36
|
*/
|
|
36
37
|
get assetsDirectory(): string;
|
|
38
|
+
/**
|
|
39
|
+
* Experimental. Backend-only API for a scratch directory ("workspace") synced across pod replicas via
|
|
40
|
+
* the shared workspace server — not the tenant's shared storage. See {@link WorkspaceClient}.
|
|
41
|
+
*/
|
|
42
|
+
get workspace(): WorkspaceClient;
|
|
37
43
|
/**
|
|
38
44
|
* Returns the API key used by the backend for your application.
|
|
39
45
|
*/
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
/** Metadata for a workspace. May gain additional fields over time — treat as extensible, not exhaustive. */
|
|
2
|
+
export interface WorkspaceMetadata {
|
|
3
|
+
/** The workspace id, generated by `create` when none is given. */
|
|
4
|
+
id: string;
|
|
5
|
+
/** Absolute path of the workspace directory on this pod's local disk. */
|
|
6
|
+
path: string;
|
|
7
|
+
}
|
|
8
|
+
/**
|
|
9
|
+
* Returns whether the shared workspace server is configured on this pod. Callers that want to degrade
|
|
10
|
+
* gracefully (treat a shared workspace as best-effort/ephemeral rather than fail) should check this
|
|
11
|
+
* before calling `WorkspaceClient` methods, which throw when it is not configured.
|
|
12
|
+
*/
|
|
13
|
+
export declare function isWorkspaceServerConfigured(): boolean;
|
|
14
|
+
/**
|
|
15
|
+
* Experimental, backend-only API for a scratch directory ("workspace") that survives across `ask()` calls
|
|
16
|
+
* and pod replicas. The directory lives on this pod's local disk for fast reads/writes; `create` and
|
|
17
|
+
* `push` are the only points that talk to the shared workspace server (rsync-over-ssh), so a
|
|
18
|
+
* workspace can move between pods without every file access paying network latency.
|
|
19
|
+
*
|
|
20
|
+
* Isolation is enforced server-side by a short-lived, per-workspace certificate: core signs it with the
|
|
21
|
+
* systemwide workspace CA and embeds an `rrsync` forced command scoped to this one workspace directory, so
|
|
22
|
+
* this client never expresses or needs to know any other path, and no long-lived key is ever held.
|
|
23
|
+
*
|
|
24
|
+
* This API may change or be removed without notice.
|
|
25
|
+
*/
|
|
26
|
+
export declare class WorkspaceClient {
|
|
27
|
+
private readonly lp;
|
|
28
|
+
/**
|
|
29
|
+
* Memoised so this pod's ephemeral keypair is generated exactly once, not per operation and not racily by
|
|
30
|
+
* two concurrent operations (a second `ssh-keygen` on the same path would hit an interactive overwrite
|
|
31
|
+
* prompt). Reusing one keypair across all workspaces/apps is safe: a keypair authorizes nothing on its own
|
|
32
|
+
* — every connection is gated by a fresh, per-workspace certificate.
|
|
33
|
+
*/
|
|
34
|
+
private podKeypairReady?;
|
|
35
|
+
/**
|
|
36
|
+
* Ensures the workspace directory exists on this pod and reflects the latest push, generating a
|
|
37
|
+
* new workspace id when none is given. Safe to call repeatedly: pulls from the workspace server only
|
|
38
|
+
* when there is something to pull, and is a no-op for a brand-new, never-pushed workspace.
|
|
39
|
+
*/
|
|
40
|
+
create(id?: string): Promise<WorkspaceMetadata>;
|
|
41
|
+
/** Syncs the current state of the workspace directory to the workspace server as the new authoritative state. */
|
|
42
|
+
push(id: string): Promise<WorkspaceMetadata>;
|
|
43
|
+
/**
|
|
44
|
+
* Deletes the workspace directory on this pod and clears its contents on the workspace server. Only
|
|
45
|
+
* the local copy on the pod this is called from is removed; copies left on other pod replicas by an
|
|
46
|
+
* earlier `create` are reclaimed by their own pod lifecycle (restart/reschedule), not by this call.
|
|
47
|
+
*/
|
|
48
|
+
delete(id: string): Promise<void>;
|
|
49
|
+
private buildMetadata;
|
|
50
|
+
/**
|
|
51
|
+
* Pulls the workspace server's copy into `dir`, replacing its content (`--delete`) so a file removed
|
|
52
|
+
* remotely by another pod's push doesn't linger locally and get resurrected by a later push.
|
|
53
|
+
* Tolerates there being nothing to pull yet.
|
|
54
|
+
*/
|
|
55
|
+
private pull;
|
|
56
|
+
/** Pushes `dir` to the workspace server as the new authoritative state. */
|
|
57
|
+
private pushDir;
|
|
58
|
+
/** Mirrors an empty local directory onto the server to clear its content. */
|
|
59
|
+
private rsyncEmptyTo;
|
|
60
|
+
/**
|
|
61
|
+
* Runs rsync against the workspace server for `workspaceId`, fetching a fresh, short-lived certificate
|
|
62
|
+
* scoped to that workspace first and cleaning it up afterwards. The certificate (not the key) is what
|
|
63
|
+
* expires, so it is re-fetched per operation.
|
|
64
|
+
*/
|
|
65
|
+
private rsync;
|
|
66
|
+
/**
|
|
67
|
+
* Ensures this pod's ephemeral keypair exists on disk, generating it exactly once. The keypair is a bare
|
|
68
|
+
* identity holder reused for the pod's lifetime; it grants no access without a current certificate.
|
|
69
|
+
*/
|
|
70
|
+
private ensurePodKeypair;
|
|
71
|
+
private generatePodKeypair;
|
|
72
|
+
/** Fetches a short-lived certificate for `workspaceId` from core and writes it to `certPath`. */
|
|
73
|
+
private issueCert;
|
|
74
|
+
private fileExists;
|
|
75
|
+
/**
|
|
76
|
+
* The rsync remote endpoint. The path is `.` (the root of the restricted directory), not the workspace
|
|
77
|
+
* id: the certificate's forced `rrsync` command already scopes the connection to this workspace's own
|
|
78
|
+
* directory server-side, and rrsync resolves the requested path relative to that restricted root.
|
|
79
|
+
*/
|
|
80
|
+
private remoteTarget;
|
|
81
|
+
/** Returns true when `e` is rsync's "partial transfer" exit, caused by the remote path not existing yet. */
|
|
82
|
+
private isMissingRemoteError;
|
|
83
|
+
private sshHost;
|
|
84
|
+
private sshPort;
|
|
85
|
+
private sshUser;
|
|
86
|
+
private sshKeyPath;
|
|
87
|
+
private getEnv;
|
|
88
|
+
}
|