@alchemy-unifi/network 0.0.1 → 0.1.0

package/src/Connection.ts

@@ -0,0 +1,185 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as HttpClient from "effect/http/HttpClient";
+import * as Layer from "effect/Layer";
+import * as Predicate from "effect/Predicate";
+import * as Schedule from "effect/Schedule";
+import * as RateLimiter from "effect/persistence/RateLimiter";
+import * as Scope from "effect/Scope";
+import { type Connection, UnifiNetworkCredentials } from "./Credentials.ts";
+import * as UnifiHttpClient from "./HttpClient.ts";
+
+export const SITE_MANAGER_URL = "https://api.ui.com";
+
+/** Integration API base URL through the cloud connector. */
+export const connectorBaseUrl = (consoleId: string) =>
+	`${SITE_MANAGER_URL}/v1/connector/consoles/${encodeURIComponent(consoleId)}/proxy/network/integration`;
+
+/** Integration API base URLs to try for a connection: a UniFi OS console's, then a standalone controller's. */
+export const candidateBaseUrls = (connection: Connection): ReadonlyArray<string> =>
+	connection.type === "remote"
+		? [connectorBaseUrl(connection.consoleId)]
+		: [`${connection.url}/proxy/network/integration`, `${connection.url}/integration`];
+
+/** The SDK's default retry policy, minus certificate failures, which retrying won't fix. */
+const probeRetry: Sdk.Retry.Policy = (lastError) => {
+	const defaults = Sdk.Retry.makeDefault(lastError);
+	return {
+		...defaults,
+		while: (error) => (defaults.while?.(error) ?? false) && !UnifiHttpClient.isCertificateError(error),
+	};
+};
+
+/** The connector allows 100 requests/minute per console; stay under it. */
+const REMOTE_REQUESTS_PER_MINUTE = 90;
+
+/** A connection whose base URL has been found and whose API key works. */
+export interface Established {
+	readonly baseUrl: string;
+	readonly applicationVersion: string;
+	/** What SDK operations need: credentials for {@link baseUrl} and a client with the connection's TLS settings. */
+	readonly services: Context.Context<Sdk.Credentials | HttpClient.HttpClient>;
+}
+
+/** Joins an error's message with its causes' (e.g. a transport error and the TLS failure behind it). */
+export const describeError = (error: unknown): string => {
+	const messages: string[] = [];
+	for (let e: unknown = error, depth = 0; e !== undefined && e !== null && depth < 5; depth++) {
+		const message = typeof e === "object" && "message" in e ? String(e.message) : String(e);
+		if (message !== "" && !messages.some((m) => m.includes(message))) messages.push(message);
+		e = typeof e === "object" && "cause" in e ? e.cause : undefined;
+	}
+	return messages.join(": ") || "unknown error";
+};
+
+const describeTarget = (connection: Connection) =>
+	connection.type === "remote" ? `console ${connection.consoleId} via ${SITE_MANAGER_URL}` : connection.url;
+
+const rateLimited = (client: HttpClient.HttpClient, key: string) =>
+	Effect.gen(function* () {
+		const limiter = yield* RateLimiter.make.pipe(Effect.provide(RateLimiter.layerStoreMemory));
+		const wait = RateLimiter.sleep(limiter, {
+			algorithm: "token-bucket",
+			window: "1 minute",
+			limit: REMOTE_REQUESTS_PER_MINUTE,
+			key,
+		}).pipe(Effect.orDie);
+		return HttpClient.transform(client, (response) => Effect.andThen(wait, response));
+	});
+
+/**
+ * Builds a client for the connection and finds the Integration API: local
+ * connections try the console path, then the standalone controller path.
+ * Fails with a `ConfigError` describing what went wrong. `options.client`
+ * replaces the TLS-configured client (for tests).
+ */
+export const connect = (
+	connection: Connection,
+	options: { readonly client?: HttpClient.HttpClient } = {},
+): Effect.Effect<Established, Sdk.ConfigError, Scope.Scope> =>
+	Effect.gen(function* () {
+		const base = options.client ?? (yield* UnifiHttpClient.make(connection.type === "local" ? connection : {}));
+		const client =
+			connection.type === "remote" ? yield* rateLimited(base, `connector:${connection.consoleId}`) : base;
+		const servicesFor = (baseUrl: string) =>
+			Context.make(Sdk.Credentials, Effect.succeed({ baseUrl, apiKey: connection.apiKey })).pipe(
+				Context.add(HttpClient.HttpClient, client),
+			);
+		const candidates = candidateBaseUrls(connection);
+		for (const baseUrl of candidates) {
+			const services = servicesFor(baseUrl);
+			const info = yield* Sdk.getInfo({}).pipe(
+				Effect.provide(services),
+				Sdk.Retry.policy(probeRetry),
+				Effect.map(({ applicationVersion }) => ({ baseUrl, applicationVersion, services })),
+				Effect.catchTag("NotFound", () => Effect.undefined),
+				Effect.mapError((error) =>
+					Sdk.ConfigError.make({
+						message:
+							error._tag === "Unauthorized" || error._tag === "Forbidden"
+								? `${describeTarget(connection)} rejected the API key (${error._tag}).`
+								: `Could not connect to ${describeTarget(connection)}: ${describeError(error)}`,
+					}),
+				),
+			);
+			if (info !== undefined) return info;
+		}
+		return yield* Sdk.ConfigError.make({
+			message:
+				connection.type === "remote"
+					? `The cloud connector found no UniFi Network application on console ${connection.consoleId}.`
+					: `No UniFi Network Integration API at ${connection.url} (tried ${candidates.join(", ")}). Use the console's root URL, e.g. https://192.168.1.1.`,
+		});
+	});
+
+const majorMinor = (version: string) => version.split(".").slice(0, 2).join(".");
+
+/** Patch releases routinely ship without a published spec, so only major.minor drift is worth a warning. */
+export const checkVersion = (applicationVersion: string) =>
+	majorMinor(applicationVersion) === majorMinor(Sdk.SPEC_VERSION)
+		? Effect.void
+		: Effect.logWarning(
+				`UniFi Network ${applicationVersion} is newer or older than the API spec this provider was built from (${Sdk.SPEC_VERSION}). Resources may not behave as documented.`,
+			);
+
+/**
+ * The profile's established connection, created on first use and shared for
+ * the rest of the run. Provider-private: its `HttpClient` and SDK
+ * `Credentials` never enter the stack's context, so they can't replace other
+ * providers' clients.
+ */
+export class UnifiNetworkConnection extends Context.Service<
+	UnifiNetworkConnection,
+	Effect.Effect<Established, Sdk.ConfigError>
+>()("UnifiNetwork::Connection") {
+	/** Alchemy's tag for environment services, which lets stack bodies (and so lookups) require this one. */
+	declare readonly kind: "Environment";
+}
+
+export const layer = Layer.effect(
+	UnifiNetworkConnection,
+	Effect.gen(function* () {
+		const credentials = yield* UnifiNetworkCredentials;
+		const scope = yield* Effect.scope;
+		return yield* Effect.cached(
+			credentials.pipe(
+				Effect.flatMap(({ connection }) => connect(connection)),
+				Effect.tap(({ applicationVersion }) => checkVersion(applicationVersion)),
+				Scope.provide(scope),
+			),
+		);
+	}),
+);
+
+/**
+ * The 422 "Configured network does not exist" the console answers requests
+ * with, on any endpoint, for a moment while networks are created or deleted
+ * anywhere on it (seen on the test controller under parallel tests, for
+ * network, zone and policy requests alike). It's never a real error, so it's
+ * retried; other 422s are.
+ */
+const isStaleNetworkState = (error: unknown) =>
+	Predicate.hasProperty(error, "_tag") &&
+	error._tag === "UnprocessableEntity" &&
+	Predicate.hasProperty(error, "message") &&
+	typeof error.message === "string" &&
+	error.message.includes("Configured network does not exist");
+
+/** Runs SDK operations against the profile's console, retrying the console's transient stale-network 422. */
+export const withConnection = <A, E, R>(
+	effect: Effect.Effect<A, E, R>,
+): Effect.Effect<
+	A,
+	E | Sdk.ConfigError,
+	Exclude<R, Sdk.Credentials | HttpClient.HttpClient> | UnifiNetworkConnection
+> =>
+	Effect.gen(function* () {
+		const { services } = yield* yield* UnifiNetworkConnection;
+		return yield* Effect.provide(effect, services).pipe(
+			Effect.retry({
+				while: isStaleNetworkState,
+				schedule: Schedule.spaced("500 millis").pipe(Schedule.upTo({ times: 10 })),
+			}),
+		);
+	});

package/src/Credentials.ts

@@ -0,0 +1,85 @@
+import { ConfigError } from "@alchemy-unifi/network-sdk";
+import { deferUntilFirstUse, orDieCredentialsUnavailable, resolveProviderConfig } from "alchemy/Auth/Resolve";
+import * as Context from "effect/Context";
+import * as Effect from "effect/Effect";
+import * as Layer from "effect/Layer";
+import type * as Redacted from "effect/Redacted";
+import { UNIFI_NETWORK_AUTH_PROVIDER_NAME, type UnifiNetworkAuthConfig } from "./AuthConfig.ts";
+
+/** A console or self-hosted controller reached directly, e.g. `https://192.168.1.1`. */
+export interface LocalConnection {
+	readonly type: "local";
+	/** Origin of the console, without the Integration API path. */
+	readonly url: string;
+	readonly apiKey: Redacted.Redacted<string>;
+	/**
+	 * Accept the server only if a certificate in its chain has this SHA-256
+	 * fingerprint (`AB:CD:…`), whether or not Node trusts it.
+	 */
+	readonly certFingerprint?: string | undefined;
+	/** Skip TLS verification entirely. */
+	readonly insecure: boolean;
+}
+
+/** A console reached through the `api.ui.com` cloud connector. */
+export interface RemoteConnection {
+	readonly type: "remote";
+	readonly consoleId: string;
+	readonly apiKey: Redacted.Redacted<string>;
+}
+
+export type Connection = LocalConnection | RemoteConnection;
+
+/** Where credentials came from: a named Alchemy profile, or `UNIFI_*` environment variables. */
+export type CredentialsSource = { readonly type: "profile"; readonly profile: string } | { readonly type: "env" };
+
+export interface ResolvedCredentials {
+	readonly connection: Connection;
+	/**
+	 * Site used by resources that don't set `site`, by internal reference
+	 * (e.g. `default`) or name. Unset means the console's only site; it's only
+	 * needed on consoles hosting several.
+	 */
+	readonly site?: string | undefined;
+	readonly source: CredentialsSource;
+}
+
+/**
+ * Lazily-resolved credentials for the active profile (or the environment).
+ * The service value is an Effect so nothing resolves at Layer construction;
+ * handlers run `yield* yield* UnifiNetworkCredentials`.
+ */
+export class UnifiNetworkCredentials extends Context.Service<
+	UnifiNetworkCredentials,
+	Effect.Effect<ResolvedCredentials>
+>()("UnifiNetwork::Credentials") {
+	/** Alchemy's tag for credentials services, which lets stack bodies require this one. */
+	declare readonly kind: "Credentials";
+}
+
+/**
+ * Resolves {@link UnifiNetworkCredentials} through the `UnifiNetwork` auth
+ * provider: environment variables when they're all set, otherwise the
+ * selected Alchemy profile. Resolution is deferred to first use and cached.
+ */
+export const fromAuthProvider = () =>
+	Layer.effect(
+		UnifiNetworkCredentials,
+		Effect.gen(function* () {
+			const deferred = yield* resolveProviderConfig<UnifiNetworkAuthConfig, ResolvedCredentials>(
+				UNIFI_NETWORK_AUTH_PROVIDER_NAME,
+			).pipe(
+				Effect.flatMap(({ profileName, resolve }) =>
+					resolve.pipe(
+						Effect.mapError((e: { readonly message: string }) =>
+							ConfigError.make({
+								message: `Failed to resolve UniFi Network credentials from ${profileName === undefined ? "the environment" : `profile '${profileName}'`}: ${e.message}`,
+							}),
+						),
+					),
+				),
+				deferUntilFirstUse,
+			);
+			return yield* deferred.pipe(orDieCredentialsUnavailable(UNIFI_NETWORK_AUTH_PROVIDER_NAME), Effect.cached);
+		}),
+	);

package/src/DnsPolicy.ts

@@ -0,0 +1,181 @@
+import * as Sdk from "@alchemy-unifi/network-sdk";
+import { Unowned } from "alchemy/AdoptPolicy";
+import type { Diff } from "alchemy/Diff";
+import * as Provider from "alchemy/Provider";
+import { Resource } from "alchemy/Resource";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import { withConnection } from "./Connection.ts";
+import { type DistributiveOmit, isCurrent, omitKeys } from "./internal/Fields.ts";
+import { plannedString, UNKNOWN } from "./internal/Plan.ts";
+import { captureServices } from "./internal/Services.ts";
+import type { Providers } from "./Providers.ts";
+import * as ReadCache from "./ReadCache.ts";
+import { resolveSite } from "./Site.ts";
+
+/**
+ * Props are the Integration API's DNS policy body plus `site`. `type` picks
+ * the kind: a record (`"A_RECORD"`, `"AAAA_RECORD"`, `"CNAME_RECORD"`,
+ * `"MX_RECORD"`, `"SRV_RECORD"`, `"TXT_RECORD"`) or `"FORWARD_DOMAIN"`
+ * (send a domain's queries to another DNS server).
+ */
+export type DnsPolicyProps = Sdk.CreateOrUpdateDNSPolicy & {
+	/** Site to create the policy in. @default the profile's site, else the console's only site */
+	site?: string;
+};
+
+export interface DnsPolicyAttributes {
+	siteId: string;
+	dnsPolicyId: string;
+	type: DnsPolicyProps["type"];
+	domain: string;
+	/** The whole policy as the console reports it, so `alchemy drift` sees any change. */
+	config: DistributiveOmit<Sdk.DNSPolicy, "id" | "metadata">;
+}
+
+export interface DnsPolicy extends Resource<
+	"UnifiNetwork.DnsPolicy",
+	DnsPolicyProps,
+	DnsPolicyAttributes,
+	never,
+	Providers
+> {}
+
+const loadPolicies = (siteId: string) => withConnection(Stream.runCollect(Sdk.getDnsPolicyPage.items({ siteId })));
+const policiesKey = ReadCache.key<ReadonlyArray<Sdk.DNSPolicy>, Effect.Error<ReturnType<typeof loadPolicies>>>(
+	"dnsPolicies",
+);
+
+/** A site's DNS policies, listed once per run. */
+export const listDnsPolicies = (siteId: string) => ReadCache.cached(policiesKey, siteId, loadPolicies(siteId));
+
+const toAttributes = (siteId: string, policy: Sdk.DNSPolicy): DnsPolicyAttributes => {
+	const { id, metadata: _metadata, ...config } = policy;
+	return { siteId, dnsPolicyId: id, type: policy.type, domain: policy.domain, config };
+};
+
+/** Fields the console reports but rejects in request bodies. */
+const READ_ONLY = ["id", "metadata"];
+
+/** A policy by ID, from the run's cached list, which returns whole policies (one request for every policy in a plan). */
+const getPolicy = (siteId: string, dnsPolicyId: string) =>
+	listDnsPolicies(siteId).pipe(Effect.map((policies) => policies.find((p) => p.id === dnsPolicyId)));
+
+/**
+ * The existing policy `body` describes: the only one with its type and
+ * domain, or, when a domain has several records of that type (e.g. two A
+ * records), the only one of those whose other fields match too.
+ */
+const findExisting = (policies: ReadonlyArray<Sdk.DNSPolicy>, body: Sdk.CreateOrUpdateDNSPolicy) => {
+	const sameName = policies.filter((p) => p.type === body.type && p.domain === body.domain);
+	const candidates = sameName.length > 1 ? sameName.filter((p) => isCurrent(body, omitKeys(p, READ_ONLY))) : sameName;
+	const [policy] = candidates;
+	return candidates.length === 1 ? policy : undefined;
+};
+
+/**
+ * A local DNS record or forwarding rule on the gateway. DNS policies have no
+ * name, so existing ones are adopted with `--adopt` by type and domain (and,
+ * when a domain has several records of that type, by their values).
+ * Changing `type` updates the policy in place.
+ *
+ * @example
+ * ```ts
+ * import * as UnifiNetwork from "@alchemy-unifi/network";
+ * import * as Alchemy from "alchemy";
+ * import * as Effect from "effect/Effect";
+ *
+ * export default Alchemy.Stack(
+ * 	"HomeNetwork",
+ * 	{ providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
+ * 	Effect.gen(function* () {
+ * 		yield* UnifiNetwork.DnsPolicy("home-assistant", {
+ * 			type: "A_RECORD",
+ * 			enabled: true,
+ * 			domain: "ha.home.arpa",
+ * 			ipv4Address: "192.168.2.20",
+ * 			ttlSeconds: 300,
+ * 		});
+ * 	}),
+ * );
+ * ```
+ */
+export const DnsPolicy = Resource<DnsPolicy>("UnifiNetwork.DnsPolicy");
+
+export const DnsPolicyProvider = () =>
+	Provider.effect(
+		DnsPolicy,
+		Effect.gen(function* () {
+			const run = yield* captureServices;
+
+			return DnsPolicy.Provider.of({
+				list: () =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite();
+							return (yield* listDnsPolicies(site.id)).map((policy) => toAttributes(site.id, policy));
+						}),
+					),
+
+				read: ({ olds, output }) =>
+					run(
+						Effect.gen(function* () {
+							if (output !== undefined) {
+								const policy = yield* getPolicy(output.siteId, output.dnsPolicyId);
+								return policy === undefined ? undefined : toAttributes(output.siteId, policy);
+							}
+							const site = yield* resolveSite(olds.site);
+							const { site: _site, ...body } = olds;
+							const policy = findExisting(yield* listDnsPolicies(site.id), body);
+							return policy === undefined ? undefined : Unowned(toAttributes(site.id, policy));
+						}),
+					),
+
+				diff: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const siteProp = plannedString(news, "site");
+							if (output === undefined || siteProp === UNKNOWN) return undefined;
+							const site = yield* resolveSite(siteProp);
+							if (site.id !== output.siteId) return { action: "replace" } satisfies Diff;
+							return undefined;
+						}),
+					),
+
+				reconcile: ({ news, output }) =>
+					run(
+						Effect.gen(function* () {
+							const site = yield* resolveSite(news.site);
+							const { site: _site, ...body } = news;
+							const observed =
+								output !== undefined && output.siteId === site.id
+									? yield* getPolicy(site.id, output.dnsPolicyId)
+									: undefined;
+							const write = ReadCache.invalidating(policiesKey, site.id);
+							if (observed === undefined) {
+								const created = yield* withConnection(
+									Sdk.createDnsPolicy({ siteId: site.id, body }),
+								).pipe(write);
+								return toAttributes(site.id, created);
+							}
+							if (isCurrent(body, omitKeys(observed, READ_ONLY))) return toAttributes(site.id, observed);
+							const updated = yield* withConnection(
+								Sdk.updateDnsPolicy({ siteId: site.id, dnsPolicyId: observed.id, body }),
+							).pipe(write);
+							return toAttributes(site.id, updated);
+						}),
+					),
+
+				delete: ({ output }) =>
+					run(
+						withConnection(
+							Sdk.deleteDnsPolicy({ siteId: output.siteId, dnsPolicyId: output.dnsPolicyId }),
+						).pipe(
+							Effect.asVoid,
+							Effect.catchTag("NotFound", () => Effect.void),
+							ReadCache.invalidating(policiesKey, output.siteId),
+						),
+					),
+			});
+		}),
+	);