Migrate to http-handler and http-rewriter

Author: Qard

CLAUDE.md

@@ -0,0 +1,124 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+@platformatic/php-node is a Node.js native addon that embeds PHP within the same process as Node.js, enabling seamless communication without network overhead. It's built with Rust using NAPI-RS for safe and performant bindings.
+
+## Essential Commands
+
+### Development
+```bash
+# Build release version
+npm run build
+
+# Build debug version (faster compilation, includes debug symbols)
+npm run build:debug
+
+# Run all tests
+npm test
+
+# Run specific test file
+npx ava __test__/headers.spec.mjs
+
+# Lint JavaScript code  
+npm run lint
+
+# Create universal binary (macOS)
+npm run universal
+
+# Version bump
+npm run version
+```
+
+### Rust-specific builds
+```bash
+# Build with proper rpath for linking libphp
+RUSTFLAGS="-C link-args=-Wl,-rpath,\$ORIGIN" npm run build
+
+# Build specific crate
+cargo build --manifest-path crates/php_node/Cargo.toml --release
+```
+
+## Architecture
+
+### Multi-language Structure
+- **Rust** (`/crates`): Core implementation using Cargo workspace
+  - `lang_handler`: Generic language handler abstractions
+  - `php`: PHP embedding and SAPI implementation  
+  - `php_node`: NAPI bindings exposing Rust to Node.js
+- **JavaScript**: Node.js API layer (`index.js`, `index.d.ts`)
+- **PHP**: Embedded runtime via libphp.{so,dylib}
+
+### Key Components
+
+1. **PHP Class** (`index.js`): Main entry point for creating PHP environments
+   - Manages rewriter rules for URL routing
+   - Handles request/response lifecycle
+   - Supports both sync and async request handling
+
+2. **Request/Response Model**: Web standards-compatible implementation
+   - `Request` class with headers, body, method
+   - `Response` class with status, headers, body
+   - `Headers` class with case-insensitive header handling
+
+3. **Rewriter System**: Apache mod_rewrite-like functionality
+   - Conditional rules with regex patterns
+   - Environment variable support
+   - Rule chaining with [L], [R], [C] flags
+
+4. **SAPI Implementation**: Custom PHP SAPI in Rust
+   - Direct Zend API usage for performance
+   - Thread-safe with TSRM support
+   - Reusable PHP environments across requests
+
+## Critical Development Notes
+
+1. **System Dependencies Required**:
+   - Linux: `libssl-dev libcurl4-openssl-dev libxml2-dev libsqlite3-dev libonig-dev re2c libpq5`
+   - macOS: `openssl@3 curl sqlite libxml2 oniguruma postgresql@16`
+
+2. **PHP Runtime**: Must have `libphp.so` (Linux) or `libphp.dylib` (macOS) in project root
+
+3. **Testing**: AVA framework with 3-minute timeout due to PHP startup overhead
+
+4. **Type Definitions**: `index.d.ts` is auto-generated by NAPI-RS - do not edit manually
+
+5. **Platform Support**: x64 Linux, x64/arm64 macOS (pre-built binaries in `/npm`)
+
+6. **Recent Architecture Changes**: 
+   - `lang_handler` crate no longer uses `napi` features directly (removed from dependencies)
+   - `php` crate uses custom fork of ext-php-rs from platformatic GitHub org
+
+## Common Tasks
+
+### Adding New NAPI Functions
+1. Implement in Rust under `crates/php_node/src/`
+2. Use `#[napi]` attributes for exposed functions/classes
+3. Run `npm run build` to regenerate TypeScript definitions
+
+### Modifying Request/Response Handling
+- Core logic in `crates/php/src/sapi.rs`
+- JavaScript wrapper in `index.js`
+- Headers handling in `crates/php_node/src/headers.rs`
+
+### Debugging PHP Issues
+- Check INTERNALS.md for PHP embedding details
+- Use `npm run build:debug` for debug symbols
+- PHP superglobals set via `SG(...)` macro in Rust code
+
+### Working with Rewriter Rules
+The rewriter system supports Apache mod_rewrite-like functionality:
+- Create rules with conditions (header, host, method, path, query)
+- Apply rewriters (header, href, method, path, query, status)
+- Use flags like [L] (last), [R] (redirect), [C] (chain)
+- Example: `new Rewriter([{ conditions: [{type: 'path', args: ['^/old/(.*)$']}], rewriters: [{type: 'path', args: ['^/old/(.*)$', '/new/$1']}] }])`
+
+## Project Files Reference
+
+- `index.js`: Main JavaScript API, exports PHP, Request, Response, Headers, Rewriter classes
+- `crates/php_node/src/lib.rs`: NAPI bindings entry point
+- `crates/php/src/sapi.rs`: PHP SAPI implementation (core request handling)
+- `crates/lang_handler/src/`: Generic language handler abstractions (request/response/rewriter)
+- `__test__/*.spec.mjs`: Test files for each component

Cargo.toml

@@ -1,10 +1,47 @@
-[workspace]
-resolver = "2"
-members = [
-    "crates/lang_handler",
-    "crates/php",
-    "crates/php_node"
-]
+[package]
+edition = "2021"
+name = "php-node"
+version = "1.4.0"
+authors = ["Platformatic Inc. <[email protected]> (https://platformatic.dev)"]
+license = "MIT"
+repository = "https://github.com/platformatic/php-node"
+
+[features]
+default = []
+napi-support = ["dep:napi", "dep:napi-derive", "dep:napi-build", "http-handler/napi-support", "http-rewriter/napi-support"]
+
+[lib]
+name = "php_node"
+crate-type = ["cdylib"]
+path = "src/lib.rs"
+
+[dependencies]
+async-trait = "0.1.88"
+bytes = "1.10.1"
+hostname = "0.4.1"
+ext-php-rs = { git = "https://github.com/platformatic/ext-php-rs.git" }
+http-handler = { git = "https://github.com/platformatic/http-handler.git", branch = "avoid-copying-inner-request" }
+# http-handler = { path = "../http-handler" }
+http-rewriter = { git = "https://github.com/platformatic/http-rewriter.git", branch = "more-flexible-url-path-rewriting" }
+# http-rewriter = { path = "../http-rewriter" }
+libc = "0.2.171"
+# Default enable napi4 feature, see https://nodejs.org/api/n-api.html#node-api-version-matrix
+napi = { version = "3", default-features = false, features = ["napi4"], optional = true }
+napi-derive = { version = "3", optional = true }
+once_cell = "1.21.0"
+tokio = { version = "1.45", features = ["rt", "macros", "rt-multi-thread"] }
+regex = "1.0"
+
+[dev-dependencies]
+tokio-test = "0.4"
+
+[build-dependencies]
+autotools = "0.2"
+bindgen = "0.69.4"
+cc = "1.1.7"
+downloader = "0.2.8"
+file-mode = "0.1.2"
+napi-build = { version = "2.2.1", optional = true }
 
 # [profile.release]
 # lto = true

__test__/headers.spec.mjs

@@ -19,20 +19,20 @@ test('only last set is used for get', (t) => {
   const headers = new Headers()
   headers.set('Content-Type', 'application/json')
   headers.add('Content-Type', 'text/html')
-  t.is(headers.size, 1)
+  t.is(headers.size, 2)
   t.assert(headers.has('Content-Type'))
-  t.is(headers.get('Content-Type'), 'text/html')
+  t.is(headers.get('Content-Type'), 'application/json')
 })
 
 test('adding a header with multiple values works and stores to a single entry', (t) => {
   const headers = new Headers()
   headers.add('Accept', 'application/json')
   headers.add('Accept', 'text/html')
-  t.is(headers.size, 1)
+  t.is(headers.size, 2)
   t.assert(headers.has('Accept'))
   t.deepEqual(headers.getAll('Accept'), ['application/json', 'text/html'])
   t.deepEqual(headers.getLine('Accept'), 'application/json,text/html')
-  t.deepEqual(headers.get('Accept'), 'text/html')
+  t.deepEqual(headers.get('Accept'), 'application/json')
 })
 
 test('deleting a header adjusts size and removes value', (t) => {

__test__/request.spec.mjs

@@ -33,7 +33,7 @@ test('full construction', (t) => {
   t.assert(req.body instanceof Buffer)
   t.is(req.body.toString('utf8'), 'Hello, from Node.js!')
   t.assert(req.headers instanceof Headers)
-  t.is(req.headers.size, 3)
+  t.is(req.headers.size, 4)
   t.is(req.headers.get('Content-Type'), 'application/json')
   t.deepEqual(req.headers.getAll('Accept'), ['application/json', 'text/html'])
   t.is(req.headers.get('X-Custom-Header'), 'CustomValue')
@@ -58,7 +58,7 @@ test('construction with headers instance', (t) => {
   t.assert(req.body instanceof Buffer)
   t.is(req.body.toString('utf8'), 'Hello, from Node.js!')
   t.assert(req.headers instanceof Headers)
-  t.is(req.headers.size, 3)
+  t.is(req.headers.size, 4)
   t.is(req.headers.get('Content-Type'), 'application/json')
   t.deepEqual(req.headers.getAll('Accept'), ['application/json', 'text/html'])
   t.is(req.headers.get('X-Custom-Header'), 'CustomValue')

__test__/rewriter.spec.mjs

@@ -3,11 +3,13 @@ import test from 'ava'
 import { Request, Rewriter } from '../index.js'
 
 const docroot = import.meta.dirname
+const filename = import.meta.filename.replace(docroot, '')
 
 test('existence condition', (t) => {
   const req = new Request({
+    docroot,
     method: 'GET',
-    url: 'http://example.com/util.mjs',
+    url: `http://example.com${filename}`,
     headers: {
       TEST: ['foo']
     }
@@ -16,7 +18,7 @@ test('existence condition', (t) => {
   const rewriter = new Rewriter([
     {
       conditions: [
-        { type: 'exists' }
+        { type: 'exists', args: [] }
       ],
       rewriters: [
         {
@@ -27,11 +29,12 @@ test('existence condition', (t) => {
     }
   ])
 
-  t.is(rewriter.rewrite(req, docroot).url, 'http://example.com/404')
+  t.is(rewriter.rewrite(req).url, 'http://example.com/404')
 })
 
 test('non-existence condition', (t) => {
   const req = new Request({
+    docroot,
     method: 'GET',
     url: 'http://example.com/index.php',
     headers: {
@@ -53,7 +56,7 @@ test('non-existence condition', (t) => {
     }
   ])
 
-  t.is(rewriter.rewrite(req, docroot).url, 'http://example.com/404')
+  t.is(rewriter.rewrite(req).url, 'http://example.com/404')
 })
 
 test('condition groups - AND', (t) => {
@@ -196,7 +199,7 @@ test('header rewriting', (t) => {
 test('href rewriting', (t) => {
   const rewriter = new Rewriter([{
     rewriters: [
-      { type: 'href', args: [ '^(.*)$', '/index.php?route=${1}' ] }
+      { type: 'href', args: [ '^http://example.com(.*)$', '/index.php?route=${1}' ] }
     ]
   }])
 
@@ -213,7 +216,7 @@ test('href rewriting', (t) => {
 test('method rewriting', (t) => {
   const rewriter = new Rewriter([{
     rewriters: [
-      { type: 'method', args: ['GET', 'POST'] }
+      { type: 'method', args: ['POST'] }
     ]
   }])
 

build.rs

@@ -0,0 +1,22 @@
+use std::env;
+
+#[cfg(feature = "napi-support")]
+extern crate napi_build;
+
+fn main() {
+  #[cfg(feature = "napi-support")]
+  napi_build::setup();
+
+  // Check for manual PHP_RPATH override, otherwise try LD_PRELOAD_PATH,
+  // and finally fallback to hard-coded /usr/local/lib path.
+  //
+  // PHP_RPATH may also be $ORIGIN to instruct the build to search for libphp
+  // in the same directory as the *.node bindings file.
+  let php_rpath = env::var("PHP_RPATH")
+    .or_else(|_| env::var("LD_PRELOAD_PATH"))
+    .unwrap_or("/usr/local/lib".to_string());
+
+  println!("cargo:rustc-link-search={php_rpath}");
+  println!("cargo:rustc-link-lib=dylib=php");
+  println!("cargo:rustc-link-arg=-Wl,-rpath,{php_rpath}");
+}