@dockstat/docker 0.1.0

package/README.md

@@ -0,0 +1,289 @@
+# @dockstat/docker
+
+> A Bun-native, type-safe wrapper for the Docker API
+
+**@dockstat/docker** provides a modern, fully-typed interface to Docker's remote API, built specifically for [Bun](https://bun.sh). It offers a modular architecture, comprehensive type safety, and support for both Unix sockets and TCP connections with TLS.
+
+## Features
+
+- **Bun-Native**: Optimized for Bun's performance and APIs
+- **Type-Safe**: Full TypeScript coverage with generated types from Docker's OpenAPI spec
+- **Modular Architecture**: Separate modules for containers, images, networks, volumes, and more
+- **Flexible Connection**: Support for Unix sockets, TCP, and TLS-secured connections
+- **Environment-Based Config**: Automatically reads Docker environment variables (like the Docker CLI)
+- **Zero Dependencies**: Minimal footprint, leveraging Bun's built-in capabilities
+
+## Installation
+
+```bash
+bun add @dockstat/docker
+```
+
+## Quick Start
+
+### Using Environment Variables
+
+The easiest way to get started is by letting the package auto-configure from your environment:
+
+```ts
+import { createDockerFromEnv } from "@dockstat/docker"
+
+const docker = createDockerFromEnv()
+```
+
+This reads from standard Docker environment variables:
+- `DOCKER_SOCKET` - Path to Unix socket or TCP URL (default: `/var/run/docker.sock`)
+- `CERT_FILE`, `KEY_FILE`, `CA_FILE` - Paths to TLS certificates
+
+### Manual Configuration
+
+For full control over the connection:
+
+```ts
+import { Docker } from "@dockstat/docker"
+
+// Unix socket connection
+const docker = new Docker({
+  mode: "unix",
+  socketPath: "/var/run/docker.sock"
+})
+
+// TCP connection
+const docker = new Docker({
+  mode: "tcp",
+  baseUrl: "http://localhost:2375"
+})
+
+// TCP with TLS
+const docker = new Docker({
+  mode: "tcp",
+  baseUrl: "https://remote-docker:2376",
+  tls: {
+    cert: Bun.file("/path/to/cert.pem"),
+    key: Bun.file("/path/to/key.pem"),
+    ca: Bun.file("/path/to/ca.pem")
+  }
+})
+```
+
+### Verify Connection
+
+```ts
+const isConnected = await docker.ping()
+console.log("Docker daemon reachable:", isConnected)
+```
+
+## Usage
+
+### Containers
+
+List all containers:
+
+```ts
+const containers = await docker.containers.list()
+console.log(containers)
+```
+
+List running containers only:
+
+```ts
+const runningContainers = await docker.containers.list({
+  all: false
+})
+```
+
+Create and start a container:
+
+```ts
+const result = await docker.containers.create({
+  Image: "nginx:latest",
+  Env: ["NGINX_PORT=80"]
+})
+await docker.containers.start(result.Id)
+```
+
+Inspect a container:
+
+```ts
+const details = await docker.containers.inspect("my-container")
+console.log(details.State)
+```
+
+Get container logs:
+
+```ts
+const logs = await docker.containers.logs("my-container", {
+  stdout: true,
+  stderr: true
+})
+```
+
+Stop and remove a container:
+
+```ts
+await docker.containers.stop("my-container")
+await docker.containers.remove("my-container", false, true)
+```
+
+### Images
+
+List images:
+
+```ts
+const images = await docker.images.list()
+```
+
+Pull an image:
+
+```ts
+await docker.images.create("nginx:latest", {})
+```
+
+### Networks
+
+List networks:
+
+```ts
+const networks = await docker.networks.list()
+```
+
+Create a network:
+
+```ts
+await docker.networks.create({
+  Name: "my-network",
+  Driver: "bridge"
+})
+```
+
+### Volumes
+
+List volumes:
+
+```ts
+const volumes = await docker.volumes.list()
+```
+
+Create a volume:
+
+```ts
+await docker.volumes.create({
+  Name: "my-volume",
+  Driver: "local"
+})
+```
+
+### Executing Commands
+
+Run a command in a container:
+
+```ts
+// Create exec instance
+const exec = await docker.containers.execCreate("my-container", {
+  AttachStdout: true,
+  AttachStderr: true,
+  Cmd: ["ls", "-la", "/app"]
+})
+
+// Start exec and get output
+const response = await docker.containers.execStart(exec.Id)
+```
+
+### Statistics
+
+Get container resource usage:
+
+```ts
+// Get single stats snapshot
+const stats = await docker.containers.stats("my-container")
+console.log(stats.cpu_stats, stats.memory_stats)
+
+// Stream stats
+const stream = await docker.containers.stats("my-container", { stream: true })
+// stream is a Response object with streaming body
+```
+
+## API Modules
+
+The `Docker` class provides access to the following modules:
+
+- **`containers`** - Container lifecycle, logs, stats, exec, filesystem operations
+- **`images`** - Image management, building, pulling
+- **`networks`** - Network creation, inspection, connection management
+- **`volumes`** - Volume lifecycle and management
+- **`exec`** - Execute commands in running containers
+- **`distribution`** - Registry and distribution operations
+- **`nodes`** - Swarm node management
+
+All modules are fully typed with TypeScript types generated from Docker's OpenAPI specification.
+
+## Configuration
+
+### Connection Modes
+
+**Unix Socket** (default):
+
+```ts
+{
+  mode: "unix",
+  socketPath: "/var/run/docker.sock",
+  tls?: TLSOptions
+}
+```
+
+**TCP**:
+
+```ts
+{
+  mode: "tcp",
+  baseUrl: "http://localhost:2375",
+  tls?: TLSOptions
+}
+```
+
+### Environment Variables
+
+When using `createDockerFromEnv()`, the following environment variables are respected:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `DOCKER_SOCKET` | Unix socket path or TCP URL | `/var/run/docker.sock` |
+| `CERT_FILE` | Path to client certificate | - |
+| `KEY_FILE` | Path to client key | - |
+| `CA_FILE` | Path to CA certificate | - |
+
+## TypeScript Support
+
+This package includes comprehensive TypeScript types for all Docker API operations.
+
+All methods return properly typed responses:
+
+```ts
+import type { ContainerInspectResponse } from "@dockstat/docker"
+
+const container: ContainerInspectResponse = await docker.containers.inspect("my-id")
+// Full type safety and autocomplete
+```
+
+## Part of the DockStat Ecosystem
+
+`@dockstat/docker` is a core package in the [DockStat](https://github.com/its4nik/dockstat) project, an extensible container administration and monitoring platform. It powers Docker interactions throughout the DockStat ecosystem, providing a unified, type-safe interface for container management.
+
+## Contributing
+
+Contributions are welcome! Please follow these guidelines:
+
+1. Follow the existing code style and structure
+2. Ensure TypeScript types are properly defined
+3. Add JSDoc comments for public APIs
+4. Test your changes thoroughly
+
+For detailed development guidelines, see the [main DockStat README](https://github.com/its4nik/dockstat).
+
+## License
+
+[ Mozilla Public License Version 2.0 ](https://www.mozilla.org/en-US/MPL/2.0/)
+
+---
+
+**Made with ❤️ for the DockStat project**

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@dockstat/docker",
+  "description": "A bun native, typesafe wrapper for the docker API",
+  "author": {
+    "email": "info@itsnik.de",
+    "name": "ItsNik",
+    "url": "https://itsnik.de"
+  },
+  "keywords": [
+    "docker",
+    "bun"
+  ],
+  "version": "0.1.0",
+  "license": "MPL-2.0",
+  "repository": {
+    "directory": "packages/bun-docker",
+    "type": "git",
+    "url": "https://github.com/its4nik/dockstat"
+  },
+  "module": "src/index.ts",
+  "type": "module",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/node": "^25.5.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "tsconfig.json"
+  ],
+  "scripts": {
+    "build": "bun build --target=bun --production --sourcemap=external --outdir=dist src/index.ts",
+    "typegen": "bunx tsc --declaration --pretty --outFile dist/types.d.ts --emitDeclarationOnly src/index.ts",
+    "publish": "bun run build && bun run typegen && bun pm pack --destination ./dist && npm publish --access public ./dist/*.tgz ; rm -r ./dist"
+  }
+}

package/src/docker.ts

@@ -0,0 +1,35 @@
+import { BaseModule } from "./modules/base"
+import type { ConnectionConfig } from "./modules/base/types"
+import { ContainerModule } from "./modules/container"
+import { DistributionModule } from "./modules/distribution"
+import { ExecModule } from "./modules/exec"
+import { ImagesModule } from "./modules/images"
+import { NetworksModule } from "./modules/networks"
+import { NodesModule } from "./modules/nodes"
+import { VolumeModule } from "./modules/volumes"
+
+export class Docker {
+  public readonly containers: ContainerModule
+  public readonly images: ImagesModule
+  public readonly networks: NetworksModule
+  public readonly volumes: VolumeModule
+  public readonly exec: ExecModule
+  public readonly distribution: DistributionModule
+  public readonly nodes: NodesModule
+
+  constructor(private config: ConnectionConfig) {
+    this.containers = new ContainerModule(config)
+    this.images = new ImagesModule(config)
+    this.networks = new NetworksModule(config)
+    this.volumes = new VolumeModule(config)
+    this.exec = new ExecModule(config)
+    this.distribution = new DistributionModule(config)
+    this.nodes = new NodesModule(config)
+  }
+
+  async ping(): Promise<boolean> {
+    const requester = new BaseModule(this.config)
+    const res = await requester.request("/_ping", "GET")
+    return res.ok
+  }
+}

package/src/environment.d.ts

@@ -0,0 +1,15 @@
+declare global {
+  namespace NodeJS {
+    interface ProcessEnv {
+      DOCKER_SOCKET: "/var/run/docker.sock" | string
+      ENABLE_API?: string
+      API_KEYS?: string
+      API_PORT?: string
+      KEY_FILE?: "./key.pem"
+      CERT_FILE?: "./cert.pem"
+      CA_FILE?: "./ca.pem"
+    }
+  }
+}
+
+export {}

package/src/index.ts

@@ -0,0 +1,9 @@
+import { Docker } from "./docker"
+import { getConnectionConfig } from "./utils/env"
+
+export const createDockerFromEnv = () => {
+  const config = getConnectionConfig()
+  return new Docker(config)
+}
+
+export { Docker }

package/src/modules/_socket/index.ts

@@ -0,0 +1,106 @@
+import type { ReadableStreamDefaultReader } from "node:stream/web"
+
+/**
+ * WebSocket-like interface for Docker container attach
+ * Uses the attach endpoint with stream wrapping for compatibility with Unix sockets
+ *
+ * @note Currently supports read-only operations (receiving stdout/stderr). Full WebSocket
+ * protocol support with bidirectional communication is planned for future versions.
+ */
+export class DockerWebSocket {
+  private static readonly CONNECTING = 0
+  private static readonly OPEN = 1
+  private static readonly CLOSING = 2
+  private static readonly CLOSED = 3
+
+  private readyStateValue: number = DockerWebSocket.CONNECTING
+  private listeners: Map<string, Array<(event: unknown) => void>> = new Map()
+  private reader: ReadableStreamDefaultReader | null = null
+
+  addEventListener(type: string, listener: (event: unknown) => void) {
+    if (!this.listeners.has(type)) {
+      this.listeners.set(type, [])
+    }
+    this.listeners.get(type)?.push(listener)
+  }
+
+  removeEventListener(type: string, listener: (event: unknown) => void) {
+    const typeListeners = this.listeners.get(type)
+    if (typeListeners) {
+      const index = typeListeners.indexOf(listener)
+      if (index > -1) {
+        typeListeners.splice(index, 1)
+      }
+    }
+  }
+
+  async attach(response: Response) {
+    if (!response.body) {
+      this.emit("error", new Error("Response has no body"))
+      this.readyStateValue = DockerWebSocket.CLOSED
+      this.emit("close", {})
+      return
+    }
+
+    this.reader = response.body.getReader()
+    this.readyStateValue = DockerWebSocket.OPEN
+    this.emit("open", {})
+
+    try {
+      while (this.readyStateValue === DockerWebSocket.OPEN) {
+        const { done, value } = await this.reader.read()
+        if (done) break
+
+        // Decode the chunk to string
+        const text = new TextDecoder().decode(value)
+        this.emit("message", { data: text })
+      }
+    } catch (error) {
+      if (this.readyStateValue !== DockerWebSocket.CLOSING) {
+        this.emit("error", error)
+      }
+    } finally {
+      this.readyStateValue = DockerWebSocket.CLOSED
+      this.emit("close", {})
+    }
+  }
+
+  close() {
+    if (this.readyStateValue === DockerWebSocket.CLOSED) return
+
+    this.readyStateValue = DockerWebSocket.CLOSING
+
+    if (this.reader) {
+      this.reader.cancel().catch(() => {})
+    }
+
+    this.readyStateValue = DockerWebSocket.CLOSED
+    this.emit("close", {})
+  }
+
+  get CONNECTING() {
+    return DockerWebSocket.CONNECTING
+  }
+  get OPEN() {
+    return DockerWebSocket.OPEN
+  }
+  get CLOSING() {
+    return DockerWebSocket.CLOSING
+  }
+  get CLOSED() {
+    return DockerWebSocket.CLOSED
+  }
+
+  get readyState() {
+    return this.readyStateValue
+  }
+
+  private emit(type: string, event: unknown) {
+    const listeners = this.listeners.get(type)
+    if (listeners) {
+      for (const listener of listeners) {
+        listener(event)
+      }
+    }
+  }
+}

package/src/modules/base/index.ts

@@ -0,0 +1,30 @@
+import type { BodyInit, HeadersInit } from "bun"
+import { prepareRequestOptions } from "../../utils/request-options"
+import { handleDockerResponse } from "../../utils/response"
+import { buildDockerUrl, buildQueryString } from "../../utils/url"
+import { DockerWebSocket } from "../_socket"
+import type { ConnectionConfig, HttpMethod } from "./types"
+
+export class BaseModule {
+  constructor(private config: ConnectionConfig) {}
+
+  protected ws = new DockerWebSocket()
+
+  async request(
+    path: string,
+    method: HttpMethod = "GET",
+    body?: BodyInit | object,
+    headers?: HeadersInit,
+    params?: object
+  ) {
+    const dockerApiVersion = this.config.dockerAPIVersion || "1.54"
+    const query = buildQueryString(params)
+    const url = buildDockerUrl(this.config, path, query, dockerApiVersion)
+
+    const options = prepareRequestOptions(this.config, method, body, headers, url)
+
+    const response = await fetch(url, options)
+
+    return handleDockerResponse(response, path, dockerApiVersion, params)
+  }
+}

package/src/modules/base/types.ts

@@ -0,0 +1,17 @@
+import type { TLSOptions } from "bun"
+
+export type ConnectionMode = "unix" | "tcp"
+
+export interface ConnectionConfig {
+  mode: ConnectionMode
+  // For Unix: the file path
+  socketPath?: string
+  // For TCP: the full base URL (e.g., http://192.168.1.50:2375)
+  baseUrl?: string
+  // TLS options (used for TCP or TLS-secured Unix sockets)
+  tls?: TLSOptions
+  // The docker API version
+  dockerAPIVersion?: string
+}
+
+export type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "HEAD"