@stacksjs/rpx 0.11.3 → 0.11.5

package/src/types.ts

@@ -0,0 +1,93 @@
+import type { TlsConfig, TlsOption } from '@stacksjs/tlsx'
+
+export interface StartOptions {
+  command: string
+  cwd?: string
+  env?: Record<string, string>
+}
+
+export interface PathRewrite {
+  /** Path prefix to match, e.g. '/api' */
+  from: string
+  /** Target backend to route to, e.g. 'localhost:3008' */
+  to: string
+  /**
+   * Strip the matched prefix before forwarding. Default: `false` (preserve path).
+   *
+   * Matches the behavior of Vite's `server.proxy`, nginx `proxy_pass http://host:port`
+   * (no trailing slash), and http-proxy-middleware's default. Most upstreams that own
+   * a `/api` namespace expect the prefix to remain on the request URL.
+   *
+   * Set to `true` only when the upstream registers routes WITHOUT the prefix
+   * (e.g., upstream serves `/cart/add` and you want `/api/cart/add` to reach it).
+   */
+  stripPrefix?: boolean
+}
+
+export interface BaseProxyConfig {
+  from: string // localhost:5173
+  to: string // stacks.localhost
+  start?: StartOptions
+  pathRewrites?: PathRewrite[]
+}
+
+export type BaseProxyOptions = Partial<BaseProxyConfig>
+
+export interface CleanupConfig {
+  domains: string[] // default: [], if only specific domain/s should be cleaned up
+  hosts: boolean // default: true, if hosts file should be cleaned up
+  certs: boolean // default: false, if certificates should be cleaned up
+  verbose: boolean // default: false
+  vitePluginUsage?: boolean // default: false, if cleanup was initiated by the Vite plugin
+}
+
+export type CleanupOptions = Partial<CleanupConfig>
+
+export interface SharedProxyConfig {
+  https: boolean | TlsOption
+  cleanup: boolean | CleanupOptions
+  vitePluginUsage: boolean
+  verbose: boolean
+  _cachedSSLConfig?: SSLConfig | null
+  start?: StartOptions
+  cleanUrls: boolean
+  changeOrigin?: boolean // default: false - changes the origin of the host header to the target URL
+  regenerateUntrustedCerts?: boolean // If true, will regenerate and re-trust certs that exist but are not trusted by the system.
+}
+
+export type SharedProxyOptions = Partial<SharedProxyConfig>
+
+export interface SingleProxyConfig extends BaseProxyConfig, SharedProxyConfig {}
+
+export interface MultiProxyConfig extends SharedProxyConfig {
+  proxies: Array<BaseProxyConfig & { cleanUrls: boolean, pathRewrites?: PathRewrite[] }>
+}
+
+export type ProxyConfig = SingleProxyConfig
+export type ProxyConfigs = SingleProxyConfig | MultiProxyConfig
+
+export type BaseProxyOption = Partial<BaseProxyConfig>
+export type ProxyOption = Partial<SingleProxyConfig>
+export type ProxyOptions = Partial<SingleProxyConfig> | Partial<MultiProxyConfig>
+
+export interface SSLConfig {
+  key: string
+  cert: string
+  ca?: string | string[]
+}
+
+export interface ProxySetupOptions extends Omit<ProxyOption, 'from'> {
+  fromPort: number
+  sourceUrl: Pick<URL, 'hostname' | 'host'>
+  ssl: SSLConfig | null
+  from: string
+  to: string
+  portManager?: PortManager
+}
+
+export interface PortManager {
+  usedPorts: Set<number>
+  getNextAvailablePort: (startPort: number) => Promise<number>
+}
+
+export type { TlsConfig, TlsOption }

package/src/utils.ts

@@ -0,0 +1,156 @@
+import type { MultiProxyConfig, PathRewrite, ProxyConfigs, ProxyOption, ProxyOptions, SingleProxyConfig } from './types'
+import { execSync } from 'node:child_process'
+import * as fs from 'node:fs/promises'
+import { Logger } from '@stacksjs/clarity'
+
+const logger = new Logger('rpx', {
+  showTags: false,
+})
+
+/**
+ * Get sudo password from environment variable if set
+ */
+export function getSudoPassword(): string | undefined {
+  return process.env.SUDO_PASSWORD
+}
+
+/**
+ * Execute a command with sudo, using SUDO_PASSWORD if available
+ */
+export function execSudoSync(command: string): string {
+  const sudoPassword = getSudoPassword()
+  const escaped = command.replace(/'/g, `'\\''`)
+
+  if (sudoPassword) {
+    return execSync(`echo '${sudoPassword}' | sudo -S sh -c '${escaped}' 2>/dev/null`, {
+      encoding: 'utf-8',
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+  }
+
+  return execSync(`sudo sh -c '${escaped}'`, { encoding: 'utf-8' })
+}
+
+export function debugLog(category: string, message: string, verbose?: boolean): void {
+  if (verbose)
+    logger.debug(`[rpx:${category}] ${message}`)
+}
+
+/**
+ * Extracts hostnames from proxy configuration
+ */
+export function extractHostname(options: ProxyOption | ProxyOptions): string[] {
+  if (isMultiProxyOptions(options)) {
+    return options.proxies.map((proxy) => {
+      const domain = proxy.to || 'stacks.localhost'
+      return domain.startsWith('http') ? new URL(domain).hostname : domain
+    })
+  }
+
+  if (isSingleProxyOptions(options)) {
+    const domain = options.to || 'stacks.localhost'
+    return [domain.startsWith('http') ? new URL(domain).hostname : domain]
+  }
+
+  return ['stacks.localhost']
+}
+
+interface RootCA {
+  certificate: string
+  privateKey: string
+}
+
+export function isValidRootCA(value: unknown): value is RootCA {
+  return (
+    typeof value === 'object'
+    && value !== null
+    && 'certificate' in value
+    && 'privateKey' in value
+    && typeof (value as RootCA).certificate === 'string'
+    && typeof (value as RootCA).privateKey === 'string'
+  )
+}
+
+export function getPrimaryDomain(options?: ProxyOption | ProxyOptions): string {
+  if (!options)
+    return 'stacks.localhost'
+
+  if (isMultiProxyOptions(options) && options.proxies.length > 0)
+    return options.proxies[0].to || 'stacks.localhost'
+
+  if (isSingleProxyOptions(options))
+    return options.to || 'stacks.localhost'
+
+  return 'stacks.localhost'
+}
+
+/**
+ * Type guard for multi-proxy configuration
+ */
+export function isMultiProxyConfig(options: ProxyConfigs | ProxyOptions): options is MultiProxyConfig {
+  return !!(options && 'proxies' in options && Array.isArray((options as MultiProxyConfig).proxies))
+}
+
+/**
+ * Type guard to check if options are for multi-proxy configuration
+ */
+export function isMultiProxyOptions(options: ProxyOption | ProxyOptions): options is MultiProxyConfig {
+  return 'proxies' in options && Array.isArray((options as MultiProxyConfig).proxies)
+}
+
+/**
+ * Type guard to check if options are for single-proxy configuration
+ */
+export function isSingleProxyOptions(options: ProxyOption | ProxyOptions): options is SingleProxyConfig {
+  return 'to' in options && typeof (options as SingleProxyConfig).to === 'string'
+}
+
+export function isSingleProxyConfig(options: ProxyConfigs | ProxyOptions): options is SingleProxyConfig {
+  return !!(options && 'to' in options && !('proxies' in options))
+}
+
+/**
+ * Resolve a path against a list of `pathRewrites`.
+ *
+ * Returns `null` if no rewrite matches; otherwise returns `{ targetHost, targetPath }`
+ * with the prefix preserved by default (or stripped when `stripPrefix === true`).
+ *
+ * Matching rule: rewrite matches if `pathname` is exactly `from` OR starts with
+ * `from + '/'`. So `/api` matches `/api`, `/api/`, `/api/cart` — but not `/apidocs`.
+ */
+export function resolvePathRewrite(
+  pathname: string,
+  rewrites: PathRewrite[] | undefined,
+): { targetHost: string, targetPath: string } | null {
+  if (!rewrites || rewrites.length === 0)
+    return null
+
+  for (const rewrite of rewrites) {
+    if (pathname === rewrite.from || pathname.startsWith(`${rewrite.from}/`)) {
+      const targetHost = rewrite.to.startsWith('http') ? new URL(rewrite.to).host : rewrite.to
+      const targetPath = rewrite.stripPrefix === true
+        ? (pathname.slice(rewrite.from.length) || '/')
+        : pathname
+      return { targetHost, targetPath }
+    }
+  }
+
+  return null
+}
+
+/**
+ * Safely delete a file if it exists
+ */
+export async function safeDeleteFile(filePath: string, verbose?: boolean): Promise<void> {
+  try {
+    // Try to delete the file directly without checking existence first
+    await fs.unlink(filePath)
+    debugLog('certificates', `Successfully deleted: ${filePath}`, verbose)
+  }
+  catch (err) {
+    // Ignore errors where file doesn't exist
+    if ((err as NodeJS.ErrnoException).code !== 'ENOENT') {
+      debugLog('certificates', `Warning: Could not delete ${filePath}: ${err}`, verbose)
+    }
+  }
+}