# Permalink Rewrite System

## The Problem

You have a document at `https://siteA.com/path/document.md` that you want to serve from `https://siteB.com/other/document.md`, but you need the permalink to remain at siteA because:

1. **Context preservation**: The originating acequia (siteA) provides important contextual information - related documents, navigation, site purpose
2. **Citation stability**: External links point to siteA's URL
3. **Semantic location**: The document's meaning is tied to where it "lives" conceptually

**Rewrite** keeps the original URL visible to the user. **Redirect** changes it.

## When to Use Rewrite vs Redirect

### Use Rewrite (Proxy) when:
- The **origin acequia provides essential context** - surrounding documents, related work, thematic coherence
- The document's **meaning depends on its location** - being at `/research/` vs `/notes/` matters
- **Citations exist** pointing to the original URL
- The originating site is the **canonical semantic home** even if the file lives elsewhere

### Use Redirect when:
- Content has **permanently moved** and the old location is meaningless
- The new location is the **canonical source**
- You want users to **know** they're viewing from a different source

## How It Works

Three files work together to enable JSON-configured rewrites:

### 1. `.htaccess` (generic, never changes)
```apache
RewriteEngine On
# Don't rewrite the proxy script itself or config
RewriteCond %{REQUEST_FILENAME} !proxy\.php$
RewriteCond %{REQUEST_FILENAME} !rewrites\.json$
# Route all .md files to proxy
RewriteRule ^(.+\.md)$ proxy.php [L]
```

### 2. `rewrites.json` (configuration - the only file you edit)
```json
{
  "trans-action-physics.md": {
    "target": "https://harvardviz.live:2078/notes/trans-action-physics.md",
    "contentType": "text/markdown"
  },
  "another-document.md": {
    "target": "https://example.com/path/document.md",
    "contentType": "text/markdown"
  }
}
```

### 3. `proxy.php` (handler - generic, rarely changes)
```php
<?php
// Load rewrite config
$config = json_decode(file_get_contents(__DIR__ . '/rewrites.json'), true);

// Get requested filename
$requested = basename($_SERVER['REQUEST_URI']);

// Check if this file should be proxied
if (isset($config[$requested])) {
    // Proxy from remote
    $target = $config[$requested]['target'];
    $contentType = $config[$requested]['contentType'] ?? 'text/markdown';

    $content = file_get_contents($target);

    if ($content === false) {
        http_response_code(502);
        die('Error fetching content from source');
    }

    header("Content-Type: $contentType; charset=utf-8");
    echo $content;
} else {
    // Serve local file if it exists
    $localFile = __DIR__ . '/' . $requested;
    if (file_exists($localFile)) {
        header('Content-Type: text/markdown; charset=utf-8');
        readfile($localFile);
    } else {
        http_response_code(404);
        die('Not found');
    }
}
?>
```

## Request Flow

```
User requests: https://redfish.com/research/trans-action-physics.md
    ↓
.htaccess: "This is a .md file, route to proxy.php"
    ↓
proxy.php: "Check rewrites.json for 'trans-action-physics.md'"
    ↓
Found in JSON → Fetch from https://harvardviz.live:2078/notes/trans-action-physics.md
    ↓
Serve content with text/markdown header
    ↓
User sees: URL stays as redfish.com/research/trans-action-physics.md
           Content comes from harvardviz.live
           Browser shows redfish.com context
```

## Adding a New Rewrite

1. Edit `rewrites.json` only
2. Add new entry:
```json
{
  "existing-file.md": { ... },
  "new-file.md": {
    "target": "https://target-site.com/path/file.md",
    "contentType": "text/markdown"
  }
}
```
3. No server restart needed - takes effect immediately

## Fallback Behavior

If a `.md` file is requested but **not** in `rewrites.json`:
- proxy.php checks for local file
- If local file exists → serve it
- If no local file → 404

This means you can gradually add files to rewrites without affecting existing local files.

## Performance Considerations

**Cost per proxied request:**
- PHP interpreter startup (unless FastCGI/FPM)
- JSON parse
- Remote HTTP request (~50-500ms network latency)
- Memory for PHP process + file contents

**Optimizations:**
1. **Only proxy specific files**: List explicitly in JSON, local files bypass PHP entirely
2. **Add caching**: Store fetched content for N seconds
3. **Use FastCGI/PHP-FPM**: Keeps PHP process running, eliminates startup cost

For low-traffic research sites, raw implementation is fine. For high-traffic, add caching.

## Example: Trans-Action Physics

**Permalink**: `https://redfish.com/research/trans-action-physics.md`
**Actual source**: `https://harvardviz.live:2078/notes/trans-action-physics.md`

**Why rewrite instead of redirect?**
- The document conceptually "lives" in redfish.com/research/ (physics research context)
- harvardviz.live is the working repository (notes, drafts, active development)
- Citations should point to redfish.com (stable, semantic location)
- Readers browsing redfish.com/research/ see coherent collection

The document flows through acequias: developed at harvardviz.live, canonically located at redfish.com/research/, potentially cited from academic papers. The permalink preserves this semantic location while the actual bytes flow from the active repository.

## Acequia Philosophy

An **acequia** is an irrigation channel - water flows through it from source to destination. Similarly, documents flow through site networks. The rewrite system preserves the **channel identity** (the URL where the document conceptually lives) while allowing the **water source** (actual file storage) to be elsewhere.

The originating acequia provides:
- **Semantic context**: Surrounding documents and thematic coherence - what it means for this document to be "here"
- **Computational context**: Browser origin with its IndexedDB, Service Workers, LocalStorage, Cache API, and registered permissions
- **Client-side state**: Any progressive web app features, offline storage, background sync tied to this origin
- **Navigation**: How the document relates to other work in the same origin
- **Stability**: Permalink for external reference
- **Same-origin access**: What other resources on this origin the page can access

The source acequia provides:
- **Storage**: Where bytes physically live
- **Version control**: Git repository, editing workflow
- **Collaboration**: Where active development happens
- **Update mechanism**: Where edits are made before flowing to canonical locations

## Why Browser Context Matters

A document served from `https://redfish.com/research/` vs `https://harvardviz.live/notes/` isn't just a different URL - it's a **different computational substrate**:

- **Service Workers** registered for redfish.com can intercept requests, cache tiles, enable offline mode
- **IndexedDB** at redfish.com origin stores application state, downloaded datasets, user annotations
- **Cache API** holds pre-loaded resources for faster loading
- **Permissions** (notifications, geolocation, camera) are granted per-origin
- **LocalStorage** persists user preferences, session state

If you **redirect** to harvardviz.live, the page runs in harvardviz's browser context - loses access to redfish's stored data, registered workers, cached resources.

If you **rewrite/proxy** to stay at redfish.com, the page keeps all its browser context - can access IndexedDB, service workers continue running, cached tiles remain available.

**For static documents**, origin doesn't matter much. **For progressive web apps**, origin is everything - it's the computational environment the application executes within.