the-moby-effect 1.45.0-alpha.2 → 1.45.0-alpha.21

package/src/MobyConnection.ts

@@ -0,0 +1,314 @@
+/**
+ * Http, https, ssh, and unix socket connection agents for all platforms.
+ *
+ * @since 1.0.0
+ */
+
+import type ssh2 from "ssh2";
+
+import * as Path from "@effect/platform/Path";
+import * as Config from "effect/Config";
+import * as ConfigError from "effect/ConfigError";
+import * as Data from "effect/Data";
+import * as Effect from "effect/Effect";
+import * as Function from "effect/Function";
+import * as Match from "effect/Match";
+import * as Redacted from "effect/Redacted";
+
+/**
+ * Connection options for how to connect to your moby/docker instance. Can be a
+ * unix socket on the current machine. Can be an ssh connection to a remote
+ * machine with a remote user, remote machine, remote port, and remote socket
+ * path. Can be an http connection to a remote machine with a host, port, and
+ * path. Or it can be an https connection to a remote machine with a host, port,
+ * path, cert, ca, key, and passphrase.
+ *
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type MobyConnectionOptions = Data.TaggedEnum<{
+    socket: { readonly socketPath: string; readonly version?: string | undefined };
+    ssh: {
+        readonly remoteSocketPath: string;
+        readonly host: string;
+        readonly version?: string | undefined;
+    } & Exclude<ssh2.ConnectConfig, "host">;
+    http: {
+        readonly host: string;
+        readonly port: number;
+        readonly path?: string | undefined;
+        readonly version?: string | undefined;
+    };
+    https: {
+        readonly host: string;
+        readonly port: number;
+        readonly version?: string | undefined;
+        readonly path?: string | undefined;
+        readonly cert?: string | undefined;
+        readonly ca?: string | undefined;
+        readonly key?: string | undefined;
+        readonly passphrase?: string | undefined;
+    };
+}>;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type SocketConnectionOptions = Data.TaggedEnum.Args<MobyConnectionOptions, "socket">;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type SocketConnectionOptionsTagged = Data.TaggedEnum.Value<MobyConnectionOptions, "socket">;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type HttpConnectionOptions = Data.TaggedEnum.Args<MobyConnectionOptions, "http">;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type HttpConnectionOptionsTagged = Data.TaggedEnum.Value<MobyConnectionOptions, "http">;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type HttpsConnectionOptions = Data.TaggedEnum.Args<MobyConnectionOptions, "https">;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type HttpsConnectionOptionsTagged = Data.TaggedEnum.Value<MobyConnectionOptions, "https">;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type SshConnectionOptions = Data.TaggedEnum.Args<MobyConnectionOptions, "ssh">;
+
+/**
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export type SshConnectionOptionsTagged = Data.TaggedEnum.Value<MobyConnectionOptions, "ssh">;
+
+/**
+ * Connection options for how to connect to your moby/docker instance. Can be a
+ * unix socket on the current machine. Can be an ssh connection to a remote
+ * machine with a remote user, remote machine, remote port, and remote socket
+ * path. Can be an http connection to a remote machine with a host, port, and
+ * path. Or it can be an https connection to a remote machine with a host, port,
+ * path, cert, ca, key, and passphrase.
+ *
+ * @since 1.0.0
+ * @category Connection Types
+ */
+export const MobyConnectionOptions = Data.taggedEnum<MobyConnectionOptions>();
+
+/**
+ * @since 1.0.0
+ * @category Connection Constructors
+ * @example
+ *     import { SocketConnectionOptions } from "the-moby-effect/MobyConnection";
+ *     const connectionOptions = SocketConnectionOptions({
+ *         socketPath: "/var/run/docker.sock",
+ *     });
+ */
+export const SocketConnectionOptions = MobyConnectionOptions.socket;
+
+/**
+ * Connects to a remote machine over ssh. This specific ssh implementation uses
+ * the OpenSSH extension "ForwardOutLocalStream" (so you must being running an
+ * OpenSSH server or something that implements the "ForwardOutLocalStream"
+ * extension) that opens a connection to a UNIX domain socket at socketPath on
+ * the server.
+ *
+ * @since 1.0.0
+ * @category Connection Constructors
+ * @example
+ *     import { SshConnectionOptions } from "the-moby-effect/MobyConnection";
+ *     const connectionOptions = SshConnectionOptions({
+ *         host: "host.domain.com",
+ *         port: 2222,
+ *         username: "user",
+ *         password: "password",
+ *         remoteSocketPath: "/var/run/docker.sock",
+ *     });
+ */
+export const SshConnectionOptions = MobyConnectionOptions.ssh;
+
+/**
+ * @since 1.0.0
+ * @category Connection Constructors
+ * @example
+ *     import { HttpConnectionOptions } from "the-moby-effect/MobyConnection";
+ *     const connectionOptions = HttpConnectionOptions({
+ *         host: "host.domain.com",
+ *         port: 2375,
+ *         path: "/proxy-path",
+ *     });
+ */
+export const HttpConnectionOptions = MobyConnectionOptions.http;
+
+/**
+ * @since 1.0.0
+ * @category Connection Constructors
+ * @example
+ *     import { HttpsConnectionOptions } from "the-moby-effect/MobyConnection";
+ *     const connectionOptions = HttpsConnectionOptions({
+ *         host: "host.domain.com",
+ *         port: 2375,
+ *         path: "/proxy-path",
+ *         // passphrase: "password",
+ *         // ca: fs.readFileSync("ca.pem"),
+ *         // key: fs.readFileSync("key.pem"),
+ *         // cert: fs.readFileSync("cert.pem"),
+ *     });
+ */
+export const HttpsConnectionOptions = MobyConnectionOptions.https;
+
+/**
+ * From
+ * https://docs.docker.com/engine/reference/commandline/dockerd/#daemon-socket-option
+ *
+ * "The Docker client will honor the DOCKER_HOST environment variable to set the
+ * -H flag for the client"
+ *
+ * And then from
+ * https://docs.docker.com/engine/reference/commandline/dockerd/#bind-docker-to-another-hostport-or-a-unix-socket
+ *
+ * "-H accepts host and port assignment in the following format:
+ * `tcp://[host]:[port][path]` or `unix://path`
+ *
+ * For example:
+ *
+ * - `unix://path/to/socket` -> Unix socket located at path/to/socket
+ * - When -H is empty, it will default to the same value as when no -H was passed
+ *   in
+ * - `http://host:port/path` -> HTTP connection on host:port and prepend path to
+ *   all requests
+ * - `https://host:port/path` -> HTTPS connection on host:port and prepend path to
+ *   all requests
+ * - `ssh://me@example.com:22/var/run/docker.sock` -> SSH connection to
+ *   example.com on port 22
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const connectionOptionsFromUrl = (
+    dockerHost: string
+): Effect.Effect<MobyConnectionOptions, ConfigError.ConfigError, never> => {
+    const url: URL = new URL(dockerHost);
+
+    if (url.protocol === "unix:") {
+        return Effect.succeed(SocketConnectionOptions({ socketPath: url.pathname }));
+    }
+
+    if (url.protocol === "ssh:") {
+        return Effect.succeed(
+            SshConnectionOptions({
+                host: url.hostname,
+                username: url.username,
+                password: url.password,
+                remoteSocketPath: url.pathname,
+                port: url.port ? Number.parseInt(url.port) : 22,
+            })
+        );
+    }
+
+    if (url.protocol === "http:") {
+        return Effect.succeed(
+            HttpConnectionOptions({
+                host: url.hostname ?? "127.0.0.1",
+                port: url.port ? Number.parseInt(url.port) : 2375,
+                path: url.pathname,
+            })
+        );
+    }
+
+    if (url.protocol === "https:") {
+        return Effect.succeed(
+            HttpConnectionOptions({
+                host: url.hostname ?? "127.0.0.1",
+                port: url.port ? Number.parseInt(url.port) : 2376,
+                path: url.pathname,
+            })
+        );
+    }
+
+    if (url.protocol === "tcp:") {
+        const path: string = url.pathname;
+        const host: string = url.hostname ?? "127.0.0.0.1";
+        const port: number = url.port ? Number.parseInt(url.port) : 2375;
+        if (port === 2376) {
+            return Effect.succeed(HttpsConnectionOptions({ host, port, path }));
+        } else {
+            return Effect.succeed(HttpConnectionOptions({ host, port, path }));
+        }
+    }
+
+    // Any other protocols are not supported
+    return Effect.fail(ConfigError.InvalidData([""], `Unsupported protocol ${url.protocol}`));
+};
+
+/**
+ * Creates a MobyApi layer from the DOCKER_HOST environment variable as a url.
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const connectionOptionsFromDockerHostEnvironmentVariable: Effect.Effect<
+    MobyConnectionOptions,
+    ConfigError.ConfigError,
+    never
+> = Config.redacted("DOCKER_HOST")
+    .pipe(Config.withDefault(Redacted.make("unix:///var/run/docker.sock")))
+    .pipe(Config.map(Redacted.value))
+    .pipe(Effect.flatMap(connectionOptionsFromUrl));
+
+/**
+ * Creates a MobyApi layer from the platform default system socket location.
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const connectionOptionsFromPlatformSystemSocketDefault: Effect.Effect<
+    MobyConnectionOptions,
+    ConfigError.ConfigError,
+    never
+> = Function.pipe(
+    Match.value(process.platform),
+    Match.when("linux", () => Effect.succeed(SocketConnectionOptions({ socketPath: "/var/run/docker.sock" }))),
+    Match.when("darwin", () => Effect.succeed(SocketConnectionOptions({ socketPath: "/var/run/docker.sock" }))),
+    Match.when("win32", () => Effect.succeed(SocketConnectionOptions({ socketPath: "//./pipe/docker_engine" }))),
+    Match.orElse(() => Effect.fail(ConfigError.InvalidData([""], `Unsupported platform ${process.platform}`)))
+);
+
+/**
+ * Creates a MobyApi layer from the platform default system socket location.
+ *
+ * @since 1.0.0
+ * @category Constructors
+ */
+export const connectionOptionsFromUserSocketDefault: Effect.Effect<MobyConnectionOptions, never, Path.Path> =
+    Function.pipe(
+        Effect.all(
+            {
+                pathLazy: Path.Path,
+                osLazy: Effect.promise(() => import("node:os")),
+            },
+            { concurrency: 2 }
+        ),
+        Effect.map(({ osLazy, pathLazy }) =>
+            SocketConnectionOptions({
+                socketPath: pathLazy.join(osLazy.homedir(), ".docker", "run", "docker.sock"),
+            })
+        )
+    );

package/src/MobyConvey.ts

@@ -0,0 +1,26 @@
+/**
+ * Convenance utilities for Docker input and output streams.
+ *
+ * @since 1.0.0
+ */
+
+import * as sinksInternal from "./convey/Sinks.js";
+import * as streamsInternal from "./convey/Streams.js";
+
+/**
+ * @since 1.0.0
+ * @category Conveyance Sinks
+ */
+export const followProgressInConsole = sinksInternal.followProgressInConsole;
+
+/**
+ * @since 1.0.0
+ * @category Conveyance Sinks
+ */
+export const waitForProgressToComplete = sinksInternal.waitForProgressToComplete;
+
+/**
+ * @since 1.0.0
+ * @category Conveyance Streams
+ */
+export const packBuildContextIntoTarballStream = streamsInternal.packBuildContextIntoTarballStream;

package/src/MobyDemux.ts

@@ -0,0 +1,17 @@
+/**
+ * Demux utilities for different types of docker streams.
+ *
+ * @since 1.0.0
+ */
+
+/** @since 1.0.0 */
+export * from "./demux/Demux.js";
+
+/** @since 1.0.0 */
+export * from "./demux/Multiplexed.js";
+
+/** @since 1.0.0 */
+export * from "./demux/Raw.js";
+
+/** @since 1.0.0 */
+export * from "./demux/Stdio.js";

package/src/MobyEndpoints.ts

@@ -0,0 +1,50 @@
+/**
+ * Moby endpoints.
+ *
+ * @since 1.0.0
+ */
+
+/** @since 1.0.0 */
+export * from "./endpoints/Configs.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Containers.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Distribution.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Execs.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Images.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Networks.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Nodes.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Plugins.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Secrets.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Services.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Session.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Swarm.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/System.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Tasks.js";
+
+/** @since 1.0.0 */
+export * from "./endpoints/Volumes.js";

package/src/MobyEngine.ts

@@ -0,0 +1,8 @@
+/**
+ * Moby engine shortcut.
+ *
+ * @since 1.0.0
+ */
+
+/** @since 1.0.0 */
+export * from "./engines/Moby.js";

package/src/MobyPlatforms.ts

@@ -0,0 +1,68 @@
+/**
+ * Http client layers for all platforms.
+ *
+ * @since 1.0.0
+ */
+
+import * as agnosticInternal from "./platforms/Agnostic.js";
+import * as bunInternal from "./platforms/Bun.js";
+import * as denoInternal from "./platforms/Deno.js";
+import * as nodeInternal from "./platforms/Node.js";
+import * as undiciInternal from "./platforms/Undici.js";
+import * as webInternal from "./platforms/Web.js";
+
+/**
+ * Given the moby connection options, it will construct a layer that provides a
+ * http client that you could use to connect to your moby instance.
+ *
+ * @since 1.0.0
+ * @category Connection
+ */
+export const makeAgnosticHttpClientLayer = agnosticInternal.makeAgnosticHttpClientLayer;
+
+/**
+ * Given the moby connection options, it will construct a layer that provides a
+ * http client that you could use to connect to your moby instance. This is no
+ * different than the Node implementation currently.
+ *
+ * @since 1.0.0
+ * @category Connection
+ */
+export const makeBunHttpClientLayer = bunInternal.makeBunHttpClientLayer;
+
+/**
+ * Given the moby connection options, it will construct a layer that provides a
+ * http client that you could use to connect to your moby instance. This is no
+ * different than the Node implementation currently.
+ *
+ * @since 1.0.0
+ * @category Connection
+ */
+export const makeDenoHttpClientLayer = denoInternal.makeDenoHttpClientLayer;
+
+/**
+ * Given the moby connection options, it will construct a layer that provides a
+ * http client that you could use to connect to your moby instance.
+ *
+ * @since 1.0.0
+ * @category Connection
+ */
+export const makeNodeHttpClientLayer = nodeInternal.makeNodeHttpClientLayer;
+
+/**
+ * Given the moby connection options, it will construct a layer that provides a
+ * http client that you could use to connect to your moby instance.
+ *
+ * @since 1.0.0
+ * @category Connection
+ */
+export const makeUndiciHttpClientLayer = undiciInternal.makeUndiciHttpClientLayer;
+
+/**
+ * Given the moby connection options, it will construct a layer that provides a
+ * http client that you could use to connect to your moby instance.
+ *
+ * @since 1.0.0
+ * @category Connection
+ */
+export const makeWebHttpClientLayer = webInternal.makeWebHttpClientLayer;

package/src/MobySchemas.ts

@@ -0,0 +1,8 @@
+/**
+ * Moby schemas.
+ *
+ * @since 1.0.0
+ */
+
+/** @since 1.0.0 */
+export * from "./generated/index.js";

package/src/PodmanEngine.ts

@@ -0,0 +1,8 @@
+/**
+ * Podman engine shortcut.
+ *
+ * @since 1.0.0
+ */
+
+/** @since 1.0.0 */
+export * from "./engines/Podman.js";

package/src/Promises.ts

@@ -0,0 +1,63 @@
+/**
+ * Docker engine promises api
+ *
+ * @since 1.0.0
+ */
+
+import * as Chunk from "effect/Chunk";
+import * as Effect from "effect/Effect";
+import * as Function from "effect/Function";
+import * as Layer from "effect/Layer";
+import * as ManagedRuntime from "effect/ManagedRuntime";
+import * as Stream from "effect/Stream";
+import * as DockerEngine from "./engines/Docker.js";
+import * as MobyConvey from "./MobyConvey.js";
+import * as MobySchemas from "./MobySchemas.js";
+
+/**
+ * Create a promise client for the docker engine
+ *
+ * @since 1.0.0
+ * @category Promises
+ */
+export const promiseClient = async <E>(
+    layer: Layer.Layer<
+        Layer.Layer.Success<DockerEngine.DockerLayer>,
+        E | Layer.Layer.Error<DockerEngine.DockerLayer>,
+        Layer.Layer.Context<DockerEngine.DockerLayer>
+    >
+) => {
+    const managedRuntime = ManagedRuntime.make(layer);
+    const runtime = await managedRuntime.runtime();
+
+    return {
+        pull: Function.compose(DockerEngine.pull, Stream.toReadableStreamRuntime(runtime)),
+        build: Function.compose(DockerEngine.build, Stream.toReadableStreamRuntime(runtime)),
+        stop: Function.flow(DockerEngine.stop, managedRuntime.runPromise),
+        start: Function.flow(DockerEngine.start, managedRuntime.runPromise),
+        run: Function.flow(DockerEngine.run, managedRuntime.runPromise),
+        exec: Function.flow(DockerEngine.exec, managedRuntime.runPromise),
+        execNonBlocking: Function.flow(DockerEngine.execNonBlocking, managedRuntime.runPromise),
+        ps: Function.flow(DockerEngine.ps, managedRuntime.runPromise),
+        push: Function.flow(DockerEngine.push, Stream.toReadableStreamRuntime(runtime)),
+        images: Function.flow(DockerEngine.images, managedRuntime.runPromise),
+        search: Function.flow(DockerEngine.search, managedRuntime.runPromise),
+        version: Function.flow(DockerEngine.version, managedRuntime.runPromise),
+        info: Function.flow(DockerEngine.info, managedRuntime.runPromise),
+        ping: Function.flow(DockerEngine.ping, managedRuntime.runPromise),
+        pingHead: Function.flow(DockerEngine.pingHead, managedRuntime.runPromise),
+        packBuildContextIntoTarballStream: MobyConvey.packBuildContextIntoTarballStream,
+        followProgressInConsole: Function.flow(
+            Stream.fromReadableStream<MobySchemas.JSONMessage, unknown>,
+            MobyConvey.followProgressInConsole<unknown, Layer.Layer.Success<typeof layer>>,
+            Effect.map(Chunk.toReadonlyArray),
+            managedRuntime.runPromise
+        ),
+        waitForProgressToComplete: Function.flow(
+            Stream.fromReadableStream<MobySchemas.JSONMessage, unknown>,
+            MobyConvey.waitForProgressToComplete<unknown, Layer.Layer.Success<typeof layer>>,
+            Effect.map(Chunk.toReadonlyArray),
+            managedRuntime.runPromise
+        ),
+    };
+};