@hivemagnus/magnus-contracts 1.1.2 → 1.1.3

package/dist/release.d.ts

@@ -48,11 +48,11 @@ export declare const migrationImpactSchema: z.ZodEnum<{
 }>;
 export declare const releaseMigrationSchema: z.ZodObject<{
     name: z.ZodString;
-    impact: z.ZodEnum<{
+    impact: z.ZodCatch<z.ZodEnum<{
         fast: "fast";
         slow: "slow";
         "one-way": "one-way";
-    }>;
+    }>>;
     note: z.ZodDefault<z.ZodString>;
 }, z.core.$strip>;
 export declare const releaseManifestSchema: z.ZodObject<{
@@ -95,11 +95,11 @@ export declare const releaseManifestSchema: z.ZodObject<{
     }, z.core.$strip>>>;
     migrations: z.ZodDefault<z.ZodArray<z.ZodObject<{
         name: z.ZodString;
-        impact: z.ZodEnum<{
+        impact: z.ZodCatch<z.ZodEnum<{
             fast: "fast";
             slow: "slow";
             "one-way": "one-way";
-        }>;
+        }>>;
         note: z.ZodDefault<z.ZodString>;
     }, z.core.$strip>>>;
     agent: z.ZodObject<{
@@ -108,6 +108,7 @@ export declare const releaseManifestSchema: z.ZodObject<{
     }, z.core.$strip>;
     summary: z.ZodDefault<z.ZodString>;
     notesUrl: z.ZodOptional<z.ZodString>;
+    allowScripts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodBoolean>>;
 }, z.core.$strip>;
 export type ReleaseManifest = z.infer<typeof releaseManifestSchema>;
 export type ReleaseEnvChange = z.infer<typeof releaseEnvChangeSchema>;
@@ -136,7 +137,17 @@ export interface UpgradePath {
  * `minUpgradeFrom` is newer than `from` blocks the path.
  */
 export declare function summarizeUpgradePath(manifests: Iterable<ReleaseManifest>, from: string, to: string): UpgradePath;
+export interface PackumentReleases {
+    manifests: ReleaseManifest[];
+    /** Versions that carry a `magnusRelease` this code cannot parse (a newer schema). */
+    unparsable: string[];
+    /** Versions npm marks deprecated. */
+    deprecated: string[];
+    /** `dist-tags.latest`, when present. */
+    latest: string | null;
+}
 /** Reads the manifests embedded as `magnusRelease` in a full npm packument. */
+export declare function readPackument(packument: unknown): PackumentReleases;
 export declare function manifestsFromPackument(packument: unknown): ReleaseManifest[];
 export declare const AGENT_SELF_UPGRADE_PROTOCOL = 1;
 export declare const agentUpgradeStateSchema: z.ZodEnum<{
@@ -148,14 +159,14 @@ export declare const agentUpgradeStateSchema: z.ZodEnum<{
     reverted: "reverted";
 }>;
 export declare const agentUpgradeReportSchema: z.ZodObject<{
-    state: z.ZodEnum<{
+    state: z.ZodUnion<readonly [z.ZodEnum<{
         failed: "failed";
         idle: "idle";
         staged: "staged";
         trial: "trial";
         confirmed: "confirmed";
         reverted: "reverted";
-    }>;
+    }>, z.ZodString]>;
     from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -163,6 +174,11 @@ export declare const agentUpgradeReportSchema: z.ZodObject<{
     attempt: z.ZodOptional<z.ZodNumber>;
     updatedAt: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
+/** The agent's local sticky managed-enrollment marker, as it reports it. */
+export declare const agentManagedEnrollmentSchema: z.ZodObject<{
+    nodeId: z.ZodString;
+    nodeFqdn: z.ZodString;
+}, z.core.$strip>;
 export declare const agentSelfUpgradeStatusSchema: z.ZodObject<{
     protocol: z.ZodNumber;
     launcherProtocol: z.ZodNullable<z.ZodNumber>;
@@ -174,14 +190,14 @@ export declare const agentSelfUpgradeStatusSchema: z.ZodObject<{
     enabled: z.ZodBoolean;
     reason: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     upgrade: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-        state: z.ZodEnum<{
+        state: z.ZodUnion<readonly [z.ZodEnum<{
             failed: "failed";
             idle: "idle";
             staged: "staged";
             trial: "trial";
             confirmed: "confirmed";
             reverted: "reverted";
-        }>;
+        }>, z.ZodString]>;
         from: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         to: z.ZodOptional<z.ZodNullable<z.ZodString>>;
         requestId: z.ZodOptional<z.ZodNullable<z.ZodString>>;
@@ -189,6 +205,11 @@ export declare const agentSelfUpgradeStatusSchema: z.ZodObject<{
         attempt: z.ZodOptional<z.ZodNumber>;
         updatedAt: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>>;
+    confirmSeconds: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    managedEnrollment: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        nodeId: z.ZodString;
+        nodeFqdn: z.ZodString;
+    }, z.core.$strip>>>;
 }, z.core.$strip>;
 export declare const agentUpgradeRequestSchema: z.ZodObject<{
     version: z.ZodString;
@@ -199,4 +220,13 @@ export declare const agentUpgradeRequestSchema: z.ZodObject<{
 export type AgentUpgradeState = z.infer<typeof agentUpgradeStateSchema>;
 export type AgentUpgradeReport = z.infer<typeof agentUpgradeReportSchema>;
 export type AgentSelfUpgradeStatus = z.infer<typeof agentSelfUpgradeStatusSchema>;
+export type AgentManagedEnrollment = z.infer<typeof agentManagedEnrollmentSchema>;
 export type AgentUpgradeRequest = z.infer<typeof agentUpgradeRequestSchema>;
+/** Name for the schema kept aside during a restore. */
+export declare function restoreAsideSchema(now: Date): string;
+/** Moves `public` aside and recreates it with the same owner and privileges. */
+export declare function restoreSwapSql(aside: string): string;
+/** After a failed restore: drop the partial schema and put the original back. */
+export declare function restoreRevertSql(aside: string): string;
+/** After a successful restore: drop the schema kept aside. */
+export declare function restoreFinishSql(aside: string): string;

package/dist/release.js

@@ -136,7 +136,8 @@ export const releaseEnvChangeSchema = z.object({
 export const migrationImpactSchema = z.enum(['fast', 'slow', 'one-way']);
 export const releaseMigrationSchema = z.object({
     name: z.string().min(1),
-    impact: migrationImpactSchema,
+    // An impact a newer release introduces is treated as the most cautious one.
+    impact: migrationImpactSchema.catch('one-way'),
     note: z.string().default(''),
 });
 export const releaseManifestSchema = z.object({
@@ -155,6 +156,8 @@ export const releaseManifestSchema = z.object({
     agent: z.object({ selfUpgradeProtocol: z.number().int().nonnegative(), minLauncher: z.number().int().nonnegative() }),
     summary: z.string().default(''),
     notesUrl: z.string().url().optional(),
+    /** npm install scripts the release's dependency tree needs (`allowScripts` of the version install). */
+    allowScripts: z.record(z.string(), z.boolean()).optional(),
 });
 /**
  * Merges the manifests of every release in (from, to]. Env names added and
@@ -200,35 +203,57 @@ export function summarizeUpgradePath(manifests, from, to) {
     };
 }
 /** Reads the manifests embedded as `magnusRelease` in a full npm packument. */
-export function manifestsFromPackument(packument) {
-    const versions = packument?.versions ?? {};
-    const manifests = [];
-    for (const entry of Object.values(versions)) {
-        const parsed = releaseManifestSchema.safeParse(entry?.magnusRelease);
+export function readPackument(packument) {
+    const doc = packument;
+    const result = { manifests: [], unparsable: [], deprecated: [], latest: null };
+    for (const [version, entry] of Object.entries(doc?.versions ?? {})) {
+        if (typeof entry?.deprecated === 'string' && entry.deprecated)
+            result.deprecated.push(version);
+        if (entry?.magnusRelease === undefined)
+            continue;
+        const parsed = releaseManifestSchema.safeParse(entry.magnusRelease);
         if (parsed.success)
-            manifests.push(parsed.data);
+            result.manifests.push(parsed.data);
+        else
+            result.unparsable.push(version);
     }
-    return manifests;
+    const latest = doc?.['dist-tags']?.['latest'];
+    if (typeof latest === 'string' && isVersion(latest))
+        result.latest = latest;
+    return result;
+}
+export function manifestsFromPackument(packument) {
+    return readPackument(packument).manifests;
 }
 // Agent self-upgrade wire contract.
 export const AGENT_SELF_UPGRADE_PROTOCOL = 1;
 export const agentUpgradeStateSchema = z.enum(['idle', 'staged', 'trial', 'confirmed', 'reverted', 'failed']);
+/** Known states plus any future one, so a newer agent's report is never dropped whole. */
+const reportedUpgradeState = z.union([agentUpgradeStateSchema, z.string().regex(/^[a-z][a-z0-9_-]{0,31}$/)]);
 export const agentUpgradeReportSchema = z.object({
-    state: agentUpgradeStateSchema,
+    state: reportedUpgradeState,
     from: z.string().nullable().optional(),
     to: z.string().nullable().optional(),
     requestId: z.string().max(128).nullable().optional(),
-    reason: z.string().max(500).nullable().optional(),
+    reason: z.string().max(1000).nullable().optional(),
     attempt: z.number().int().nonnegative().optional(),
     updatedAt: z.string().optional(),
 });
+/** The agent's local sticky managed-enrollment marker, as it reports it. */
+export const agentManagedEnrollmentSchema = z.object({
+    nodeId: z.string().min(1).max(128),
+    nodeFqdn: z.string().min(1).max(253),
+});
 export const agentSelfUpgradeStatusSchema = z.object({
     protocol: z.number().int().nonnegative(),
     launcherProtocol: z.number().int().nonnegative().nullable(),
     layout: z.enum(['versioned', 'legacy', 'container']),
     enabled: z.boolean(),
-    reason: z.string().max(300).nullable().optional(),
+    reason: z.string().max(1000).nullable().optional(),
     upgrade: agentUpgradeReportSchema.nullable().optional(),
+    /** Seconds a new version has on trial before the launcher switches back (MAGNUS_AGENT_UPGRADE_CONFIRM_SECONDS). */
+    confirmSeconds: z.number().int().positive().max(86_400).nullable().optional(),
+    managedEnrollment: agentManagedEnrollmentSchema.nullable().optional(),
 });
 export const agentUpgradeRequestSchema = z.object({
     version: versionString,
@@ -236,3 +261,34 @@ export const agentUpgradeRequestSchema = z.object({
     requestId: z.string().min(1).max(128),
     packageName: z.string().default('@hivemagnus/magnus-agent'),
 });
+// Database restore. A dump is restored into an empty `public` schema so that
+// tables a newer release created do not survive next to the restored ones:
+// the live schema is renamed aside, a new one with the same owner and grants
+// takes its place, `pg_restore --single-transaction` fills it, and the old
+// schema is dropped only after the restore committed (or renamed back if it
+// failed). Each step is one transaction.
+/** Name for the schema kept aside during a restore. */
+export function restoreAsideSchema(now) {
+    return `magnus_pre_restore_${now.toISOString().replace(/\D/g, '').slice(0, 14)}`;
+}
+/** Moves `public` aside and recreates it with the same owner and privileges. */
+export function restoreSwapSql(aside) {
+    return `DO $magnus$ DECLARE owner_name text; grant_row record; BEGIN
+  SELECT pg_get_userbyid(nspowner) INTO owner_name FROM pg_namespace WHERE nspname = 'public';
+  IF owner_name IS NULL THEN RAISE EXCEPTION 'schema public does not exist'; END IF;
+  EXECUTE format('ALTER SCHEMA public RENAME TO %I', '${aside}');
+  EXECUTE format('CREATE SCHEMA public AUTHORIZATION %I', owner_name);
+  FOR grant_row IN SELECT CASE WHEN a.grantee = 0 THEN 'PUBLIC' ELSE quote_ident(pg_get_userbyid(a.grantee)) END AS grantee, a.privilege_type
+    FROM pg_namespace n, aclexplode(n.nspacl) a WHERE n.nspname = '${aside}' LOOP
+    EXECUTE format('GRANT %s ON SCHEMA public TO %s', grant_row.privilege_type, grant_row.grantee);
+  END LOOP;
+END $magnus$;`;
+}
+/** After a failed restore: drop the partial schema and put the original back. */
+export function restoreRevertSql(aside) {
+    return `BEGIN; DROP SCHEMA public CASCADE; ALTER SCHEMA "${aside}" RENAME TO public; COMMIT;`;
+}
+/** After a successful restore: drop the schema kept aside. */
+export function restoreFinishSql(aside) {
+    return `DROP SCHEMA "${aside}" CASCADE;`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivemagnus/magnus-contracts",
-  "version": "1.1.2",
+  "version": "1.1.3",
   "description": "Shared Zod schemas and TypeScript types for the Magnus server, UI and node agent wire contracts.",
   "keywords": [
     "magnus",