effect 4.0.2 → 4.0.3

package/dist/net/AddressResolver.d.ts

@@ -0,0 +1,145 @@
+/**
+ * Resolves host and port endpoints to socket addresses.
+ *
+ * The `AddressResolver` service turns a `Host.HostPort` or `host:port` string
+ * into socket addresses. Numeric hosts are converted without a lookup. IPv6
+ * literals with a named zone such as `fe80::1%eth0` get their scope ID from the host's
+ * network interfaces, and domain names are looked up with the `Dns` service.
+ * Runtime layers look up network interfaces; this module's layer requires
+ * only `Dns` and supports numeric zones only.
+ *
+ * @stability experimental
+ * @since 4.0.0
+ */
+import * as Arr from "../Array.ts";
+import * as Context from "../Context.ts";
+import * as Effect from "../Effect.ts";
+import * as Layer from "../Layer.ts";
+import * as Option from "../Option.ts";
+import * as Dns from "./Dns.ts";
+import * as Host from "./Host.ts";
+import * as NetAddress from "./NetAddress.ts";
+declare const AddressResolver_base: Context.ServiceClass<AddressResolver, "effect/net/AddressResolver", {
+    /**
+     * Resolves an endpoint to every matching socket address.
+     *
+     * **Details**
+     *
+     * - Socket addresses are returned as-is.
+     * - `host:port` strings and `{ host, port }` objects are converted like
+     *   `Host.hostPortFromInput`, failing with `NetAddressError` when invalid.
+     * - A `Host.HostPort` with a numeric host is converted without a lookup.
+     * - A `Host.HostPort` with a domain name is looked up with `Dns.lookup`, and
+     *   the port is attached to every address.
+     *
+     * Results keep the resolver's order and are filtered by the requested
+     * family, which does not apply to Unix-domain addresses.
+     *
+     * **Gotchas**
+     *
+     * Looked-up IPv6 link-local addresses (`fe80::/10`) are skipped, because
+     * lookups do not report the interface they belong to and they cannot be
+     * connected to without it. Names that resolve only to such addresses, such
+     * as some `.local` names, fail with a `NetAddress.NetAddressError`; use an
+     * address with a zone such as `fe80::1%en0` instead.
+     */
+    resolve<F extends NetAddress.IpFamily>(target: NetAddress.InetAddress | Host.HostPortInput, options: ResolveOptions & {
+        readonly family: F;
+    }): Effect.Effect<Arr.NonEmptyReadonlyArray<NetAddress.Inet<NetAddress.FamilyAddress<F>>>, Dns.DnsError | NetAddress.NetAddressError>;
+    resolve(target: NetAddress.InetAddress | Host.HostPortInput, options?: ResolveOptions): Effect.Effect<Arr.NonEmptyReadonlyArray<NetAddress.InetAddress>, Dns.DnsError | NetAddress.NetAddressError>;
+    resolve(target: NetAddress.SocketAddress | Host.HostPortInput, options?: ResolveOptions): Effect.Effect<Arr.NonEmptyReadonlyArray<NetAddress.SocketAddress>, Dns.DnsError | NetAddress.NetAddressError>;
+}>;
+/**
+ * Service that resolves endpoints to internet and socket addresses.
+ *
+ * **Details**
+ *
+ * Every operation either returns at least one address or fails. Lookups fail
+ * with a `Dns.DnsError`, and hosts that cannot be converted, such as IPv6
+ * literals with an unknown zone or numeric addresses outside the requested
+ * family, fail with a `NetAddress.NetAddressError`.
+ *
+ * @stability experimental
+ * @category services
+ * @since 4.0.0
+ */
+export declare class AddressResolver extends AddressResolver_base {
+}
+/**
+ * Options for resolving an endpoint. Without a `family`, addresses of both
+ * families are returned.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export interface ResolveOptions {
+    readonly family?: NetAddress.IpFamily | undefined;
+}
+/**
+ * Looks up the IPv6 scope ID of a network interface by name.
+ *
+ * **Details**
+ *
+ * Returns `None` for interfaces that do not exist or have no IPv6 scope ID, and
+ * fails when the interfaces cannot be listed.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export type ScopeIdLookup = (name: string) => Effect.Effect<Option.Option<number>, NetAddress.NetAddressError>;
+/**
+ * Options for creating an `AddressResolver`.
+ *
+ * **Details**
+ *
+ * `scopeId` is called whenever an IPv6 literal with a named zone such as
+ * `fe80::1%eth0` is resolved, so interfaces added or recreated while the
+ * program runs are found. Without it, only numeric zones such as `fe80::1%2`
+ * are supported.
+ *
+ * @stability experimental
+ * @category models
+ * @since 4.0.0
+ */
+export interface MakeOptions {
+    readonly scopeId?: ScopeIdLookup | undefined;
+}
+/**
+ * Creates an `AddressResolver` that looks up domain names with a `Dns`
+ * service.
+ *
+ * **Example** (Resolving an endpoint with a static resolver)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Result } from "effect"
+ * import { AddressResolver, Dns, NetAddress } from "effect/net"
+ *
+ * const dns = Result.getOrThrow(Dns.makeStatic({
+ *   hosts: { "db.internal": ["10.0.0.5"] }
+ * }))
+ * const resolver = AddressResolver.make(dns)
+ *
+ * const program = resolver.resolve("db.internal:5432").pipe(
+ *   Effect.map((addresses) => addresses.map(NetAddress.formatInet))
+ * )
+ *
+ * await Effect.runPromise(program) // => ["10.0.0.5:5432"]
+ * ```
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.0.0
+ */
+export declare const make: (dns: Dns.Dns["Service"], options?: MakeOptions) => AddressResolver["Service"];
+/**
+ * Creates a layer that provides an `AddressResolver` using the `Dns` service.
+ *
+ * @stability experimental
+ * @category layers
+ * @since 4.0.0
+ */
+export declare const layer: (options?: MakeOptions) => Layer.Layer<AddressResolver, never, Dns.Dns>;
+export {};
+//# sourceMappingURL=AddressResolver.d.ts.map

package/dist/net/AddressResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AddressResolver.d.ts","sourceRoot":"","sources":["../../src/net/AddressResolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,GAAG,MAAM,aAAa,CAAA;AAClC,OAAO,KAAK,OAAO,MAAM,eAAe,CAAA;AACxC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,KAAK,MAAM,aAAa,CAAA;AACpC,OAAO,KAAK,MAAM,MAAM,cAAc,CAAA;AACtC,OAAO,KAAK,GAAG,MAAM,UAAU,CAAA;AAC/B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAA;AACjC,OAAO,KAAK,UAAU,MAAM,iBAAiB,CAAA;;IAiB3C;;;;;;;;;;;;;;;;;;;;;;OAsBG;YACK,CAAC,SAAS,UAAU,CAAC,QAAQ,UAC3B,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC,aAAa,WAC1C,cAAc,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;KAAE,GAC/C,MAAM,CAAC,MAAM,CACd,GAAG,CAAC,qBAAqB,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,EACvE,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC,eAAe,CAC1C;oBAES,UAAU,CAAC,WAAW,GAAG,IAAI,CAAC,aAAa,YACzC,cAAc,GACvB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,UAAU,CAAC,WAAW,CAAC,EAAE,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC,eAAe,CAAC;oBAEpG,UAAU,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,YAC3C,cAAc,GACvB,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,qBAAqB,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,GAAG,CAAC,QAAQ,GAAG,UAAU,CAAC,eAAe,CAAC;;AApDlH;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAgB,SAAQ,oBAuCH;CAAG;AAErC;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,QAAQ,GAAG,SAAS,CAAA;CAClD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,eAAe,CAAC,CAAA;AAE9G;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,SAAS,CAAA;CAC7C;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,IAAI,QAAS,GAAG,CAAC,GAAG,CAAC,SAAS,CAAC,YAAY,WAAW,KAAG,eAAe,CAAC,SAAS,CAwD9F,CAAA;AAED;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,aAAc,WAAW,KAAG,KAAK,CAAC,KAAK,CAAC,eAAe,EAAE,KAAK,EAAE,GAAG,CAAC,GAAG,CACQ,CAAA"}

package/dist/net/AddressResolver.js

@@ -0,0 +1,114 @@
+/**
+ * Resolves host and port endpoints to socket addresses.
+ *
+ * The `AddressResolver` service turns a `Host.HostPort` or `host:port` string
+ * into socket addresses. Numeric hosts are converted without a lookup. IPv6
+ * literals with a named zone such as `fe80::1%eth0` get their scope ID from the host's
+ * network interfaces, and domain names are looked up with the `Dns` service.
+ * Runtime layers look up network interfaces; this module's layer requires
+ * only `Dns` and supports numeric zones only.
+ *
+ * @stability experimental
+ * @since 4.0.0
+ */
+import * as Arr from "../Array.js";
+import * as Context from "../Context.js";
+import * as Effect from "../Effect.js";
+import * as Layer from "../Layer.js";
+import * as Option from "../Option.js";
+import * as Dns from "./Dns.js";
+import * as Host from "./Host.js";
+import * as NetAddress from "./NetAddress.js";
+/**
+ * Service that resolves endpoints to internet and socket addresses.
+ *
+ * **Details**
+ *
+ * Every operation either returns at least one address or fails. Lookups fail
+ * with a `Dns.DnsError`, and hosts that cannot be converted, such as IPv6
+ * literals with an unknown zone or numeric addresses outside the requested
+ * family, fail with a `NetAddress.NetAddressError`.
+ *
+ * @stability experimental
+ * @category services
+ * @since 4.0.0
+ */
+export class AddressResolver extends /*#__PURE__*/Context.Service()("effect/net/AddressResolver") {}
+const inFamily = (address, family) => family === undefined || NetAddress.isFamily(address, family) ? Effect.succeed(Arr.of(address)) : Effect.fail(new NetAddress.NetAddressError({
+  input: address,
+  message: `expected an ${family} address`
+}));
+/**
+ * Creates an `AddressResolver` that looks up domain names with a `Dns`
+ * service.
+ *
+ * **Example** (Resolving an endpoint with a static resolver)
+ *
+ * ```ts import.meta.vitest
+ * import { Effect, Result } from "effect"
+ * import { AddressResolver, Dns, NetAddress } from "effect/net"
+ *
+ * const dns = Result.getOrThrow(Dns.makeStatic({
+ *   hosts: { "db.internal": ["10.0.0.5"] }
+ * }))
+ * const resolver = AddressResolver.make(dns)
+ *
+ * const program = resolver.resolve("db.internal:5432").pipe(
+ *   Effect.map((addresses) => addresses.map(NetAddress.formatInet))
+ * )
+ *
+ * await Effect.runPromise(program) // => ["10.0.0.5:5432"]
+ * ```
+ *
+ * @stability experimental
+ * @category constructors
+ * @since 4.0.0
+ */
+export const make = (dns, options) => {
+  const scopeId = options?.scopeId;
+  const fromLiteral = (host, port) => {
+    if (NetAddress.isIpAddress(host)) return Effect.fromResult(NetAddress.inetAddress(host, port));
+    const zone = host.slice(host.indexOf("%") + 1);
+    if (scopeId === undefined || /^\d+$/.test(zone)) {
+      return Effect.fromResult(NetAddress.inetAddressFromHostString(host, port));
+    }
+    return Effect.flatMap(scopeId(zone), id => Effect.fromResult(NetAddress.inetAddressFromHostString(host, port, Option.isSome(id) ? new Map([[zone, id.value]]) : undefined)));
+  };
+  const resolve = (target, options) => {
+    const family = options?.family;
+    if (NetAddress.isUnixPathAddress(target)) return Effect.succeed(Arr.of(target));
+    if (NetAddress.isInetAddress(target)) return inFamily(target, family);
+    if (!Host.isHostPort(target)) {
+      return Effect.flatMap(Effect.fromResult(Host.hostPortFromInput(target)), endpoint => resolve(endpoint, options));
+    }
+    const {
+      host,
+      port
+    } = target;
+    if (NetAddress.isIpAddress(host) || NetAddress.isScopedIpv6Literal(host)) {
+      return Effect.flatMap(fromLiteral(host, port), address => inFamily(address, family));
+    }
+    return Effect.flatMap(dns.lookup(host, {
+      family
+    }), addresses => {
+      // Lookups do not report the scope that a link-local IPv6 address needs.
+      const usable = addresses.filter(address => !(NetAddress.isIpv6Address(address) && NetAddress.isLinkLocal(address)));
+      return Arr.isReadonlyArrayNonEmpty(usable) ? Effect.succeed(Arr.map(usable, address => NetAddress.inetAddressUnsafe(address, port))) : Effect.fail(new NetAddress.NetAddressError({
+        input: host,
+        message: "only link-local IPv6 addresses were found, and lookups do not report their scope"
+      }));
+    });
+  };
+  return AddressResolver.of({
+    resolve: resolve
+  });
+};
+/**
+ * Creates a layer that provides an `AddressResolver` using the `Dns` service.
+ *
+ * @stability experimental
+ * @category layers
+ * @since 4.0.0
+ */
+export const layer = options => Layer.effect(AddressResolver, Effect.map(Effect.service(Dns.Dns), dns => make(dns, options)));
+//# sourceMappingURL=AddressResolver.js.map

package/dist/net/AddressResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AddressResolver.js","names":[],"sources":["../../src/net/AddressResolver.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}