Bifurc — Network Architecture

This document explains how Bifurc's network layer works: the reverse proxy, the forward proxy, mappings, mocks, proxy rules, HTTPS handling, and how requests you send from the app travel. It also answers the common question: "Will using a system proxy cause a loop?"

Bifurc's engine is written in Rust and runs as a local process. The desktop app, the bifurc CLI and the browser extension are all clients of that engine.

---

1. Two local proxies

Bifurc runs two listeners, both bound to 127.0.0.1 only. Each can be started, stopped and moved to another port in Settings.

A third local port, the companion (default 4747), is a WebSocket bridge for the browser extension. It never carries proxied traffic.

Browser / App
    │
    ├── http://myapp.localhost  ──────►  127.0.0.1:80    (reverse proxy)
    │
    └── configured proxy        ──────►  127.0.0.1:8080  (forward proxy)

---

2. Reverse proxy — *.localhost names

RFC 6761 designates *.localhost as a special-use domain. Major browsers resolve any *.localhost name to 127.0.0.1 without touching DNS, so no hosts-file edits are needed. With the reverse proxy on port 80 the browser reaches Bifurc directly, and mapped names work without a port. If you move the reverse proxy to another port, include it in the URL: http://myapp.localhost:<port>.

Flow

Request: GET / HTTP/1.1
Host: myapp.localhost
         │
         ▼
  Does an enabled mock match?
         │
         ├─── Yes ──────────────────────► serve the mock
         │                                → log entry: via="mock"
         ▼ (no)
  Is there an enabled mapping for this host?
         │
         ├─── Yes ──────────────────────► forward to the mapping's target
         │                                → log entry: via="rfc6761"
         │
         └─── No ───────────────────────► 404 "Not Mapped" page
                                          → log entry: via="error"

Visiting a host that is neither mapped nor a .localhost name shows Bifurc's home page, which lists your enabled mappings.

Mocks are checked in the reverse proxy; proxy rules are not.

---

3. Forward proxy

When a browser or application uses Bifurc as its HTTP proxy (127.0.0.1:8080), requests arrive as absolute URLs:

GET http://api.example.com/v1/users HTTP/1.1
Host: api.example.com

The routes are checked in strict priority order:

Request arrives at the forward proxy
         │
         ▼
  ┌─────────────────────────────────────┐
  │  1. Mock check (highest priority)   │
  └─────────────────────────────────────┘
         │
         ├─── Mock matched ──────────────► serve the mock
         │                                → log entry: via="mock"
         ▼ (no mock matched)
  ┌─────────────────────────────────────┐
  │  2. Proxy rule check                │
  └─────────────────────────────────────┘
         │
         ├─── Rule matched ──────────────► forward to the rule's target mapping
         │                                → log entry: via="rule"
         ▼ (no rule matched)
  ┌─────────────────────────────────────┐
  │  3. Passthrough (default)           │
  └─────────────────────────────────────┘
         │
         └────────────────────────────────► forward to the original host
                                           → log entry: via="proxy"

---

4. Mappings

A mapping links a *.localhost domain to a backend target:

domain:  "myapp.localhost"
target:  "127.0.0.1:3000"
label:   "Frontend Dev Server"
enabled: true

Mappings are used in two situations:

1. The reverse proxy: the incoming Host header matches the mapping's domain.
2. Proxy rules: a rule names a mapping as its redirect target.

Mappings belong to a workspace; only the active workspace's mappings are used.

---

5. Proxy rules

A proxy rule redirects matching URLs to a mapping's target, and can run request and response scripts:

pattern:  "^https?://api\\.staging\\.example\\.com"  (regex)
target:   a mapping
enabled:  true

For each enabled rule, in order, the pattern is tested against the full absolute URL. The first match wins; if the rule's target is missing the proxy answers 502, and if no rule matches the request passes through.

Proxy rules only apply to the forward proxy.

---

6. Mocks

A mock short-circuits a real request and returns a configured response. Mocks match on method and URL (exact or regex), and GraphQL and SOAP mocks also match on operation. A mock can be complete, or can replace only part of the response (for example the body) and take the rest from the live upstream.

Mock bodies, headers and URL patterns can use {{VARIABLE_NAME}} placeholders, resolved against the active environment when the response is served.

Mocks are checked first in both proxies. gRPC is not mockable.

---

7. HTTPS

For HTTPS, browsers send a CONNECT request to the forward proxy. What happens next depends on whether TLS interception is enabled in Settings.

The root certificate and its private key are generated on your device and are used only by the local proxy.

---

8. The loop question: *.localhost + a system proxy

Question: If the OS or browser proxy is set to 127.0.0.1:8080, and a request to myapp.localhost arrives, will it loop back through Bifurc?

Answer: No.

Bifurc connects to a mapping's target directly, with its own outbound connection. That connection does not consult the OS proxy settings and does not go to Bifurc's own ports, so the chain ends at your real service:

Browser navigates to http://myapp.localhost/
         │
         ▼
Bifurc looks up the mapping for myapp.localhost
         │
         ▼
Direct connection to 127.0.0.1:3000   ← your app, not through Bifurc again

---

9. Requests sent from the app

Requests you author and send from the Requests screen are made by the engine directly to the target server. They do not go through Bifurc's proxies, so mocks and proxy rules do not apply to them.

• REST, GraphQL and SOAP requests are plain HTTP(S) calls from the engine.
• gRPC requests open a channel to the server directly (TLS is used for https:// and grpcs:// addresses and port 443).
• WebSocket connections are opened by the engine directly to the target URL.

If you want a request to be captured, send it from your app or browser through the forward proxy instead.

---

10. Summary