@hummingbirdworks/proxy 0.1.0 → 0.2.1

package/README.md

@@ -6,14 +6,6 @@ local dev builds or a running dev server (e.g. Vite). This lets you iterate on
 web resources and PCF controls locally without deploying to the environment on
 every change.
 
-## How it works
-
-The package ships a Python mitmproxy addon plus a small Node CLI
-(`hummingbird-proxy`) that launches `mitmdump` with the addon and points it at
-your config file. Redirect rules live in a `proxy.config.toml` file that you
-check into your own repo. **All relative paths in the config are resolved
-relative to the config file**, so the config is portable across machines.
-
 ## Prerequisites
 
 - **Node.js** >= 16 (to run the CLI).
@@ -21,24 +13,15 @@ relative to the config file**, so the config is portable across machines.
   (Python 3.11+, for stdlib TOML support).
   Install from <https://www.mitmproxy.org/> — e.g. `pipx install mitmproxy`.
 
-## Install
+## Install and Configure
 
 ```sh
 npm install -D @hummingbirdworks/proxy
-```
-
-## Configure
-
-Create a config in your repo with the `init` command:
-
-```sh
 npx hummingbird-proxy init
 ```
 
-This copies the bundled example to `./proxy.config.toml` and adds a `proxy`
-script (`"proxy": "hummingbird-proxy"`) to your `package.json`. Pass `--force`
-to overwrite an existing config/script. (You can also copy the example manually
-from `node_modules/@hummingbirdworks/proxy/proxy.config.example.toml`.)
+This creates a proxy.config.toml in the current directory and adds a `proxy`
+script (`"proxy": "hummingbird-proxy"`) to your `package.json`. 
 
 The config is a TOML file. It's a table with a `rules` array-of-tables; each
 `[[rules]]` entry is one redirect:
@@ -82,8 +65,6 @@ Run the proxy from the folder containing `proxy.config.toml`:
 
 ```sh
 npm run proxy
-# or, without the added script:
-npx hummingbird-proxy
 ```
 
 Or point it at a specific config file:
@@ -112,7 +93,7 @@ On first use, install the mitmproxy root certificate so HTTPS interception
 works: with the proxied browser open, visit <http://mitm.it/> and follow the
 instructions for your OS/browser.
 
-### Notes
+### ⚠️ **Notes**
 
 - Chrome and Edge share a single background process across all windows. Either
   close all Chrome/Edge windows before starting the proxy, or use a separate
@@ -127,14 +108,70 @@ instructions for your OS/browser.
   open DevTools → Application → Service Workers and check "Bypass for network"
   to disable the service worker cache.
 
-## Config reference (CLI / env)
+## Using with Vite (HMR)
 
-- **Config path resolution:** the CLI uses the first non-flag argument as the
-  config path, defaulting to `./proxy.config.toml` in the current directory. It
-  passes the resolved absolute path to the addon via the
-  `HUMMINGBIRD_PROXY_CONFIG` environment variable.
-- **Running the addon directly** (without the CLI) is also supported:
+A `devserver` rule routes a web resource's requests to a running Vite dev
+server, giving you hot module reload on the Dynamics-hosted page.
 
-  ```sh
-  HUMMINGBIRD_PROXY_CONFIG=/abs/path/proxy.config.toml mitmdump -s powerapp_dev_proxy.py
-  ```
+The dev server can stay on plain HTTP — the browser only talks to the proxy, and
+the proxy relays requests (including the HMR websocket) to `localhost`. Because
+the Dynamics page is HTTPS, the browser would block an insecure `ws://` HMR
+socket as mixed content, so point the HMR client at `wss` and let the proxy
+forward it to the HTTP dev server. No dev-server cert (or `vite-plugin-mkcert`)
+is needed.
+
+### Vite config
+
+The package ships a Vite plugin that helps with the configuration of web resources. 
+It sets the base path, configures settings to support HMR with the proxy, and turns
+off cache busting since powerapps already has cache busting when you publish customizations.
+
+```ts
+import { defineConfig } from 'vite'
+import { svelte } from '@sveltejs/vite-plugin-svelte'
+import { powerAppsWebResource } from '@hummingbirdworks/proxy/vite'
+
+export default defineConfig({
+  plugins: [
+    svelte(), // or react(), vue(), etc.
+    powerAppsWebResource({ prefix: 'test_/myapp/' }),
+  ],
+  server: { port: 5173 },
+})
+```
+
+Options:
+
+- `prefix` (required): the web resource path, e.g. `test_/myapp/`.
+- `hmrClientPort` (default `443`): port the browser uses for the HMR socket.
+- `stableFilenames` (default `true`): emit unhashed filenames and a single
+  stylesheet. Set `false` to keep Vite's defaults.
+
+If your HTML entry isn't `index.html`, add it to `build.rollupOptions.input`.
+
+### Proxy rule
+
+Point a `devserver` rule at the dev server. The `url` scheme/port must match
+what Vite serves (`http://localhost:5173` by default here):
+
+```toml
+[[rules]]
+type = "devserver"
+name = "test_/myapp/"
+url = "http://localhost:5173"
+domain = "myorg.crm.dynamics.com"
+```
+
+### Run
+
+Start the dev server and the proxy, then browse through the proxy:
+
+```sh
+npm run dev
+npm run proxy
+```
+
+Open the Dynamics page hosting the web resource. Edit → save → the page updates
+without a manual refresh. If HMR doesn't trigger, confirm Vite's port matches
+the rule `url`, that the HMR socket connects over `wss`, and that the service
+worker cache is bypassed (see Notes above).

package/package.json

@@ -1,12 +1,20 @@
 {
   "name": "@hummingbirdworks/proxy",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "mitmproxy-based dev proxy that redirects Dataverse / Dynamics 365 web resources and PCF control assets to local dev builds or a running dev server.",
   "bin": {
     "hummingbird-proxy": "bin/hummingbird-proxy.js"
   },
+  "exports": {
+    "./vite": {
+      "types": "./vite/index.d.ts",
+      "default": "./vite/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "bin/",
+    "vite/",
     "powerapp_dev_proxy.py",
     "proxy.config.example.toml",
     "README.md"
@@ -14,6 +22,14 @@
   "engines": {
     "node": ">=16"
   },
+  "peerDependencies": {
+    "vite": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "vite": {
+      "optional": true
+    }
+  },
   "keywords": [
     "mitmproxy",
     "powerapps",

package/powerapp_dev_proxy.py

@@ -64,6 +64,14 @@ Redirect a PCF control to its local build output folder:
     name = "test.BookingsEditor"
     folder = "./bookings-editor/out/controls/BookingsEditor"
 
+Pull in the rules from another config file (so several projects can proxy the
+same Power Apps environment at once without switching proxies). Includes are
+resolved recursively; each included config's relative paths resolve against its
+own location, and every included file is watched for live reloads:
+    [[rules]]
+    type = "include"
+    path = "../bookings-editor/proxy.config.toml"
+
 Optional keys on any entry:
 "domain":   omit for all hosts, a host string, or an array of host strings
 "disabled": true to skip the entry
@@ -111,6 +119,17 @@ _CONFIG_SCHEMA: dict[str, set[str]] = {
 }
 _OPTIONAL_KEYS = {"type", "domain", "disabled"}
 
+# An "include" entry pulls in the rules from another config file. It is expanded
+# away at load time, so it never reaches _validate_config / the request handler.
+_INCLUDE_KEYS = {"path"}
+_INCLUDE_OPTIONAL_KEYS = {"type", "disabled"}
+
+# Keys the loader attaches to each rule internally; not user-provided.
+_INTERNAL_KEYS = {"_base_dir"}
+
+# Safety net against pathological include nesting (cycles are caught separately).
+_MAX_INCLUDE_DEPTH = 20
+
 
 def _config_path() -> str:
     """Absolute path of the TOML config file to load."""
@@ -138,11 +157,55 @@ def _load_config(path: str) -> list[dict]:
     return rules
 
 
-def _resolve_path(path: str) -> str:
-    """Convert a path to absolute, relative to the config file directory."""
+def _load_rules(path: str, _seen: frozenset[str] = frozenset(), _depth: int = 0) -> tuple[list[dict], set[str]]:
+    """Load rules from a config file, expanding any "include" entries.
+
+    Each returned rule carries a "_base_dir" key giving the directory its
+    relative paths resolve against, so rules pulled in from another config keep
+    resolving against that config's own location. Returns
+    (rules, config_paths) where config_paths is every config file touched, used
+    to watch them all for changes.
+    """
+    path = os.path.abspath(path)
+    if path in _seen:
+        raise ValueError(f"include cycle detected at config {path}")
+    if _depth > _MAX_INCLUDE_DEPTH:
+        raise ValueError(f"include nesting too deep (>{_MAX_INCLUDE_DEPTH}) at {path}")
+    _seen = _seen | {path}
+    base_dir = os.path.dirname(path)
+    rules: list[dict] = []
+    config_paths: set[str] = {path}
+
+    for index, item in enumerate(_load_config(path)):
+        if isinstance(item, dict) and item.get("type") == "include":
+            label = f"{path} include[{index}]"
+            missing = _INCLUDE_KEYS - item.keys()
+            if missing:
+                raise ValueError(f"{label}: missing keys {sorted(missing)}")
+            unknown = item.keys() - (_INCLUDE_KEYS | _INCLUDE_OPTIONAL_KEYS)
+            if unknown:
+                raise ValueError(f"{label}: unknown keys {sorted(unknown)}")
+            if item.get("disabled", False):
+                continue
+            target = item["path"]
+            if not os.path.isabs(target):
+                target = os.path.normpath(os.path.join(base_dir, target))
+            sub_rules, sub_paths = _load_rules(target, _seen, _depth + 1)
+            rules.extend(sub_rules)
+            config_paths |= sub_paths
+        elif isinstance(item, dict):
+            rules.append({**item, "_base_dir": base_dir})
+        else:
+            rules.append(item)
+
+    return rules, config_paths
+
+
+def _resolve_path(path: str, base_dir: str) -> str:
+    """Convert a path to absolute, relative to its config file's directory."""
     if os.path.isabs(path):
         return path
-    return os.path.normpath(os.path.join(CONFIG_DIR, path))
+    return os.path.normpath(os.path.join(base_dir, path))
 
 
 def _validate_config(config: list[dict]) -> list[dict]:
@@ -162,7 +225,7 @@ def _validate_config(config: list[dict]) -> list[dict]:
         missing = required - item.keys()
         if missing:
             raise ValueError(f"{label} (type={item_type!r}): missing keys {sorted(missing)}")
-        unknown = item.keys() - (required | _OPTIONAL_KEYS)
+        unknown = item.keys() - (required | _OPTIONAL_KEYS | _INTERNAL_KEYS)
         if unknown:
             raise ValueError(f"{label} (type={item_type!r}): unknown keys {sorted(unknown)}")
         if not item.get("disabled", False):
@@ -184,7 +247,12 @@ def _web_resource_name(request: http.Request) -> str | None:
     components = request.path_components
     for i, component in enumerate(components):
         if component.lower() == "webresources":
-            return "/".join(components[i + 1:])
+            name = "/".join(components[i + 1:])
+            # path_components drops a trailing slash; keep it so dev-server root
+            # requests (e.g. the Vite HMR base URL) still match a rule prefix.
+            if name and request.path.split("?", 1)[0].endswith("/"):
+                name += "/"
+            return name
     return None
 
 
@@ -214,8 +282,8 @@ def _log_redirect(flow: http.HTTPFlow, rule_type: str, rule_name: str, destinati
     )
 
 
-def _serve_file(flow: http.HTTPFlow, filepath: str, rule_type: str, rule_name: str) -> None:
-    absolute_path = _resolve_path(filepath)
+def _serve_file(flow: http.HTTPFlow, filepath: str, rule_type: str, rule_name: str, base_dir: str) -> None:
+    absolute_path = _resolve_path(filepath, base_dir)
     try:
         with open(absolute_path, "rb") as handle:
             content = handle.read()
@@ -257,14 +325,21 @@ def _config_mtime(path: str) -> float | None:
         return None
 
 
+def _config_mtimes(paths: set[str]) -> dict[str, float | None]:
+    """Modification times for every config file, keyed by path."""
+    return {path: _config_mtime(path) for path in paths}
+
+
 class DataverseProxy:
-    def __init__(self, config: list[dict]) -> None:
-        self.config = _validate_config(config)
-        self._config_mtime = _config_mtime(CONFIG_PATH)
+    def __init__(self, config_path: str) -> None:
+        self.config_path = config_path
+        rules, self._config_paths = _load_rules(config_path)
+        self.config = _validate_config(rules)
+        self._config_mtimes = _config_mtimes(self._config_paths)
         self._watch_task: asyncio.Task | None = None
 
     def running(self) -> None:
-        # Start watching the config file for changes once the event loop is up.
+        # Start watching the config files for changes once the event loop is up.
         if self._watch_task is None:
             self._watch_task = asyncio.ensure_future(self._watch_config())
 
@@ -276,21 +351,27 @@ class DataverseProxy:
     async def _watch_config(self) -> None:
         while True:
             await asyncio.sleep(_CONFIG_POLL_INTERVAL)
-            mtime = _config_mtime(CONFIG_PATH)
-            if mtime is None or mtime == self._config_mtime:
+            mtimes = _config_mtimes(self._config_paths)
+            if mtimes == self._config_mtimes:
                 continue
-            self._config_mtime = mtime
+            self._config_mtimes = mtimes
             self._reload_config()
 
     def _reload_config(self) -> None:
         try:
-            config = _validate_config(_load_config(CONFIG_PATH))
+            rules, paths = _load_rules(self.config_path)
+            config = _validate_config(rules)
         except (OSError, ValueError) as err:
             ctx.log.warn(f"Config reload failed, keeping previous rules: {err}")
             return
         self.config = config
+        self._config_paths = paths
+        self._config_mtimes = _config_mtimes(paths)
         _pcf_patterns.clear()
-        ctx.log.info(f"Reloaded proxy config from {CONFIG_PATH} ({len(config)} active rules)")
+        ctx.log.info(
+            f"Reloaded proxy config from {self.config_path} "
+            f"({len(config)} active rules across {len(paths)} files)"
+        )
 
     def tls_start_server(self, data: tls.TlsData) -> None:
         # Provide a no-verify TLS context for localhost dev servers only. This runs
@@ -344,7 +425,7 @@ class DataverseProxy:
 
             elif item_type == "single":
                 if web_resource == item["name"]:
-                    _serve_file(flow, item["file"], item_type, item["name"])
+                    _serve_file(flow, item["file"], item_type, item["name"], item["_base_dir"])
                     return
 
             elif item_type == "folder":
@@ -355,6 +436,7 @@ class DataverseProxy:
                         os.path.join(item["folder"], *relative.split("/")),
                         item_type,
                         item["name"],
+                        item["_base_dir"],
                     )
                     return
 
@@ -366,12 +448,10 @@ class DataverseProxy:
                     if is_css:
                         parts.append("css")
                     parts.extend(segment for segment in relative.split("/") if segment)
-                    _serve_file(flow, os.path.join(*parts), item_type, item["name"])
+                    _serve_file(flow, os.path.join(*parts), item_type, item["name"], item["_base_dir"])
                     return
 
 
 CONFIG_PATH = _config_path()
-CONFIG_DIR = os.path.dirname(CONFIG_PATH)
-CONFIG = _load_config(CONFIG_PATH)
 
-addons = [DataverseProxy(CONFIG)]
+addons = [DataverseProxy(CONFIG_PATH)]

package/vite/index.d.ts

@@ -0,0 +1,22 @@
+import type { Plugin } from "vite";
+
+export interface WebResourceOptions {
+  /** Web resource path prefix, e.g. `test_/myapp/`. Leading/trailing slashes are optional. */
+  prefix: string;
+  /** Port the browser uses for the HMR websocket. Defaults to `443`. */
+  hmrClientPort?: number;
+  /**
+   * Emit unhashed filenames and a single stylesheet so solution components stay
+   * stable across builds. Defaults to `true`; set `false` to keep Vite's defaults.
+   */
+  stableFilenames?: boolean;
+}
+
+/**
+ * Vite plugin that aligns the dev server and build output with a Dataverse /
+ * Dynamics 365 web resource served through `@hummingbirdworks/proxy`.
+ *
+ * Sets `base` (absolute in dev, relative in build) and a `wss` HMR socket, and
+ * optionally emits stable filenames.
+ */
+export function powerAppsWebResource(options: WebResourceOptions): Plugin;

package/vite/index.js

@@ -0,0 +1,49 @@
+"use strict";
+
+// Vite plugin that configures a project so its dev server and build output line
+// up with a Dataverse / Dynamics 365 web resource served through the proxy.
+
+function powerAppsWebResource(options) {
+  if (!options || typeof options.prefix !== "string") {
+    throw new Error(
+      "powerAppsWebResource: 'prefix' is required, e.g. 'test_/myapp/'."
+    );
+  }
+  const prefix = options.prefix.replace(/^\/+|\/+$/g, "");
+  if (!prefix) {
+    throw new Error(
+      "powerAppsWebResource: 'prefix' must not be empty, e.g. 'test_/myapp/'."
+    );
+  }
+  const clientPort = options.hmrClientPort != null ? options.hmrClientPort : 443;
+  const stableFilenames = options.stableFilenames !== false;
+
+  return {
+    name: "@hummingbirdworks/proxy:webresource",
+    config(_config, env) {
+      const isServe = env.command === "serve";
+      // Dynamics pages are HTTPS, so the HMR socket must be wss to avoid
+      // mixed-content blocking; the proxy relays it to the HTTP dev server.
+      const config = {
+        base: isServe ? "/webresources/" + prefix + "/" : "./",
+        server: { hmr: { protocol: "wss", clientPort: clientPort } },
+      };
+      if (stableFilenames) {
+        config.build = {
+          cssCodeSplit: false,
+          rollupOptions: {
+            output: {
+              // Stable filenames — Dynamics does its own cache busting on publish.
+              entryFileNames: "[name].js",
+              chunkFileNames: "[name].js",
+              assetFileNames: "[name].[ext]",
+            },
+          },
+        };
+      }
+      return config;
+    },
+  };
+}
+
+exports.powerAppsWebResource = powerAppsWebResource;