@sealant/api-contracts-next 0.40.0-next.770 → 0.40.0-next.772

package/dist/core-api/resource-domains.d.ts

@@ -26,9 +26,82 @@
  * keeps the member's row, with its version. One member reads at `GET …/members/:userId`, and the
  * list pages by user id: `limit` (100 unless named, at most 500) and the previous page's
  * `nextCursor` as `cursor`.
+ *
+ * A budget caps CPU (millicores), memory and storage (bytes): ceilings, not measurements, and
+ * zero allows nothing. Storage is one allowance for volumes, archived ones included, and the
+ * backups and snapshots that protect them. `ensureResourceDomain` may name a new domain's budget
+ * and never changes one: naming another gets `409`, carrying the domain and its revision.
+ * `setResourceDomainBudget` takes the `revision` it read: a change made since gets `409`, so a
+ * delayed update never overwrites a newer one, and it answers the budget it wrote. Changing a
+ * budget changes nothing the domain holds. The read is one snapshot. It reports, per dimension,
+ * `used` (confirmed to exist), `reserved` (admitted, not yet confirmed), the `limit` and a `warning`
+ * once both reach 80%, 95% or all of it; storage also reports its `archived` and `protection` bytes.
  */
 import { Schema } from "effect";
 import { HttpApiEndpoint, HttpApiGroup } from "effect/http-api";
+/**
+ * The dimensions a budget caps, defined once: the contract's schemas, the database's budget, the
+ * admission check and the SDK all take theirs from these keys. `freedBy` is what makes room in a
+ * dimension besides raising its limit.
+ */
+export declare const RESOURCE_DOMAIN_BUDGET_DIMENSIONS: {
+    readonly cpuMillicores: {
+        readonly name: "CPU";
+        readonly freedBy: "stop-objects";
+    };
+    readonly memoryBytes: {
+        readonly name: "memory";
+        readonly freedBy: "stop-objects";
+    };
+    readonly storageBytes: {
+        readonly name: "storage";
+        readonly freedBy: "purge-objects";
+    };
+};
+export type ResourceDomainBudgetDimension = keyof typeof RESOURCE_DOMAIN_BUDGET_DIMENSIONS;
+export declare const resourceDomainBudgetLimitsSchema: Schema.Struct<Record<"cpuMillicores" | "memoryBytes" | "storageBytes", Schema.Int>>;
+export type ResourceDomainBudgetLimits = typeof resourceDomainBudgetLimitsSchema.Type;
+/** The share of a limit at which the budget read starts to warn. */
+export declare const RESOURCE_DOMAIN_BUDGET_WARNINGS: {
+    readonly "80-percent": 80;
+    readonly "95-percent": 95;
+};
+declare const BudgetWarning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+export type ResourceDomainBudgetWarning = typeof BudgetWarning.Type;
+export declare const resourceDomainBudgetSchema: Schema.Struct<{
+    readonly revision: Schema.Int;
+    readonly storageBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        readonly archived: Schema.Int;
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        readonly protection: Schema.Int;
+    }>;
+    readonly cpuMillicores: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+    readonly memoryBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+}>;
+export type ResourceDomainBudgetWire = typeof resourceDomainBudgetSchema.Type;
+export declare const setResourceDomainBudgetRequestSchema: Schema.Struct<{
+    /** The revision this change replaces: the one the caller last read. */
+    readonly revision: Schema.Int;
+    readonly cpuMillicores: Schema.Int;
+    readonly memoryBytes: Schema.Int;
+    readonly storageBytes: Schema.Int;
+}>;
+export type SetResourceDomainBudgetRequest = typeof setResourceDomainBudgetRequestSchema.Type;
 export declare const resourceDomainSchema: Schema.Struct<{
     readonly resourceDomainId: Schema.String;
     readonly key: Schema.String;
@@ -37,6 +110,8 @@ export declare const resourceDomainSchema: Schema.Struct<{
 export type ResourceDomainWire = typeof resourceDomainSchema.Type;
 export declare const ensureResourceDomainRequestSchema: Schema.Struct<{
     readonly key: Schema.String;
+    /** The budget a new domain starts with; none starts it at zero. */
+    readonly budget: Schema.optional<Schema.Struct<Record<"cpuMillicores" | "memoryBytes" | "storageBytes", Schema.Int>>>;
 }>;
 export type EnsureResourceDomainRequest = typeof ensureResourceDomainRequestSchema.Type;
 export declare const ensureResourceDomainResponseSchema: Schema.Struct<{
@@ -116,6 +191,21 @@ declare const ResourceDomainMemberVersionConflictError_base: Schema.Class<Resour
  */
 export declare class ResourceDomainMemberVersionConflictError extends ResourceDomainMemberVersionConflictError_base {
 }
+declare const ResourceDomainBudgetDiffersError_base: Schema.Class<ResourceDomainBudgetDiffersError, Schema.TaggedStruct<"ResourceDomainBudgetDiffersError", {
+    readonly message: Schema.String;
+    readonly resourceDomainId: Schema.String;
+    readonly revision: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** The domain exists with another budget, at `revision`; nothing changed. */
+export declare class ResourceDomainBudgetDiffersError extends ResourceDomainBudgetDiffersError_base {
+}
+declare const ResourceDomainBudgetRevisionConflictError_base: Schema.Class<ResourceDomainBudgetRevisionConflictError, Schema.TaggedStruct<"ResourceDomainBudgetRevisionConflictError", {
+    readonly message: Schema.String;
+    readonly revision: Schema.Int;
+}>, import("effect/Cause").YieldableError>;
+/** `revision` is the current one. */
+export declare class ResourceDomainBudgetRevisionConflictError extends ResourceDomainBudgetRevisionConflictError_base {
+}
 declare const ResourceDomainInternalServerError_base: Schema.Class<ResourceDomainInternalServerError, Schema.TaggedStruct<"ResourceDomainInternalServerError", {
     readonly message: Schema.String;
 }>, import("effect/Cause").YieldableError>;
@@ -123,18 +213,46 @@ export declare class ResourceDomainInternalServerError extends ResourceDomainInt
 }
 export declare const ResourceDomainsGroup: HttpApiGroup.HttpApiGroup<"resourceDomains", HttpApiEndpoint.HttpApiEndpoint<"ensureResourceDomain", "POST", "/", never, never, Schema.toCodecJson<Schema.Struct<{
     readonly key: Schema.String;
+    /** The budget a new domain starts with; none starts it at zero. */
+    readonly budget: Schema.optional<Schema.Struct<Record<"cpuMillicores" | "memoryBytes" | "storageBytes", Schema.Int>>>;
 }>>, never, Schema.toCodecJson<Schema.Struct<{
     readonly resourceDomainId: Schema.String;
     readonly key: Schema.String;
     readonly createdAt: Schema.String;
     /** True when this call created the domain. */
     readonly created: Schema.Boolean;
-}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomain", "GET", "/:resourceDomainId", Schema.toCodecStringTree<Schema.Struct<{
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainBudgetDiffersError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomain", "GET", "/:resourceDomainId", Schema.toCodecStringTree<Schema.Struct<{
     readonly resourceDomainId: Schema.String;
 }>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
     readonly resourceDomainId: Schema.String;
     readonly key: Schema.String;
     readonly createdAt: Schema.String;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomainBudget", "GET", "/:resourceDomainId/budget", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, never, never, never, Schema.toCodecJson<Schema.Struct<{
+    readonly revision: Schema.Int;
+    readonly storageBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        readonly archived: Schema.Int;
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        readonly protection: Schema.Int;
+    }>;
+    readonly cpuMillicores: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+    readonly memoryBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
 }>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"getResourceDomainMember", "GET", "/:resourceDomainId/members/:userId", Schema.toCodecStringTree<Schema.Struct<{
     readonly resourceDomainId: Schema.String;
     readonly userId: Schema.String;
@@ -180,5 +298,37 @@ export declare const ResourceDomainsGroup: HttpApiGroup.HttpApiGroup<"resourceDo
     readonly state: Schema.Literals<readonly ["member", "revoked"]>;
     readonly version: Schema.Int;
     readonly updatedAt: Schema.String;
-}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberVersionConflictError | typeof ResourceDomainInternalServerError>, never, never>, false>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainPersonNotFoundError | typeof ResourceDomainMemberVersionConflictError | typeof ResourceDomainInternalServerError>, never, never> | HttpApiEndpoint.HttpApiEndpoint<"setResourceDomainBudget", "PUT", "/:resourceDomainId/budget", Schema.toCodecStringTree<Schema.Struct<{
+    readonly resourceDomainId: Schema.String;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    /** The revision this change replaces: the one the caller last read. */
+    readonly revision: Schema.Int;
+    readonly cpuMillicores: Schema.Int;
+    readonly memoryBytes: Schema.Int;
+    readonly storageBytes: Schema.Int;
+}>>, never, Schema.toCodecJson<Schema.Struct<{
+    readonly revision: Schema.Int;
+    readonly storageBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        readonly archived: Schema.Int;
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        readonly protection: Schema.Int;
+    }>;
+    readonly cpuMillicores: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+    readonly memoryBytes: Schema.Struct<{
+        readonly limit: Schema.Int;
+        readonly used: Schema.Int;
+        readonly reserved: Schema.Int;
+        readonly warning: Schema.Literals<readonly ["none", "80-percent", "95-percent", "full"]>;
+    }>;
+}>>, Schema.toCodecJson<typeof ResourceDomainForbiddenError | typeof ResourceDomainNotFoundError | typeof ResourceDomainBudgetRevisionConflictError | typeof ResourceDomainInternalServerError>, never, never>, false>;
 export {};

package/dist/core-api/resource-domains.js

@@ -26,9 +26,20 @@
  * keeps the member's row, with its version. One member reads at `GET …/members/:userId`, and the
  * list pages by user id: `limit` (100 unless named, at most 500) and the previous page's
  * `nextCursor` as `cursor`.
+ *
+ * A budget caps CPU (millicores), memory and storage (bytes): ceilings, not measurements, and
+ * zero allows nothing. Storage is one allowance for volumes, archived ones included, and the
+ * backups and snapshots that protect them. `ensureResourceDomain` may name a new domain's budget
+ * and never changes one: naming another gets `409`, carrying the domain and its revision.
+ * `setResourceDomainBudget` takes the `revision` it read: a change made since gets `409`, so a
+ * delayed update never overwrites a newer one, and it answers the budget it wrote. Changing a
+ * budget changes nothing the domain holds. The read is one snapshot. It reports, per dimension,
+ * `used` (confirmed to exist), `reserved` (admitted, not yet confirmed), the `limit` and a `warning`
+ * once both reach 80%, 95% or all of it; storage also reports its `archived` and `protection` bytes.
  */
 import { Schema } from "effect";
 import { HttpApi, HttpApiEndpoint, HttpApiGroup, OpenApi } from "effect/http-api";
+import * as Rec from "effect/Record";
 import { PersonId, RESOURCE_DOMAIN_ID_PREFIX } from "./person-id.js";
 const RESOURCE_DOMAIN_ID_PATTERN = new RegExp(`^${RESOURCE_DOMAIN_ID_PREFIX}[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`);
 const RESOURCE_DOMAIN_KEY_PATTERN = /^[a-z][a-z0-9-]{0,31}:[A-Za-z0-9._:/@+=-]{1,223}$/;
@@ -36,12 +47,54 @@ const ResourceDomainId = Schema.String.check(Schema.makeFilter((id) => RESOURCE_
 const ResourceDomainKey = Schema.String.check(Schema.makeFilter((key) => RESOURCE_DOMAIN_KEY_PATTERN.test(key)
     ? undefined
     : "must be <application>:<name>: a lower-case application name (letters, digits, '-'), a colon, then at most 223 letters, digits, '.', '_', ':', '/', '@', '+', '=' or '-'"));
+const Amount = Schema.Int.check(Schema.isBetween({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }));
+const BudgetRevision = Schema.Int.check(Schema.isBetween({ minimum: 1, maximum: Number.MAX_SAFE_INTEGER }));
+/**
+ * The dimensions a budget caps, defined once: the contract's schemas, the database's budget, the
+ * admission check and the SDK all take theirs from these keys. `freedBy` is what makes room in a
+ * dimension besides raising its limit.
+ */
+export const RESOURCE_DOMAIN_BUDGET_DIMENSIONS = {
+    cpuMillicores: { name: "CPU", freedBy: "stop-objects" },
+    memoryBytes: { name: "memory", freedBy: "stop-objects" },
+    storageBytes: { name: "storage", freedBy: "purge-objects" },
+};
+export const resourceDomainBudgetLimitsSchema = Schema.Struct(Rec.map(RESOURCE_DOMAIN_BUDGET_DIMENSIONS, () => Amount));
+/** The share of a limit at which the budget read starts to warn. */
+export const RESOURCE_DOMAIN_BUDGET_WARNINGS = { "80-percent": 80, "95-percent": 95 };
+const BudgetWarning = Schema.Literals(["none", "80-percent", "95-percent", "full"]);
+const budgetDimensionSchema = Schema.Struct({
+    limit: Amount,
+    used: Amount,
+    reserved: Amount,
+    warning: BudgetWarning,
+});
+export const resourceDomainBudgetSchema = Schema.Struct({
+    revision: BudgetRevision,
+    ...Rec.map(RESOURCE_DOMAIN_BUDGET_DIMENSIONS, () => budgetDimensionSchema),
+    storageBytes: Schema.Struct({
+        ...budgetDimensionSchema.fields,
+        /** Archived volumes' data bytes, part of `used`: kept until a person purges them. */
+        archived: Amount,
+        /** Bytes that backups and snapshots hold, not a volume's unused reserve for them. */
+        protection: Amount,
+    }),
+});
+export const setResourceDomainBudgetRequestSchema = Schema.Struct({
+    ...resourceDomainBudgetLimitsSchema.fields,
+    /** The revision this change replaces: the one the caller last read. */
+    revision: BudgetRevision,
+});
 export const resourceDomainSchema = Schema.Struct({
     resourceDomainId: ResourceDomainId,
     key: ResourceDomainKey,
     createdAt: Schema.String,
 });
-export const ensureResourceDomainRequestSchema = Schema.Struct({ key: ResourceDomainKey });
+export const ensureResourceDomainRequestSchema = Schema.Struct({
+    key: ResourceDomainKey,
+    /** The budget a new domain starts with; none starts it at zero. */
+    budget: Schema.optional(resourceDomainBudgetLimitsSchema),
+});
 export const ensureResourceDomainResponseSchema = Schema.Struct({
     ...resourceDomainSchema.fields,
     /** True when this call created the domain. */
@@ -90,6 +143,12 @@ export class ResourceDomainMemberVersionConflictError extends Schema.TaggedError
     current: Schema.Struct({ state: MemberState, version: MemberVersion }),
 }, { httpApiStatus: 409 }) {
 }
+/** The domain exists with another budget, at `revision`; nothing changed. */
+export class ResourceDomainBudgetDiffersError extends Schema.TaggedError()("ResourceDomainBudgetDiffersError", { message: Schema.String, resourceDomainId: ResourceDomainId, revision: BudgetRevision }, { httpApiStatus: 409 }) {
+}
+/** `revision` is the current one. */
+export class ResourceDomainBudgetRevisionConflictError extends Schema.TaggedError()("ResourceDomainBudgetRevisionConflictError", { message: Schema.String, revision: BudgetRevision }, { httpApiStatus: 409 }) {
+}
 export class ResourceDomainInternalServerError extends Schema.TaggedError()("ResourceDomainInternalServerError", { message: Schema.String }, { httpApiStatus: 500 }) {
 }
 const memberParams = Schema.Struct({ resourceDomainId: ResourceDomainId, userId: PersonId });
@@ -104,7 +163,11 @@ export const ResourceDomainsGroup = HttpApiGroup.make("resourceDomains")
     .add(HttpApiEndpoint.post("ensureResourceDomain", "/", {
     payload: ensureResourceDomainRequestSchema,
     success: ensureResourceDomainResponseSchema,
-    error: [ResourceDomainForbiddenError, ResourceDomainInternalServerError],
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainBudgetDiffersError,
+        ResourceDomainInternalServerError,
+    ],
 }))
     .add(HttpApiEndpoint.get("getResourceDomain", "/:resourceDomainId", {
     params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
@@ -147,6 +210,26 @@ export const ResourceDomainsGroup = HttpApiGroup.make("resourceDomains")
         ResourceDomainNotFoundError,
         ResourceDomainInternalServerError,
     ],
+}))
+    .add(HttpApiEndpoint.get("getResourceDomainBudget", "/:resourceDomainId/budget", {
+    params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
+    success: resourceDomainBudgetSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainInternalServerError,
+    ],
+}))
+    .add(HttpApiEndpoint.put("setResourceDomainBudget", "/:resourceDomainId/budget", {
+    params: Schema.Struct({ resourceDomainId: ResourceDomainId }),
+    payload: setResourceDomainBudgetRequestSchema,
+    success: resourceDomainBudgetSchema,
+    error: [
+        ResourceDomainForbiddenError,
+        ResourceDomainNotFoundError,
+        ResourceDomainBudgetRevisionConflictError,
+        ResourceDomainInternalServerError,
+    ],
 }))
     .annotate(HttpApi.PayloadParseOptions, { onExcessProperty: "error" })
     .annotate(OpenApi.Description, "Owners that are projects, not people: they never hold a login or a provider credential.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sealant/api-contracts-next",
-  "version": "0.40.0-next.770",
+  "version": "0.40.0-next.772",
   "description": "Contract-first HTTP API definitions for Sealant services",
   "license": "Apache-2.0",
   "repository": {
@@ -36,7 +36,7 @@
   "peerDependencies": {
     "effect": "^4.0.5"
   },
-  "gitHead": "1e8b4f1153f5107504649c863c305cd31f424d58",
+  "gitHead": "722ef7c7d08581db5c9c4de770d5630329063a97",
   "publishConfig": {
     "access": "public"
   }