feat: add composable bridge middleware (#117)

Author: jingjing2222

.changeset/quiet-dingos-guard.md

@@ -0,0 +1,6 @@
+---
+"@webview-bridge/react-native": minor
+---
+
+Add chainable `bridge(...).use(middleware)` support for composing Web-to-Native
+request authentication, preprocessing, short-circuiting, and response logic.

docs/reference/react-native/create-webview.md

@@ -8,4 +8,38 @@ The `createWebView` is used to create a WebView with an interface that enables c
 | `bridge`         | Object                         | true     | X       | Represents the bridge between React Native and the WebView.                  |
 | `debug`          | boolean                        | false    | false   | Outputs console.log from the web in React Native.                                          |
 | `responseTimeout`| number                         | false    | 2000    | Timeout duration when executing web methods.                   |
-| `fallback`       | (method: keyof T) => void      | false    | X       |Callback function called when a method from the bridge is not found.         |
+| `fallback`       | (method: keyof T) => void      | false    | X       |Callback function called when a method from the bridge is not found.         |
+
+## Bridge middleware
+
+`bridge(...).use(...)` registers instance-scoped middleware for Web-to-Native
+method calls.
+
+```tsx
+import {
+  bridge,
+  type BridgeMiddleware,
+} from "@webview-bridge/react-native";
+
+const logger: BridgeMiddleware = async ({ method }, next) => {
+  console.log(`Calling ${method}`);
+  const result = await next();
+  console.log(`Called ${method}`);
+  return result;
+};
+
+const appBridge = bridge({
+  async getMessage() {
+    return "Hello, I'm native";
+  },
+}).use(logger);
+```
+
+Middleware receives `{ url, method, args }` and `next()`. It may update `args`,
+attach typed context fields to the shared request, short-circuit without calling
+`next()`, or transform the returned value.
+`use()` returns the same bridge store for chaining; call `next()` at most once.
+
+`url` is the top-level URL reported by `react-native-webview`, not a verified
+caller origin. Middleware applies only to bridge method calls and does not
+intercept navigation or network requests.

example/native-method/react-native/App.tsx

@@ -1,26 +1,122 @@
-import React from "react";
-import { SafeAreaView } from "react-native";
+import React from 'react';
+import { SafeAreaView, StyleSheet } from 'react-native';
 import {
   createWebView,
+  type BridgeMiddleware,
+  type BridgeStore,
   type BridgeWebView,
   bridge,
-} from "@webview-bridge/react-native";
-import InAppBrowser from "react-native-inappbrowser-reborn";
+} from '@webview-bridge/react-native';
+import InAppBrowser from 'react-native-inappbrowser-reborn';
+import 'react-native-url-polyfill/auto';
 
-export const appBridge = bridge({
+const WEB_APP_URL = new URL('http://localhost:5173');
+
+const getUrlOrigin = (url: string) => new URL(url).origin;
+
+const observeBridgeRequests = (): BridgeMiddleware =>
+  async ({ method, url }, next) => {
+    const startedAt = Date.now();
+    let origin = 'unknown';
+    try {
+      if (url) {
+        origin = getUrlOrigin(url);
+      }
+    } catch {
+      origin = 'invalid URL';
+    }
+
+    console.log(`[bridge] -> ${method} (${origin})`);
+    try {
+      const result = await next();
+      console.log(`[bridge] <- ${method} (${Date.now() - startedAt}ms)`);
+      return result;
+    } catch (error) {
+      console.error(
+        `[bridge] !! ${method} (${Date.now() - startedAt}ms)`,
+        error,
+      );
+      throw error;
+    }
+  };
+
+const allowWebAppOrigin = (webAppUrl: URL): BridgeMiddleware => {
+  const allowedOrigin = webAppUrl.origin;
+
+  return async ({ url }, next) => {
+    let requestOrigin: string;
+    try {
+      if (!url) {
+        throw new Error('Missing WebView URL');
+      }
+      requestOrigin = getUrlOrigin(url);
+    } catch {
+      throw new Error('Bridge request has an invalid WebView URL');
+    }
+
+    if (requestOrigin !== allowedOrigin) {
+      throw new Error(`Bridge request denied for origin: ${requestOrigin}`);
+    }
+    return next();
+  };
+};
+
+const normalizeExternalUrl = (): BridgeMiddleware =>
+  async (request, next) => {
+    if (request.method !== 'openInAppBrowser') {
+      return next();
+    }
+
+    const [input] = request.args;
+    if (typeof input !== 'string' || input.trim().length === 0) {
+      throw new TypeError('A non-empty URL is required');
+    }
+
+    const trimmedUrl = input.trim();
+    let externalUrl: URL;
+    try {
+      externalUrl = new URL(trimmedUrl);
+    } catch {
+      externalUrl = new URL(`https://${trimmedUrl}`);
+    }
+
+    if (externalUrl.protocol !== 'https:') {
+      throw new Error('Only HTTPS links can be opened');
+    }
+
+    request.args = [externalUrl.toString()];
+    return next();
+  };
+
+const configuredAppBridge = bridge({
   async getMessage() {
     return "I'm from native" as const;
   },
   async openInAppBrowser(url: string) {
-    if (await InAppBrowser.isAvailable()) {
-      await InAppBrowser.open(url);
+    if (!(await InAppBrowser.isAvailable())) {
+      return {
+        openedUrl: url,
+        status: 'unavailable' as const,
+      };
     }
+
+    const result = await InAppBrowser.open(url);
+    return {
+      openedUrl: url,
+      status: result.type,
+    };
   },
   async throwError() {
     throw new Error('🚧 This error is from native side!!');
   },
-});
+})
+  .use(observeBridgeRequests())
+  .use(allowWebAppOrigin(WEB_APP_URL))
+  .use(normalizeExternalUrl());
 
+export const appBridge: BridgeStore<
+  ReturnType<typeof configuredAppBridge.getState>
+> = configuredAppBridge;
 
 export const { WebView } = createWebView({
   bridge: appBridge,
@@ -34,16 +130,27 @@ function App(): JSX.Element {
   const webviewRef = React.useRef<BridgeWebView>(null);
 
   return (
-    <SafeAreaView style={{ height: "100%" }}>
+    <SafeAreaView style={styles.container}>
       <WebView
         ref={webviewRef}
         source={{
-          uri: "http://localhost:5173",
+          uri: WEB_APP_URL.href,
         }}
-        style={{ height: "100%", flex: 1, width: "100%" }}
+        style={styles.webView}
       />
     </SafeAreaView>
   );
 }
 
+const styles = StyleSheet.create({
+  container: {
+    height: '100%',
+  },
+  webView: {
+    flex: 1,
+    width: '100%',
+    height: '100%',
+  },
+});
+
 export default App;

example/native-method/react-native/README.md

@@ -1,5 +1,20 @@
 This is a new [**React Native**](https://reactnative.dev) project, bootstrapped using [`@react-native-community/cli`](https://github.com/react-native-community/cli).
 
+## Bridge middleware example
+
+`App.tsx` chains request logging, WebView URL authorization, and external URL
+normalization with `bridge(...).use(...)`. The paired `../react` app exercises
+the chain before opening a real native InAppBrowser.
+
+From the repository root, run the middleware integration tests with:
+
+```bash
+pnpm --filter @webview-bridge-example-native-method/react-native test --runInBand
+```
+
+In the running example, a scheme-less URL is normalized to HTTPS, while the
+**Try blocked scheme** action is rejected before native browser code runs.
+
 # Getting Started
 
 >**Note**: Make sure you have completed the [React Native - Environment Setup](https://reactnative.dev/docs/environment-setup) instructions till "Creating a new application" step, before proceeding.