anbaric-cloud-hosting 1.31.0 → 1.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.31.0",
+  "version": "1.32.0",
   "description": "Anbaric Cloud hosting service: Postgres-backed job persistence and queuing exposed over an HTTP API",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -18,18 +18,18 @@
     "@aws-sdk/client-s3": "^3.1110.0",
     "@aws-sdk/client-secrets-manager": "^3.700.0",
     "@aws-sdk/client-servicediscovery": "^3.1110.0",
-    "anbaric-data-store": "^1.31.0",
-    "anbaric-plugins": "^1.31.0",
-    "anbaric-tsapi": "^1.31.0",
-    "anbaric-web": "^1.31.0",
+    "anbaric-data-store": "^1.32.0",
+    "anbaric-plugins": "^1.32.0",
+    "anbaric-tsapi": "^1.32.0",
+    "anbaric-web": "^1.32.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.31.0",
-    "anbaric-state-machine": "^1.31.0",
+    "anbaric-impl-cloud": "^1.32.0",
+    "anbaric-state-machine": "^1.32.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/app-management/BaseBuildLayer.ts

@@ -114,10 +114,28 @@ abstract class BaseBuildLayer implements BuildLayer {
         }));
     }
 
+    // Regenerates an app's docs from its uploaded source without redeploying it:
+    // the source is materialised (from S3 for Fargate, from disk for Docker) and
+    // the same generator that runs on deploy is invoked against it.
+    async regenerateDocs(appName : string) : Promise<number> {
+        if (!this.deployments.has(appName)) throw new Error(`No app named "${appName}"`);
+        if (!this.docGenerator) throw new Error("Documentation generation is not configured on this platform");
+
+        const { dir, cleanup } = await this.sourceDir(appName);
+        try {
+            return await this.docGenerator.generate(appName, dir, { redeploy: true });
+        } finally {
+            await cleanup();
+        }
+    }
+
     protected abstract appHostFor(appName : string) : string;
     protected abstract start(deployment : Deployment, appDir : string, entryPoint : string) : Promise<void>;
     protected abstract stop(deployment : Deployment) : Promise<void>;
     protected abstract streamLogs(deployment : Deployment, signal : AbortSignal) : AsyncIterable<string>;
+    // Materialises the app's source into a directory for regeneration; the
+    // returned cleanup removes anything temporary the implementation created.
+    protected abstract sourceDir(appName : string) : Promise<{ dir : string, cleanup : () => Promise<void> }>;
 
     private async buildAndStart(deployment : Deployment, tarball : Buffer) : Promise<void> {
         const appDir = join(this.appsDir, deployment.appName);

package/src/app-management/BuildLayer.ts

@@ -16,6 +16,9 @@ interface BuildLayer {
     ping(appName : string) : Promise<boolean>;
     logs(appName : string, signal : AbortSignal) : AsyncIterable<string>;
     teardown(appName : string) : Promise<boolean>;
+    // Re-runs documentation generation for an already-deployed app from its
+    // uploaded source, without redeploying it. Returns the number of docs written.
+    regenerateDocs(appName : string) : Promise<number>;
     cleanUp() : Promise<void>;
 
 }

package/src/app-management/DockerBuildLayer.ts

@@ -120,6 +120,12 @@ class DockerBuildLayer extends BaseBuildLayer {
         await this.removeContainer(deployment, this.appHostFor(deployment.appName));
     }
 
+    // Locally the extracted source from the last deploy is still on disk, so
+    // regeneration reads it in place with nothing to clean up.
+    protected async sourceDir(appName : string) : Promise<{ dir : string, cleanup : () => Promise<void> }> {
+        return { dir: join(this.appsDir, appName), cleanup: async () => {} };
+    }
+
     private async removeContainer(deployment : Deployment, container : string) : Promise<void> {
         await this.docker(deployment, ["rm", "--force", container]).catch(() => {});
     }

package/src/app-management/FargateBuildLayer.ts

@@ -1,10 +1,12 @@
-import {readFile, writeFile} from "node:fs/promises";
+import {spawn} from "node:child_process";
+import {mkdir, mkdtemp, readFile, rm, writeFile} from "node:fs/promises";
+import {tmpdir} from "node:os";
 import {join} from "node:path";
 import {CodeBuildClient, BatchGetBuildsCommand, StartBuildCommand} from "@aws-sdk/client-codebuild";
 import {ECSClient, CreateServiceCommand, DeleteServiceCommand, DescribeServicesCommand,
     DescribeTaskDefinitionCommand, ListServicesCommand as ListEcsServicesCommand,
     RegisterTaskDefinitionCommand, UpdateServiceCommand} from "@aws-sdk/client-ecs";
-import {S3Client, PutObjectCommand} from "@aws-sdk/client-s3";
+import {S3Client, GetObjectCommand, PutObjectCommand} from "@aws-sdk/client-s3";
 import {ServiceDiscoveryClient, CreateServiceCommand as CreateDiscoveryServiceCommand,
     ListServicesCommand} from "@aws-sdk/client-servicediscovery";
 import {CloudWatchLogsClient, FilterLogEventsCommand, StartLiveTailCommand} from "@aws-sdk/client-cloudwatch-logs";
@@ -344,7 +346,38 @@ class FargateBuildLayer extends BaseBuildLayer {
         return `builds/${appName}.tar.gz`;
     }
 
+    protected async sourceDir(appName : string) : Promise<{ dir : string, cleanup : () => Promise<void> }> {
+        const work = await mkdtemp(join(tmpdir(), `anbaric-docs-${appName}-`));
+        const cleanup = () => rm(work, { recursive: true, force: true });
+
+        try {
+            const object = await this.aws.s3.send(new GetObjectCommand({
+                Bucket: this.options.buildBucket,
+                Key: this.buildKeyFor(appName),
+            }));
+            const bytes = await object.Body.transformToByteArray();
+
+            const tarballPath = join(work, "source.tar.gz");
+            await writeFile(tarballPath, Buffer.from(bytes));
+            const dir = join(work, "src");
+            await mkdir(dir, { recursive: true });
+            await extractTarball(tarballPath, dir);
+
+            return { dir, cleanup };
+        } catch (error) {
+            await cleanup();
+            throw error;
+        }
+    }
+
 }
 
+const extractTarball = (tarballPath : string, dir : string) : Promise<void> =>
+    new Promise((resolve, reject) => {
+        const tar = spawn("tar", ["-xzf", tarballPath, "-C", dir]);
+        tar.on("error", reject);
+        tar.on("close", code => code === 0 ? resolve() : reject(new Error(`tar exited with code ${code}`)));
+    });
+
 export { FargateBuildLayer };
 export type { AwsClients, FargateBuildLayerOptions };

package/src/docs/DocGenerator.ts

@@ -75,20 +75,22 @@ class DocGenerator {
 
     constructor(private model : DocModel, private store : AppDocsStore) {}
 
-    async generate(appName : string, appDir : string, options : { redeploy : boolean }) : Promise<void> {
+    async generate(appName : string, appDir : string, options : { redeploy : boolean }) : Promise<number> {
         try {
             const { files, truncated } = await gatherSources(appDir);
-            if (files.length === 0) return;
+            if (files.length === 0) return 0;
 
             const drafts = await this.model.writeDocs({ appName, files, truncated });
             const readme = files.find(file => README.test(file.path))?.content;
             const docs = buildDocTree(drafts, readme);
-            if (docs.length === 0) return;
+            if (docs.length === 0) return 0;
 
             await this.store.replaceForApp(appName, docs);
             console.log(`[docs] ${options.redeploy ? "regenerated" : "generated"} ${docs.length} doc(s) for "${appName}"`);
+            return docs.length;
         } catch (error) {
             console.error(`[docs] could not generate documentation for "${appName}": ${error instanceof Error ? error.message : error}`);
+            return 0;
         }
     }
 

package/src/hosting/handlers/AppsHandler.ts

@@ -15,6 +15,9 @@ class AppsHandler implements RequestHandler {
             case "logs":
                 if (request.id) return this.handleLogs(request, request.id);
                 break;
+            case "docs":
+                if (request.id) return this.handleDocs(request, request.id);
+                break;
             case undefined:
                 if (request.id) return this.handleApp(request, request.id);
                 return this.handleCollection(request);
@@ -22,6 +25,17 @@ class AppsHandler implements RequestHandler {
         request.notFound();
     }
 
+    private async handleDocs(request : Request, appName : string) : Promise<void> {
+        if (request.method !== "POST") return request.notFound();
+        try {
+            const docs = await this.buildLayer.regenerateDocs(appName);
+            return request.reply(200, { appName, docs });
+        } catch (error) {
+            const message = error instanceof Error ? error.message : "Could not regenerate documentation";
+            return request.reply(message.startsWith("No app") ? 404 : 400, { error: message });
+        }
+    }
+
     private async handleDeploy(request : Request, appName : string) : Promise<void> {
         switch (request.method) {
             case "POST": {