javascript-solid-server 0.0.9 → 0.0.11

package/.claude/settings.local.json

@@ -15,7 +15,12 @@
       "Bash(npm test:*)",
       "Bash(git add:*)",
       "WebFetch(domain:solid.github.io)",
-      "Bash(node:*)"
+      "Bash(node:*)",
+      "WebFetch(domain:solidservers.org)",
+      "WebFetch(domain:solid-contrib.github.io)",
+      "Bash(git clone:*)",
+      "Bash(chmod:*)",
+      "Bash(JSS_PORT=4000 JSS_CONNEG=true node bin/jss.js:*)"
     ]
   }
 }

package/README.md

@@ -35,12 +35,34 @@ const server = createServer();
 const serverWithConneg = createServer({ conneg: true });
 ```
 
+## Performance
+
+This server is designed for speed. Benchmark results on a typical development machine:
+
+| Operation | Requests/sec | Avg Latency | p99 Latency |
+|-----------|-------------|-------------|-------------|
+| GET resource | 5,400+ | 1.2ms | 3ms |
+| GET container | 4,700+ | 1.6ms | 3ms |
+| PUT (write) | 5,700+ | 1.1ms | 2ms |
+| POST (create) | 5,200+ | 1.3ms | 3ms |
+| OPTIONS | 10,000+ | 0.4ms | 1ms |
+
+Run benchmarks yourself:
+```bash
+npm run benchmark
+```
+
 ## Features
 
-### Implemented (v0.0.8)
+### Implemented (v0.0.11)
 
 - **LDP CRUD Operations** - GET, PUT, POST, DELETE, HEAD
 - **N3 Patch** - Solid's native patch format for RDF updates
+- **SPARQL Update** - Standard SPARQL UPDATE protocol for PATCH
+- **Conditional Requests** - If-Match/If-None-Match headers (304, 412)
+- **CLI & Config** - `jss` command with config file/env var support
+- **SSL/TLS** - HTTPS support with certificate configuration
+- **WebSocket Notifications** - Real-time updates via solid-0.1 protocol (SolidOS compatible)
 - **Container Management** - Create, list, and manage containers
 - **Multi-user Pods** - Create pods at `/<username>/`
 - **WebID Profiles** - JSON-LD structured data in HTML at pod root
@@ -72,18 +94,75 @@ const serverWithConneg = createServer({ conneg: true });
 
 ```bash
 npm install
+
+# Or install globally
+npm install -g javascript-solid-server
+```
+
+### Quick Start
+
+```bash
+# Initialize configuration (interactive)
+jss init
+
+# Start server
+jss start
+
+# Or with options
+jss start --port 8443 --ssl-key ./key.pem --ssl-cert ./cert.pem
+```
+
+### CLI Commands
+
+```bash
+jss start [options]    # Start the server
+jss init [options]     # Initialize configuration
+jss --help             # Show help
 ```
 
-### Running
+### Start Options
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `-p, --port <n>` | Port to listen on | 3000 |
+| `-h, --host <addr>` | Host to bind to | 0.0.0.0 |
+| `-r, --root <path>` | Data directory | ./data |
+| `-c, --config <file>` | Config file path | - |
+| `--ssl-key <path>` | SSL private key (PEM) | - |
+| `--ssl-cert <path>` | SSL certificate (PEM) | - |
+| `--conneg` | Enable Turtle support | false |
+| `--notifications` | Enable WebSocket | false |
+| `-q, --quiet` | Suppress logs | false |
+
+### Environment Variables
+
+All options can be set via environment variables with `JSS_` prefix:
 
 ```bash
-# Start server (default port 3000)
-npm start
+export JSS_PORT=8443
+export JSS_SSL_KEY=/path/to/key.pem
+export JSS_SSL_CERT=/path/to/cert.pem
+export JSS_CONNEG=true
+jss start
+```
+
+### Config File
+
+Create `config.json`:
 
-# Development mode with watch
-npm dev
+```json
+{
+  "port": 8443,
+  "root": "./data",
+  "sslKey": "./ssl/key.pem",
+  "sslCert": "./ssl/cert.pem",
+  "conneg": true,
+  "notifications": true
+}
 ```
 
+Then: `jss start --config config.json`
+
 ### Creating a Pod
 
 ```bash
@@ -129,6 +208,44 @@ curl -X PATCH http://localhost:3000/alice/public/data.json \
         solid:inserts { <#data> <http://example.org/name> "Updated" }.'
 ```
 
+### PATCH with SPARQL Update
+
+```bash
+curl -X PATCH http://localhost:3000/alice/public/data.json \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/sparql-update" \
+  -d 'PREFIX ex: <http://example.org/>
+      DELETE DATA { <#data> ex:value 42 } ;
+      INSERT DATA { <#data> ex:value 43 }'
+```
+
+### Conditional Requests
+
+Use `If-Match` for safe updates (optimistic concurrency):
+
+```bash
+# Get current ETag
+ETAG=$(curl -sI http://localhost:3000/alice/public/data.json | grep -i etag | awk '{print $2}')
+
+# Update only if ETag matches
+curl -X PUT http://localhost:3000/alice/public/data.json \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/ld+json" \
+  -H "If-Match: $ETAG" \
+  -d '{"@id": "#data", "http://example.org/value": 100}'
+```
+
+Use `If-None-Match: *` for create-only semantics:
+
+```bash
+# Create only if resource doesn't exist (returns 412 if it does)
+curl -X PUT http://localhost:3000/alice/public/new-resource.json \
+  -H "Authorization: Bearer YOUR_TOKEN" \
+  -H "Content-Type: application/ld+json" \
+  -H "If-None-Match: *" \
+  -d '{"@id": "#new"}'
+```
+
 ## Pod Structure
 
 ```
@@ -171,18 +288,42 @@ curl -H "Authorization: DPoP ACCESS_TOKEN" \
 
 ```javascript
 createServer({
-  logger: true,     // Enable Fastify logging (default: true)
-  conneg: false     // Enable content negotiation (default: false)
+  logger: true,        // Enable Fastify logging (default: true)
+  conneg: false,       // Enable content negotiation (default: false)
+  notifications: false // Enable WebSocket notifications (default: false)
 });
 ```
 
+### WebSocket Notifications
+
+Enable real-time notifications for resource changes:
+
+```javascript
+const server = createServer({ notifications: true });
+```
+
+Clients discover the WebSocket URL via the `Updates-Via` header:
+
+```bash
+curl -I http://localhost:3000/alice/public/
+# Updates-Via: ws://localhost:3000/.notifications
+```
+
+Protocol (solid-0.1, compatible with SolidOS):
+```
+Server: protocol solid-0.1
+Client: sub http://localhost:3000/alice/public/data.json
+Server: ack http://localhost:3000/alice/public/data.json
+Server: pub http://localhost:3000/alice/public/data.json  (on change)
+```
+
 ## Running Tests
 
 ```bash
 npm test
 ```
 
-Currently passing: **105 tests**
+Currently passing: **163 tests** (including 27 conformance tests)
 
 ## Project Structure
 
@@ -208,12 +349,18 @@ src/
 ├── webid/
 │   └── profile.js        # WebID generation
 ├── patch/
-│   └── n3-patch.js       # N3 Patch support
+│   ├── n3-patch.js       # N3 Patch support
+│   └── sparql-update.js  # SPARQL Update support
+├── notifications/
+│   ├── index.js          # WebSocket plugin
+│   ├── events.js         # Event emitter
+│   └── websocket.js      # solid-0.1 protocol
 ├── rdf/
 │   ├── turtle.js         # Turtle <-> JSON-LD
 │   └── conneg.js         # Content negotiation
 └── utils/
-    └── url.js            # URL utilities
+    ├── url.js            # URL utilities
+    └── conditional.js    # If-Match/If-None-Match
 ```
 
 ## Dependencies
@@ -221,6 +368,7 @@ src/
 Minimal dependencies for a fast, secure server:
 
 - **fastify** - High-performance HTTP server
+- **@fastify/websocket** - WebSocket support for notifications
 - **fs-extra** - Enhanced file operations
 - **jose** - JWT/JWK handling for Solid-OIDC
 - **n3** - Turtle parsing (only used when conneg enabled)