@hallmaster/docker.js 0.0.5 → 0.0.7

package/README.md

@@ -0,0 +1,60 @@
+# Docker.js
+
+This repository is heavily used for the Hallmaster project, that you can check
+out [right here](https://github.com/hallmasterorg/hallmaster).
+
+It is a library used to manipulate Docker containers, images and all interfaces
+that can be managed by the Docker Engine.
+
+## How to use
+
+The entrypoint of this library is the `DockerSocket` object. It has to be
+instantiated given a UNIX socket (the one used by the Docker Engine) as well as
+the API hostname.
+
+```typescript
+// index.ts
+import { DockerSocket } from "@hallmaster/docker.js";
+
+(async function () {
+  const socket = new DockerSocket();
+
+  await socket.init(); // prepare the UNIX socket to be used
+
+  // if you want, you may authenticate to a Docker Image registry
+  // await socket.authenticate(
+  //   "ghcr.io",
+  //   "github_username",
+  //   "github_pat",
+  // );
+  // console.log(socket.token);
+
+  // you can get the information of the API from the socket such as the version
+  // of the Docker Engine
+  console.log(await socket.info());
+})();
+```
+
+Once you have instantiated the `DockerSocket` object and initialized it with the
+`init()` method, you are ready to use it everywhere.
+
+For instance, to fetch data from containers, you may use this snippet :
+
+```typescript
+import ( DockerContainer ) from "@hallmaster/docker.js";
+
+(async function() {
+    // ...
+
+    const containerApi = new DockerContainer(dockerSocket);
+
+    const containers = await containerApi.list();
+    for (const container of containers) {
+        const containerLogs = await containerApi.logs(container.Id);
+        console.log("-----------");
+        console.log(`Logs for the container #${container.Id}`);
+        console.log(containerLogs);
+        console.log("-----------");
+    }
+})();
+```

package/dist/DockerContainer.d.ts

@@ -0,0 +1,33 @@
+import DockerSocket from "./DockerSocket";
+import type { DockerContainerStats } from "./types/DockerContainerStats";
+import type { DockerContainerSumary } from "./types/DockerContainerSummary";
+import type { DockerContainerTop } from "./types/DockerContainerTop";
+export default class DockerContainer {
+    private readonly dockerSocket;
+    constructor(dockerSocket: DockerSocket);
+    list(options?: {
+        all?: boolean;
+        limit?: number;
+        size?: boolean;
+        filters?: Record<string, string[]>;
+    }): Promise<DockerContainerSumary>;
+    get(containerId: string, size?: boolean): Promise<DockerContainer>;
+    top(containerId: string, psArgs?: string): Promise<DockerContainerTop>;
+    logs(containerId: string, options?: {
+        follow?: boolean;
+        stdout?: boolean;
+        stderr?: boolean;
+        since?: number;
+        until?: number;
+        timestamps?: boolean;
+        tail?: number | "all";
+    }): Promise<string>;
+    stats(containerId: string, options?: {
+        stream: true;
+        oneShot?: false;
+    } | {
+        stream: false;
+        oneShot?: boolean;
+    }): Promise<DockerContainerStats>;
+}
+//# sourceMappingURL=DockerContainer.d.ts.map

package/dist/DockerContainer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DockerContainer.d.ts","sourceRoot":"","sources":["../src/DockerContainer.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,MAAM,gBAAgB,CAAC;AAC1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AACzE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gCAAgC,CAAC;AAC5E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAErE,MAAM,CAAC,OAAO,OAAO,eAAe;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,YAAY;IAEjD,IAAI,CACR,OAAO,GAAE;QACP,GAAG,CAAC,EAAE,OAAO,CAAC;QACd,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;KACiB;IAkBlD,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,GAAE,OAAe;IAQ9C,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,GAAE,MAAc;IAQ/C,IAAI,CACR,WAAW,EAAE,MAAM,EACnB,OAAO,GAAE;QACP,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,MAAM,CAAC,EAAE,OAAO,CAAC;QACjB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,UAAU,CAAC,EAAE,OAAO,CAAC;QACrB,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK,CAAC;KASvB;IAqBG,KAAK,CACT,WAAW,EAAE,MAAM,EACnB,OAAO,GACH;QAAE,MAAM,EAAE,IAAI,CAAC;QAAC,OAAO,CAAC,EAAE,KAAK,CAAA;KAAE,GACjC;QACE,MAAM,EAAE,KAAK,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;KAIvB;CAeJ"}

package/dist/DockerContainer.js

@@ -0,0 +1,58 @@
+import DockerSocket from "./DockerSocket";
+export default class DockerContainer {
+    dockerSocket;
+    constructor(dockerSocket) {
+        this.dockerSocket = dockerSocket;
+    }
+    async list(options = { all: false, limit: 0, size: false, filters: {} }) {
+        const apiOptions = {
+            all: (options.all ?? false).toString(),
+            limit: (options.limit ?? 0).toString(),
+            size: (options.size ?? false).toString(),
+            filters: JSON.stringify(options.filters ?? {}),
+        };
+        return await this.dockerSocket.apiCall("GET", "/containers/json", {
+            query: apiOptions,
+        });
+    }
+    async get(containerId, size = false) {
+        return await this.dockerSocket.apiCall("GET", `/containers/${containerId}/json`, { query: { size: size.toString() } });
+    }
+    async top(containerId, psArgs = "-ef") {
+        return await this.dockerSocket.apiCall("GET", `/containers/${containerId}/top`, { query: { psArgs: psArgs } });
+    }
+    async logs(containerId, options = {
+        follow: false,
+        stdout: false,
+        stderr: false,
+        since: 0,
+        until: 0,
+        timestamps: false,
+        tail: "all",
+    }) {
+        const apiOptions = {
+            follow: (options?.follow ?? false).toString(),
+            stdout: (options?.stdout ?? false).toString(),
+            stderr: (options?.stderr ?? false).toString(),
+            since: (options?.since ?? 0).toString(),
+            until: (options?.until ?? 0).toString(),
+            timestamps: (options?.timestamps ?? false).toString(),
+            tail: (options?.tail ?? "all").toString(),
+        };
+        return await this.dockerSocket.apiCall("GET", `/containers/${containerId}/logs`, {
+            query: apiOptions,
+        });
+    }
+    async stats(containerId, options = {
+        stream: true,
+        oneShot: false,
+    }) {
+        const apiOptions = {
+            stream: (options.stream ?? true).toString(),
+            "one-shot": (options.oneShot ?? false).toString(),
+        };
+        return await this.dockerSocket.apiCall("GET", `/containers/${containerId}/stats`, {
+            query: apiOptions,
+        });
+    }
+}

package/dist/DockerSocket.d.ts

@@ -14,6 +14,7 @@ export default class DockerSocket {
     apiCall<T>(method: Request["method"], urlPath: string, options?: {
         headers?: Record<string, string>;
         body?: string | Buffer | DataView;
+        query?: Record<string, string>;
     }): Promise<T>;
     authenticate(serverAddress: string, username: string, password: string): Promise<void>;
     info(): Promise<DockerInfo>;

package/dist/DockerSocket.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"DockerSocket.d.ts","sourceRoot":"","sources":["../src/DockerSocket.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQrD,MAAM,CAAC,OAAO,OAAO,YAAY;IAS7B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAR7B,OAAO,CAAC,gBAAgB,CAAS;IAEjC,OAAO,CAAC,aAAa,CAA8B;IAEnD,OAAO,CAAC,eAAe,CAAuB;gBAG5C,cAAc,GAAE,MAA+B,EAC9B,UAAU,GAAE,MAA2B;IAKpD,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;YAiBnB,OAAO;IA+Df,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B,IAAI,OAAO,kBAKV;IAED,IAAI,KAAK,WAKR;IAEK,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;KACnC,GACA,OAAO,CAAC,CAAC,CAAC;IAYP,YAAY,CAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAoBV,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;CAGlC"}
+{"version":3,"file":"DockerSocket.d.ts","sourceRoot":"","sources":["../src/DockerSocket.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAQrD,MAAM,CAAC,OAAO,OAAO,YAAY;IAS7B,OAAO,CAAC,QAAQ,CAAC,UAAU;IAR7B,OAAO,CAAC,gBAAgB,CAAS;IAEjC,OAAO,CAAC,aAAa,CAA8B;IAEnD,OAAO,CAAC,eAAe,CAAuB;gBAG5C,cAAc,GAAE,MAA+B,EAC9B,UAAU,GAAE,MAA2B;IAKpD,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;YAiBnB,OAAO;IAqEf,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAa3B,IAAI,OAAO,kBAKV;IAED,IAAI,KAAK,WAKR;IAEK,OAAO,CAAC,CAAC,EACb,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,EACzB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QACR,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,QAAQ,CAAC;QAClC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAChC,GACA,OAAO,CAAC,CAAC,CAAC;IAkBP,YAAY,CAChB,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC;IAmBV,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC;CAGlC"}

package/dist/DockerSocket.js

@@ -26,12 +26,17 @@ export default class DockerSocket {
     }
     async request(method, path, options) {
         const url = new URL(path, this.apiBaseURL);
+        if (options?.query) {
+            for (const [k, v] of Object.entries(options.query)) {
+                url.searchParams.set(k, v);
+            }
+        }
         const requestOptions = {
             hostname: url.hostname,
             host: url.host,
             protocol: url.protocol,
             port: url.port,
-            path: url.pathname,
+            path: url.pathname + url.search.toString(),
             headers: options?.headers,
             method: method,
             socketPath: this.dockerSocketPath,
@@ -85,8 +90,14 @@ export default class DockerSocket {
     }
     async apiCall(method, urlPath, options) {
         const { ApiVersion } = this.version;
-        const response = await this.request(method, path.join("/", `v${ApiVersion}`, urlPath), options);
-        return JSON.parse(response.body.toString("utf-8"));
+        const response = await this.request(method, `/v${ApiVersion}/${urlPath.replace(/^\//, "")}`, options);
+        const responseBody = response.body.toString("utf-8");
+        try {
+            return JSON.parse(responseBody);
+        }
+        catch {
+            return responseBody;
+        }
     }
     async authenticate(serverAddress, username, password) {
         const tokenPayload = JSON.stringify({ serverAddress, username, password });

package/dist/index.js

@@ -1,12 +1,19 @@
+import DockerContainer from "./DockerContainer";
 import DockerSocket from "./DockerSocket";
 (async function () {
     const socket = new DockerSocket();
     await socket.init();
-    console.log(await socket.info());
     // await socket.authenticate(
     //   "ghcr.io",
     //   "github_username",
     //   "github_pat",
     // );
     // console.log(socket.token);
+    // console.log(await socket.info());
+    const containersApi = new DockerContainer(socket);
+    const containersSummary = await containersApi.stats("XXX", {
+        stream: false,
+        oneShot: true,
+    });
+    console.log(containersSummary);
 })();

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@hallmaster/docker.js",
   "description": "A TypeScript Docker API wrapper mainly used for the Hallmaster project.",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "private": false,
@@ -15,6 +15,7 @@
     "dist"
   ],
   "repository": "github:hallmasterorg/hallmaster-docker-wrapper",
+  "homepage": "https://github.com/hallmasterorg/hallmaster-docker-wrapper#readme",
   "devDependencies": {
     "@types/node": "^25.0.9",
     "typescript": "^5.9.3"