@madewithremy/admin 0.1.64 → 0.1.66

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.
@@ -1,7 +1,7 @@
1
1
  /**
2
- * Provisioned-infrastructure operations: lease, park, resume and delete
2
+ * Provisioned-infrastructure operations: lease, hibernate, resume and delete
3
3
  * dedicated resources (retrieval capacity for data sources, and database
4
- * servers for databases past the shared pool's limit).
4
+ * servers for databases past the shared servers' limit).
5
5
  *
6
6
  * Ops are pure (ctx, params) → typed result. The CLI skin in
7
7
  * commands/infra.ts owns flag parsing, progress printing and exit codes.
@@ -18,6 +18,10 @@ export interface ListParams {
18
18
  * The app's dedicated resources plus the offerings it can provision, with
19
19
  * their hourly and monthly prices.
20
20
  *
21
+ * In a method, needs the `infra.view` admin permission, which reads the list,
22
+ * each resource and its narration; the changes (provision, hibernate, resume,
23
+ * resize, destroy, rename) are a person's only.
24
+ *
21
25
  * @example
22
26
  * const { resources, offerings } = await admin.infra.list();
23
27
  */
@@ -28,8 +32,11 @@ export interface GetParams {
28
32
  }
29
33
  /**
30
34
  * One resource with its state timeline and the data sources placed on it.
35
+ * In a method, needs `infra.view`.
31
36
  *
32
- * @throws AdminApiError `resource_not_found` (404).
37
+ * @throws AdminApiError `resource_not_found` (404);
38
+ * `admin_permission_required:infra.view` (403) — a method that doesn't
39
+ * declare it.
33
40
  */
34
41
  export declare function get(ctx: AdminContext, params: GetParams): Promise<InfraGetResult>;
35
42
  export interface LogsParams {
@@ -44,9 +51,11 @@ export interface LogsParams {
44
51
  * The platform's narration of a resource, oldest first: the steps a
45
52
  * transition went through, failed attempts, and failures with the pod's
46
53
  * events and a warnings-and-errors tail of the instance log. Not the
47
- * instance's own stdout.
54
+ * instance's own stdout. In a method, needs `infra.view`.
48
55
  *
49
- * @throws AdminApiError `resource_not_found` (404).
56
+ * @throws AdminApiError `resource_not_found` (404);
57
+ * `admin_permission_required:infra.view` (403) — a method that doesn't
58
+ * declare it.
50
59
  */
51
60
  export declare function logs(ctx: AdminContext, params: LogsParams): Promise<InfraLogsResult>;
52
61
  export interface ProvisionParams {
@@ -74,9 +83,9 @@ export interface ResourceIdParams {
74
83
  id: string;
75
84
  }
76
85
  /**
77
- * Park an active resource. Data is kept and billing stops until it resumes.
78
- * Retrieval: searches on its data sources return `capacity_hibernating` while
79
- * it parks and `capacity_hibernated` once parked. A database server: every
86
+ * Hibernate an active resource. Data is kept and billing stops until it
87
+ * resumes. Retrieval: searches on its data sources return
88
+ * `capacity_hibernating` on the way and `capacity_hibernated` once there. A database server: every
80
89
  * database is backed up first, and its queries answer `database_lease_parked`
81
90
  * until it resumes.
82
91
  *
@@ -94,7 +103,7 @@ export declare function resume(ctx: AdminContext, params: ResourceIdParams): Pro
94
103
  * Retrieval: refused while any data source is placed on it; move those to
95
104
  * shared capacity (`admin.dataSources.move({ placement: 'shared' })`, data
96
105
  * intact) or delete them first. A database server: its databases go back to
97
- * the shared pool, so it's refused while any is too large for the pool to
106
+ * the shared servers, so it's refused while any is too large for them to
98
107
  * take back.
99
108
  *
100
109
  * @throws AdminApiError `resource_not_found` (404),
@@ -109,9 +118,9 @@ export interface ResizeParams {
109
118
  }
110
119
  /**
111
120
  * Change a resource's size, keeping its data. Either kind passes through
112
- * `hibernated`: the platform parks the resource, swaps its spec and brings it
113
- * back up. A resource that is already hibernated swaps in place and stays
114
- * parked. Growing is gated on a month of credits at the new rate like a
121
+ * `hibernated`: the platform hibernates the resource, swaps its spec and
122
+ * brings it back up. A resource that is already hibernated swaps in place and
123
+ * stays hibernated. Growing is gated on a month of credits at the new rate like a
115
124
  * provision; shrinking is refused below what the resource holds. The response
116
125
  * carries `resizingTo` until the swap has happened; `waitForPhase` with
117
126
  * `until: (r) => r.resizingTo === null` blocks on the whole thing.
@@ -163,7 +172,11 @@ export type WaitForPhaseResult = {
163
172
  };
164
173
  /**
165
174
  * Poll a resource until it reaches one of `phases`, fails, or the timeout
166
- * elapses. A `failed` phase returns immediately with the platform's error.
175
+ * elapses. A failure the platform is still retrying is waited through
176
+ * (`retrying`): a resume or hibernate asked of a failed resource reads
177
+ * `failed` until the platform takes its first step, and a transition that
178
+ * timed out once is tried again. One it has given up on returns with the
179
+ * platform's error.
167
180
  *
168
181
  * @example
169
182
  * const result = await admin.infra.waitForPhase({ id, phases: ['active'] });
package/dist/prod.js CHANGED
@@ -9608,7 +9608,7 @@ async function waitForPhase(ctx, params) {
9608
9608
  const arrived = (resource2) => wanted.has(resource2.phase) && (params.until?.(resource2) ?? true);
9609
9609
  const outcome = await pollUntil(
9610
9610
  async () => (await get11(ctx, { id: params.id })).resource,
9611
- (resource2) => arrived(resource2) || resource2.phase === "failed",
9611
+ (resource2) => arrived(resource2) || resource2.phase === "failed" && !resource2.retrying,
9612
9612
  {
9613
9613
  timeoutMs,
9614
9614
  pollMs: POLL_MS5,
@@ -9715,10 +9715,9 @@ async function waitAndReport2(ctx, a, id, phases, summary4, until) {
9715
9715
  });
9716
9716
  printJson({ ...summary4, ...result });
9717
9717
  if (result.status === "failed") {
9718
- throw new CliError(result.error, EXIT.buildFailed);
9719
- }
9720
- if (result.status === "timeout") {
9721
- throw new CliError(result.error, EXIT.timeout);
9718
+ process.exitCode = EXIT.buildFailed;
9719
+ } else if (result.status === "timeout") {
9720
+ process.exitCode = EXIT.timeout;
9722
9721
  }
9723
9722
  }
9724
9723
  async function infraList(ctx, a) {
@@ -9761,8 +9760,7 @@ function pricingOf(resource) {
9761
9760
  return {
9762
9761
  offering: offering.id,
9763
9762
  activeMonthlyDollars: offering.monthlyPriceDollars,
9764
- hibernatedMonthlyDollars: offering.hibernatedMonthlyPriceDollars,
9765
- note: "Bills hourly from activation. A month's credits were verified before the lease was accepted."
9763
+ note: "Bills hourly while active, and nothing while hibernated. A month's credits were verified before the lease was accepted."
9766
9764
  };
9767
9765
  }
9768
9766
  async function infraProvision(ctx, a) {
@@ -9823,10 +9821,8 @@ async function infraRename(ctx, a) {
9823
9821
  }
9824
9822
  async function infraResize(ctx, a) {
9825
9823
  const id = a.required("id");
9826
- const { resource } = await resize(ctx, {
9827
- id,
9828
- offeringId: a.str("offering")
9829
- });
9824
+ const offeringId = a.str("offering");
9825
+ const { resource } = await resize(ctx, { id, offeringId });
9830
9826
  const pricing = pricingOf({
9831
9827
  ...resource,
9832
9828
  offering: resource.resizingTo ?? resource.offering
@@ -9835,7 +9831,7 @@ async function infraResize(ctx, a) {
9835
9831
  printJson({
9836
9832
  resource,
9837
9833
  pricing,
9838
- note: "Resizing; searches on its sources pause while it is parked and restored. Poll `infra get <id>` or re-run with --wait."
9834
+ note: `Resizing; ${resource.kind === "database" ? "the app's queries pause" : "searches on its sources pause"} while it is hibernated and restored. Poll \`infra get <id>\` or re-run with --wait.`
9839
9835
  });
9840
9836
  return;
9841
9837
  }
@@ -9845,7 +9841,9 @@ async function infraResize(ctx, a) {
9845
9841
  id,
9846
9842
  [resource.phase],
9847
9843
  { action: "resize", pricing },
9848
- (r) => r.resizingTo === null
9844
+ // On the size asked for, not only settled: a resize the platform gave up
9845
+ // on also clears, back at the old size.
9846
+ (r) => r.resizingTo === null && r.offeringId === offeringId
9849
9847
  );
9850
9848
  }
9851
9849
  var infraHandlers = {
@@ -9861,9 +9859,9 @@ var infraHandlers = {
9861
9859
  };
9862
9860
  var infraHelp = `remy-admin infra \u2014 Dedicated infrastructure your app leases from the platform.
9863
9861
 
9864
- Two kinds, each isolated from the shared pool: \`retrieval\`, the app's own
9865
- vector-store capacity for data sources, and \`database\`, a database server of
9866
- the app's own for databases past the shared pool's limit. Sizes and prices come
9862
+ Two kinds, each the app's own: \`retrieval\`, vector-store capacity for its
9863
+ data sources in place of the shared pool, and \`database\`, a database server
9864
+ for databases past the shared servers' limit. Sizes and prices come
9867
9865
  from the platform catalog (\`infra list\` prints them, by kind); nothing is
9868
9866
  priced client-side.
9869
9867
 
@@ -9881,11 +9879,11 @@ Subcommands:
9881
9879
  logs The platform's log for a resource (--follow to keep reading)
9882
9880
  provision Lease a new resource (needs a month's credits; prints the price;
9883
9881
  one database server an app)
9884
- hibernate Park it: data kept, its searches or queries paused, the charge stops
9882
+ hibernate Hibernate it: data kept, its searches or queries paused, the charge stops
9885
9883
  resume Bring a hibernated resource back (needs a month's credits)
9886
9884
  resize Change its size, data intact (passes through hibernated)
9887
9885
  destroy Delete it (retrieval: refused while data sources are placed on it;
9888
- database: while a database is too large for the shared pool)
9886
+ database: while a database is too large for the shared servers)
9889
9887
  rename Change the display name
9890
9888
 
9891
9889
  Usage:
@@ -9912,7 +9910,7 @@ Placing a data source on a resource:
9912
9910
  leaves a resource you mean to destroy. See \`datasources --help\`.
9913
9911
 
9914
9912
  Searches on a source whose resource is not active fail with
9915
- capacity_<phase>: capacity_hibernated once parked, capacity_hibernating /
9913
+ capacity_<phase>: capacity_hibernated once hibernated, capacity_hibernating /
9916
9914
  capacity_resuming while it moves. Once active, a source whose index is being
9917
9915
  rebuilt from durable storage (after a resume, a resize or a lost node)
9918
9916
  answers index_warming with the rebuild's progress and ETA until it lands;
@@ -9920,11 +9918,11 @@ Placing a data source on a resource:
9920
9918
  progress. The messages are written for the app's end user; the stable code
9921
9919
  is what to act on.
9922
9920
 
9923
- Dedicated databases:
9921
+ Database servers:
9924
9922
  A database server takes the app's live databases as it first becomes active,
9925
- each one let go by the shared pool and served there from then on, under the
9926
- size's own limit (\`maxDatabaseGiB\` on the offering) in place of the shared
9927
- pool's. A release the app deploys keeps its databases there. Nothing in the
9923
+ each one let go by the shared servers and served there from then on, under
9924
+ the size's own limit (\`maxDatabaseGiB\` on the offering, in GB) in place of
9925
+ the shared servers'. A release the app deploys keeps its databases there. Nothing in the
9928
9926
  app changes: the same queries, routed to it by the platform. An app has one:
9929
9927
  a second is refused with database_server_exists (422); resize the one it has.
9930
9928
 
@@ -10444,7 +10442,8 @@ allow. analytics.view, usage.view, requests.view (requests, crashes),
10444
10442
  agent.view, tasks.view, voice.view|manage, users.view|manage (live runs only),
10445
10443
  settings.manage, email.view|manage, domains.manage (custom domains, the
10446
10444
  subdomain), issues.view|manage, datasources.manage, cron.view|manage,
10447
- releases.view. A .manage includes its .view. A call the method doesn't hold is
10445
+ releases.view, infra.view (infra list, get, logs). A .manage includes its
10446
+ .view. A call the method doesn't hold is
10448
10447
  admin_permission_required:<name>; another app is app_credential_wrong_app and
10449
10448
  needs a key. The full list and rules are createAdminClient's docs.`;
10450
10449
  var GROUPS = [
@@ -23,7 +23,7 @@ export type InfraHealth = 'ready' | 'not-ready' | 'missing' | 'rebuilding'
23
23
  /**
24
24
  * What a resource is: `retrieval`, vector-store capacity of the app's own for
25
25
  * its data sources, or `database`, a database server of the app's own for
26
- * databases past the shared pool's limit.
26
+ * databases past the shared servers' limit.
27
27
  */
28
28
  export type InfraKind = 'retrieval' | 'database';
29
29
  /** What a retrieval size holds. */
@@ -53,20 +53,15 @@ export interface InfraOffering {
53
53
  /** User-facing capacity, e.g. "Up to ~34M chunks at 2560 dimensions (~48M at 1024, ~26M at 4096)". */
54
54
  description: string;
55
55
  hourlyPriceDollars: number;
56
- /** Hourly × 730. */
57
- monthlyPriceDollars: number;
58
56
  /**
59
- * Zero: a hibernated resource holds nothing. A retrieval resource's sources'
60
- * documents stay in the platform's own store; a database server's databases
61
- * are backed up there as it parks.
57
+ * Hourly × 730. Only an active resource bills: hibernated, it holds nothing
58
+ * and costs nothing. A retrieval resource's sources' documents stay in the
59
+ * platform's own store, and a database server's databases are backed up
60
+ * there as it hibernates.
62
61
  */
63
- hibernatedHourlyPriceDollars: number;
64
- hibernatedMonthlyPriceDollars: number;
62
+ monthlyPriceDollars: number;
65
63
  /** What the size holds, by kind. */
66
64
  capacity: InfraRetrievalCapacity | InfraDatabaseCapacity;
67
- capabilities: {
68
- hibernate: boolean;
69
- };
70
65
  retired: boolean;
71
66
  }
72
67
  export interface InfraResource {
@@ -81,6 +76,13 @@ export interface InfraResource {
81
76
  /** Data sources placed on this resource (retrieval). Destroy is refused while > 0. */
82
77
  attachedSources: number;
83
78
  lastError: string | null;
79
+ /** A failed resource: the phase it failed in. Null otherwise. */
80
+ failedIn: InfraPhase | null;
81
+ /**
82
+ * A failed resource: whether the platform is still retrying it. False once
83
+ * it waits to be resumed, hibernated or destroyed.
84
+ */
85
+ retrying: boolean;
84
86
  /** Null until the instance exists (requested, hibernated, destroyed). */
85
87
  health: InfraHealth | null;
86
88
  /**
@@ -142,11 +144,10 @@ export interface InfraResource {
142
144
  resizingTo: InfraOffering | null;
143
145
  /**
144
146
  * What this resource has actually been charged, from the ledger's own
145
- * writes, with the hours at each rate beside it. Rates are on `offering`.
147
+ * writes, with the hours it was active for. Its rate is on `offering`.
146
148
  */
147
149
  billing: {
148
150
  activeHours: number;
149
- hibernatedHours: number;
150
151
  billedDollars: number;
151
152
  lastBilledAt: string | null;
152
153
  };
@@ -157,7 +158,12 @@ export interface InfraResource {
157
158
  createdAt: string;
158
159
  updatedAt: string;
159
160
  }
160
- /** One of a database server's databases, as its pod last reported it. */
161
+ /**
162
+ * One of a database server's databases, as its pod last reported it. Every
163
+ * database on the server is listed; one the server hasn't opened yet (it
164
+ * downloads on its first query after a provision or a resume) has null sizes
165
+ * and no backup time.
166
+ */
161
167
  export interface InfraLeasedDatabase {
162
168
  databaseId: string;
163
169
  name: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@madewithremy/admin",
3
- "version": "0.1.64",
3
+ "version": "0.1.66",
4
4
  "description": "Admin SDK + CLI for managing production Remy apps",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",