@expandai/sdk 0.20.1 → 0.20.2

package/src/Tunnel/LocalTarget.ts

@@ -0,0 +1,153 @@
+import { homedir } from 'node:os'
+import { FileSystem, Path } from '@effect/platform'
+import type { PlatformError } from '@effect/platform/Error'
+import { Data, Effect, Match, Option } from 'effect'
+import { ExpandLocalTargetError } from '../Error.js'
+
+/** Something on this machine the Expand API cannot reach without a tunnel. */
+export type LocalTarget = Data.TaggedEnum<{
+	/** A server already listening on a loopback port. `host` is dialled as written; `path` includes the query and fragment for browser navigation. */
+	Port: { readonly host: string; readonly port: number; readonly path: string }
+	File: { readonly path: string }
+	Directory: { readonly path: string }
+}>
+export const LocalTarget = Data.taggedEnum<LocalTarget>()
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '0.0.0.0'])
+const LOOPBACK_PREFIX = /^(localhost|127\.0\.0\.1|\[::1\]|0\.0\.0\.0)(?=[:/?#]|$)/iu
+
+function parseUrl(input: string): Option.Option<URL> {
+	// A schemeless `localhost:3000/x` is plainly local, and only ever a plaintext dev server.
+	const candidate = LOOPBACK_PREFIX.test(input) ? `http://${input}` : input
+	return URL.canParse(candidate) ? Option.some(new URL(candidate)) : Option.none()
+}
+
+// TLS dev servers are not tunnelled: the client dials plaintext, so `https://localhost` would only
+// ever get a connection reset.
+function isHttpLoopback(url: URL): boolean {
+	return url.protocol === 'http:' && LOOPBACK_HOSTS.has(url.hostname)
+}
+
+/** True for `http://localhost…` and friends — input that only a local tunnel can serve. */
+export function isLoopbackUrl(input: string): boolean {
+	return Option.exists(parseUrl(input), (url) => isHttpLoopback(url))
+}
+
+/** Preserves filesystem failures instead of treating unreadable paths as missing files. */
+function localTargetFileError(input: string, cause: PlatformError): ExpandLocalTargetError {
+	const details = Match.value(cause).pipe(
+		Match.withReturnType<Pick<ExpandLocalTargetError, 'reason' | 'message'>>(),
+		Match.when({ _tag: 'SystemError', reason: 'NotFound' }, () => ({
+			reason: 'NotFound',
+			message: `Local path "${input}" was not found. Check the path and try again.`,
+		})),
+		Match.when({ _tag: 'SystemError', reason: 'PermissionDenied' }, () => ({
+			reason: 'PermissionDenied',
+			message: `Cannot read "${input}": permission denied. Check the file or folder permissions.`,
+		})),
+		Match.tag('SystemError', () => ({
+			reason: 'Unavailable',
+			message: `Cannot access local path "${input}". ${cause.message}`,
+		})),
+		Match.orElse(() => ({
+			reason: 'InvalidInput',
+			message: `Invalid local path "${input}". Pass a file or folder path on this machine.`,
+		})),
+	)
+	return new ExpandLocalTargetError({ input, cause, ...details })
+}
+
+/** Canonicalizes a directory before serving it and refuses anything containing the home folder. */
+export const resolveSafeDirectory = Effect.fn('LocalTarget.resolveSafeDirectory')(function* (input: string) {
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const directory = yield* fs.realPath(input).pipe(Effect.mapError((cause) => localTargetFileError(input, cause)))
+	const home = yield* fs.realPath(homedir()).pipe(Effect.orDie)
+	const relativeHome = path.relative(directory, home)
+	const containsHome =
+		!path.isAbsolute(relativeHome) && relativeHome !== '..' && !relativeHome.startsWith(`..${path.sep}`)
+	if (containsHome) {
+		return yield* new ExpandLocalTargetError({
+			reason: 'UnsafeDirectory',
+			input,
+			message: `Refusing to share "${input}" because it contains your home folder. Choose a specific project folder or file.`,
+		})
+	}
+	return directory
+})
+
+const resolveFileTarget = Effect.fn('LocalTarget.resolveFileTarget')(function* (input: string, filePath: string) {
+	const fs = yield* FileSystem.FileSystem
+	const path = yield* Path.Path
+	const expanded = /^~(?=$|[/\\])/u.test(filePath) ? path.join(homedir(), filePath.slice(1)) : filePath
+	const resolved = path.resolve(expanded)
+	const info = yield* fs.stat(resolved).pipe(Effect.mapError((cause) => localTargetFileError(input, cause)))
+	if (info.type !== 'File' && info.type !== 'Directory') {
+		return yield* new ExpandLocalTargetError({
+			reason: 'UnsupportedFileType',
+			input,
+			message: `"${input}" is not a regular file or folder. Choose a file or folder to fetch.`,
+		})
+	}
+	yield* fs.access(resolved, { readable: true }).pipe(Effect.mapError((cause) => localTargetFileError(input, cause)))
+	return info.type === 'Directory' ? LocalTarget.Directory({ path: resolved }) : LocalTarget.File({ path: resolved })
+})
+
+const resolveUrlTarget = Effect.fn('LocalTarget.resolveUrlTarget')(function* (
+	input: string,
+	parsed: Option.Option<URL>,
+) {
+	if (Option.isNone(parsed)) {
+		return yield* new ExpandLocalTargetError({
+			reason: 'InvalidInput',
+			input,
+			message: `Invalid local URL "${input}". Check the address and port.`,
+		})
+	}
+	const url = parsed.value
+	if (url.protocol === 'file:') {
+		const path = yield* Path.Path
+		const filePath = yield* path.fromFileUrl(url).pipe(Effect.mapError((cause) => localTargetFileError(input, cause)))
+		return yield* resolveFileTarget(input, filePath)
+	}
+	if (!LOOPBACK_HOSTS.has(url.hostname)) {
+		return yield* new ExpandLocalTargetError({
+			reason: 'NotLocal',
+			input,
+			message: `"${input}" is not a localhost address. Use a localhost URL or file path, or disable local mode to fetch a public URL.`,
+		})
+	}
+	if (url.protocol !== 'http:') {
+		return yield* new ExpandLocalTargetError({
+			reason: 'UnsupportedProtocol',
+			input,
+			message:
+				url.protocol === 'https:'
+					? `Local HTTPS websites are not supported yet. Start an HTTP server and pass its http://localhost address instead of "${input}".`
+					: `Local websites must use HTTP. Pass an http://localhost address instead of "${input}".`,
+		})
+	}
+	return LocalTarget.Port({
+		host: url.hostname === '0.0.0.0' ? 'localhost' : url.hostname,
+		port: Number(url.port || 80),
+		path: `${url.pathname}${url.search}${url.hash}`,
+	})
+})
+
+/** Reads an explicitly local input or fails with a specific, actionable error. */
+export const resolveLocalTarget = Effect.fn('LocalTarget.resolveLocalTarget')(function* (input: string) {
+	if (input.length === 0) {
+		return yield* new ExpandLocalTargetError({
+			reason: 'InvalidInput',
+			input,
+			message: 'The local input is empty. Pass a localhost URL or a local file or folder path.',
+		})
+	}
+	// Windows drive paths contain a colon but are filesystem inputs, not URL schemes.
+	const isWindowsPath = /^[a-z]:/iu.test(input)
+	const looksLikeUrl = !isWindowsPath && (/^[a-z][a-z\d+.-]*:/iu.test(input) || LOOPBACK_PREFIX.test(input))
+	const parsed = parseUrl(input)
+	return yield* looksLikeUrl || Option.exists(parsed, (url) => isHttpLoopback(url))
+		? resolveUrlTarget(input, parsed)
+		: resolveFileTarget(input, input)
+})

package/src/Tunnel/Protocol.ts

@@ -0,0 +1,99 @@
+import { Array, Encoding, Schema } from 'effect'
+
+/**
+ * Wire protocol between a local tunnel client (CLI / SDK) and the Cloudflare
+ * relay (`packages/tunnel-relay`). One WebSocket per tunnel.
+ *
+ * Control frames are JSON text frames. Body bytes travel as binary frames:
+ * the 16-byte request id followed by the chunk. Every control frame carries
+ * `v: 1` so either side can reject a peer it does not understand.
+ */
+
+export const PROTOCOL_VERSION = 1
+
+/** Upper bound on one binary body frame; larger bodies are split. */
+export const MAX_BODY_FRAME_BYTES = 512 * 1024
+/** Upper bound on each request or response body. */
+export const MAX_BODY_BYTES = 25 * 1024 * 1024
+/** Bounds both relay requests and local work, including uploads still being buffered. */
+export const MAX_INFLIGHT_REQUESTS = 32
+
+/** 16-byte request id encoded as 32 lowercase hex characters. */
+export const RequestId = Schema.String.pipe(Schema.pattern(/^[0-9a-f]{32}$/u), Schema.brand('TunnelRequestId'))
+export type RequestId = typeof RequestId.Type
+
+const HeaderEntries = Schema.Array(Schema.Tuple(Schema.String, Schema.String))
+
+const frame = <Tag extends string, Fields extends Schema.Struct.Fields>(tag: Tag, fields: Fields) =>
+	Schema.TaggedStruct(tag, { v: Schema.Literal(PROTOCOL_VERSION), ...fields })
+
+// relay → client
+
+/** First frame after the socket opens. `url` is the tunnel's public origin, no trailing slash. */
+export const Hello = frame('Hello', { url: Schema.String })
+
+export const RequestStart = frame('RequestStart', {
+	id: RequestId,
+	method: Schema.String,
+	/** Path plus query, e.g. `/docs?x=1`. */
+	path: Schema.String,
+	headers: HeaderEntries,
+	/** When true, binary body frames follow until `RequestEnd`. */
+	hasBody: Schema.Boolean,
+})
+
+const RequestEnd = frame('RequestEnd', { id: RequestId })
+/** The caller disconnected, stopped reading, or exceeded a relay limit. */
+const RequestCancel = frame('RequestCancel', { id: RequestId })
+
+// client → relay
+
+const ResponseStart = frame('ResponseStart', {
+	id: RequestId,
+	status: Schema.Number,
+	headers: HeaderEntries,
+})
+
+const ResponseEnd = frame('ResponseEnd', { id: RequestId })
+
+/** The local origin could not be reached or failed mid-stream; the relay answers 502. */
+const ResponseError = frame('ResponseError', { id: RequestId, message: Schema.String })
+
+export const RelayToClient = Schema.Union(Hello, RequestStart, RequestEnd, RequestCancel)
+export type RelayToClient = typeof RelayToClient.Type
+
+export const ClientToRelay = Schema.Union(ResponseStart, ResponseEnd, ResponseError)
+export type ClientToRelay = typeof ClientToRelay.Type
+
+export const decodeRelayToClient = Schema.decodeUnknownSync(Schema.parseJson(RelayToClient))
+export const decodeClientToRelay = Schema.decodeUnknownSync(Schema.parseJson(ClientToRelay))
+export const encodeRelayToClient = Schema.encodeSync(Schema.parseJson(RelayToClient))
+export const encodeClientToRelay = Schema.encodeSync(Schema.parseJson(ClientToRelay))
+
+const REQUEST_ID_BYTES = 16
+const decodeRequestIdBytes = Schema.decodeSync(Schema.Uint8ArrayFromHex)
+
+/** Binary frame layout: 16 id bytes, then the chunk. */
+export function encodeBodyFrame(id: RequestId, chunk: Uint8Array): Uint8Array {
+	const out = new Uint8Array(REQUEST_ID_BYTES + chunk.byteLength)
+	out.set(decodeRequestIdBytes(id))
+	out.set(chunk, REQUEST_ID_BYTES)
+	return out
+}
+
+export function decodeBodyFrame(frameBytes: Uint8Array): { readonly id: RequestId; readonly chunk: Uint8Array } {
+	if (frameBytes.byteLength < REQUEST_ID_BYTES) {
+		throw new Error(`Tunnel body frame shorter than ${REQUEST_ID_BYTES} bytes`)
+	}
+	return {
+		id: RequestId.make(Encoding.encodeHex(frameBytes.subarray(0, REQUEST_ID_BYTES))),
+		chunk: frameBytes.subarray(REQUEST_ID_BYTES),
+	}
+}
+
+/** Views over a body chunk that fit the protocol's frame-size limit. */
+export function splitBodyChunk(chunk: Uint8Array): Uint8Array[] {
+	return Array.makeBy(Math.ceil(chunk.byteLength / MAX_BODY_FRAME_BYTES), (index) =>
+		chunk.subarray(index * MAX_BODY_FRAME_BYTES, (index + 1) * MAX_BODY_FRAME_BYTES),
+	)
+}

package/src/Tunnel/StaticServer.ts

@@ -0,0 +1,85 @@
+import { FileSystem, HttpServer, HttpServerError, HttpServerRequest, HttpServerResponse, Path } from '@effect/platform'
+import { Effect, Match, Option } from 'effect'
+import mime from 'mime'
+
+const parseRequestUrl = Option.liftThrowable((input: string) => {
+	const url = new URL(input, 'http://localhost')
+	return { url, decodedPathname: decodeURIComponent(url.pathname) }
+})
+
+interface ResolvedFile {
+	readonly path: string
+	readonly name: string
+	readonly directory: boolean
+}
+
+type Resolve = (
+	pathname: string,
+) => Effect.Effect<Option.Option<ResolvedFile>, never, FileSystem.FileSystem | Path.Path>
+
+/** Installs a read-only handler on the supplied server until the scope closes, and returns its TCP port. */
+const serve = Effect.fn('StaticServer.serve')(function* (resolve: Resolve) {
+	const notFound = HttpServerResponse.text('Not found', { status: 404 })
+	const server = yield* HttpServer.HttpServer
+	yield* server.serve(
+		Effect.gen(function* () {
+			const request = yield* HttpServerRequest.HttpServerRequest
+			const parsed = parseRequestUrl(request.url)
+			if (Option.isNone(parsed)) return notFound
+			const { url, decodedPathname } = parsed.value
+			const file = yield* resolve(decodedPathname)
+			if (Option.isNone(file)) return notFound
+			if (file.value.directory && !url.pathname.endsWith('/')) {
+				return HttpServerResponse.redirect(`${url.pathname}/${url.search}`)
+			}
+			// A symlink's public name determines its content type, while reads use its validated destination.
+			return yield* HttpServerResponse.file(file.value.path, {
+				headers: { 'content-type': mime.getType(file.value.name) ?? 'application/octet-stream' },
+			}).pipe(Effect.orElseSucceed(() => notFound))
+		}),
+	)
+	return yield* Match.valueTags(server.address, {
+		TcpAddress: ({ port }) => Effect.succeed(port),
+		UnixAddress: () => new HttpServerError.ServeError({ cause: new Error('Local file serving requires a TCP port.') }),
+	})
+})
+
+/** Serves exactly one file at `/<basename>`; nothing else on the machine is reachable. */
+export const serveFile = (file: string) =>
+	serve((pathname) =>
+		Effect.map(Path.Path, (path) => {
+			const name = path.basename(file)
+			return pathname === `/${name}` ? Option.some({ path: file, name, directory: false }) : Option.none()
+		}),
+	)
+
+/**
+ * Serves `root`; directories answer with their `index.html`. Dotfiles (`.env`, `.git/`) and anything
+ * resolving outside `root`, through `..` or a symlink, are a 404.
+ */
+export const serveDirectory = (root: string) =>
+	serve(
+		Effect.fn('StaticServer.resolveInDirectory')(function* (pathname: string) {
+			const fs = yield* FileSystem.FileSystem
+			const path = yield* Path.Path
+			if (pathname.split('/').some((segment) => segment.startsWith('.'))) return Option.none<ResolvedFile>()
+			const candidate = path.join(root, pathname)
+			const info = yield* fs.stat(candidate).pipe(Effect.option)
+			if (Option.isNone(info)) return Option.none<ResolvedFile>()
+			const file = info.value.type === 'Directory' ? path.join(candidate, 'index.html') : candidate
+			const real = yield* Effect.all([fs.realPath(root), fs.realPath(file)]).pipe(Effect.option)
+			if (Option.isNone(real)) return Option.none<ResolvedFile>()
+			const [realRoot, realFile] = real.value
+			const relative = path.relative(realRoot, realFile)
+			const inside =
+				relative !== '' && !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`)
+			// A visible symlink may resolve to `.env` or into `.git` inside the root.
+			const hidden = relative.split(path.sep).some((segment) => segment.startsWith('.'))
+			if (!inside || hidden) return Option.none<ResolvedFile>()
+			// Opening a FIFO can block a filesystem worker even after the HTTP request is cancelled.
+			const destination = yield* fs.stat(realFile).pipe(Effect.option)
+			return Option.exists(destination, (entry) => entry.type === 'File')
+				? Option.some({ path: realFile, name: path.basename(file), directory: info.value.type === 'Directory' })
+				: Option.none<ResolvedFile>()
+		}),
+	)