javascript-solid-server 0.0.8 → 0.0.10

package/.claude/settings.local.json

@@ -13,7 +13,9 @@
       "Bash(pkill:*)",
       "Bash(curl:*)",
       "Bash(npm test:*)",
-      "Bash(git add:*)"
+      "Bash(git add:*)",
+      "WebFetch(domain:solid.github.io)",
+      "Bash(node:*)"
     ]
   }
 }

package/README.md

@@ -35,12 +35,32 @@ 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.10)
 
 - **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)
+- **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
@@ -129,6 +149,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 +229,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: **136 tests**
 
 ## Project Structure
 
@@ -208,12 +290,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 +309,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)

package/benchmark.js

@@ -1,286 +1,182 @@
-import fetch from 'node-fetch';
-import { performance } from 'perf_hooks';
-import { promises as fs } from 'fs';
-import path from 'path';
-
-// Configuration
-const config = {
-  baseUrl: 'http://nostr.social:3000',
-  concurrentUsers: [1, 5, 10, 50, 100], // Different concurrency levels to test
-  operations: 100, // Operations per user
-  testDuration: 30000, // 30 seconds per test
-  testUserPrefix: 'testuser',
-  testPassword: 'benchmark123',
-  results: {
-    registerTime: [],
-    loginTime: [],
-    readTime: [],
-    writeTime: [],
-    deleteTime: [],
-    throughput: []
-  }
-};
-
-// Store tokens for authenticated requests
-const tokens = new Map();
-
-// Utility function to measure execution time
-async function measureTime (fn) {
-  const start = performance.now();
-  const result = await fn();
-  const end = performance.now();
-  return { result, time: end - start };
-}
-
-// Register a test user
-async function registerUser (username) {
-  const { result, time } = await measureTime(async () => {
-    const response = await fetch(`${config.baseUrl}/register`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        username,
-        password: config.testPassword,
-        email: `${username}@benchmark.test`
-      })
-    });
-    return response.json();
+#!/usr/bin/env node
+/**
+ * Benchmark script for JavaScript Solid Server
+ *
+ * Measures throughput and latency for common operations.
+ * Run: node benchmark.js
+ */
+
+import autocannon from 'autocannon';
+import { createServer } from './src/server.js';
+import fs from 'fs-extra';
+
+const PORT = 3030;
+const DURATION = 10; // seconds per test
+const CONNECTIONS = 10;
+
+let server;
+let token;
+
+async function setup() {
+  // Clean data directory
+  await fs.emptyDir('./data');
+
+  // Start server (no logging for clean benchmark)
+  server = createServer({ logger: false });
+  await server.listen({ port: PORT, host: '127.0.0.1' });
+
+  // Create a test pod
+  const res = await fetch(`http://127.0.0.1:${PORT}/.pods`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ name: 'bench' })
   });
+  const data = await res.json();
+  token = data.token;
 
-  config.results.registerTime.push(time);
-  return result;
-}
-
-// Login a test user
-async function loginUser (username) {
-  const { result, time } = await measureTime(async () => {
-    const response = await fetch(`${config.baseUrl}/login`, {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({
-        username,
-        password: config.testPassword
-      })
-    });
-    return response.json();
-  });
-
-  config.results.loginTime.push(time);
-
-  if (result.id_token) {
-    tokens.set(username, result.id_token);
-  }
-
-  return result;
-}
-
-// Create a resource
-async function createResource (username, resourcePath, content = null) {
-  const token = tokens.get(username);
-  if (!token) throw new Error(`No token for user ${username}`);
-
-  const turtleContent = content || `
-    @prefix foaf: <http://xmlns.com/foaf/0.1/>.
-    <#me> a foaf:Person;
-      foaf:name "${username}";
-      foaf:mbox <mailto:${username}@benchmark.test>.
-  `;
-
-  const { result, time } = await measureTime(async () => {
-    const response = await fetch(`${config.baseUrl}/${username}/${resourcePath}`, {
+  // Create some test resources
+  for (let i = 0; i < 100; i++) {
+    await fetch(`http://127.0.0.1:${PORT}/bench/public/item${i}.json`, {
       method: 'PUT',
       headers: {
-        'Content-Type': 'text/turtle',
+        'Content-Type': 'application/ld+json',
         'Authorization': `Bearer ${token}`
       },
-      body: turtleContent
+      body: JSON.stringify({ '@id': `#item${i}`, 'http://example.org/value': i })
     });
-    return response.status;
-  });
+  }
 
-  config.results.writeTime.push(time);
-  return result;
+  console.log('Setup complete: created pod with 100 resources\n');
 }
 
-// Read a resource
-async function readResource (username, resourcePath) {
-  const token = tokens.get(username);
-  if (!token) throw new Error(`No token for user ${username}`);
+async function teardown() {
+  await server.close();
+  await fs.emptyDir('./data');
+}
 
-  const { result, time } = await measureTime(async () => {
-    const response = await fetch(`${config.baseUrl}/${username}/${resourcePath}`, {
-      method: 'GET',
-      headers: {
-        'Authorization': `Bearer ${token}`
-      }
+function runBenchmark(opts) {
+  return new Promise((resolve) => {
+    const instance = autocannon({
+      ...opts,
+      duration: DURATION,
+      connections: CONNECTIONS,
+    }, (err, result) => {
+      resolve(result);
     });
-    return response.status;
-  });
 
-  config.results.readTime.push(time);
-  return result;
+    autocannon.track(instance, { renderProgressBar: false });
+  });
 }
 
-// Delete a resource
-async function deleteResource (username, resourcePath) {
-  const token = tokens.get(username);
-  if (!token) throw new Error(`No token for user ${username}`);
+function formatResult(result) {
+  return {
+    'Requests/sec': Math.round(result.requests.average),
+    'Latency avg': `${result.latency.average.toFixed(2)}ms`,
+    'Latency p99': `${result.latency.p99.toFixed(2)}ms`,
+    'Throughput': `${(result.throughput.average / 1024 / 1024).toFixed(2)} MB/s`
+  };
+}
 
-  const { result, time } = await measureTime(async () => {
-    const response = await fetch(`${config.baseUrl}/${username}/${resourcePath}`, {
-      method: 'DELETE',
-      headers: {
-        'Authorization': `Bearer ${token}`
-      }
-    });
-    return response.status;
+async function benchmarkGET() {
+  console.log('📖 Benchmarking GET (read resource)...');
+  const result = await runBenchmark({
+    url: `http://127.0.0.1:${PORT}/bench/public/item0.json`,
+    method: 'GET'
   });
-
-  config.results.deleteTime.push(time);
-  return result;
+  return formatResult(result);
 }
 
-// Run benchmark for specific concurrency
-async function runBenchmark (concurrentUsers) {
-  console.log(`\n=== Running benchmark with ${concurrentUsers} concurrent users ===`);
-
-  // Create test users
-  console.log('Creating test users...');
-  const users = [];
-  for (let i = 0; i < concurrentUsers; i++) {
-    const username = `${config.testUserPrefix}${i}`;
-    users.push(username);
-    await registerUser(username);
-    await loginUser(username);
-  }
+async function benchmarkGETContainer() {
+  console.log('📂 Benchmarking GET (container listing)...');
+  const result = await runBenchmark({
+    url: `http://127.0.0.1:${PORT}/bench/public/`,
+    method: 'GET'
+  });
+  return formatResult(result);
+}
 
-  // Prepare operation queue (read/write/delete)
-  const operations = [];
-  for (const username of users) {
-    for (let i = 0; i < config.operations; i++) {
-      const resourcePath = `benchmark/resource${i}.ttl`;
-      operations.push(async () => await createResource(username, resourcePath));
-      operations.push(async () => await readResource(username, resourcePath));
-      operations.push(async () => await deleteResource(username, resourcePath));
+let putCounter = 1000;
+async function benchmarkPUT() {
+  console.log('✏️  Benchmarking PUT (create/update resource)...');
+  const result = await runBenchmark({
+    url: `http://127.0.0.1:${PORT}/bench/public/new`,
+    method: 'PUT',
+    headers: {
+      'Content-Type': 'application/ld+json',
+      'Authorization': `Bearer ${token}`
+    },
+    setupClient: (client) => {
+      client.setBody(JSON.stringify({ '@id': '#test', 'http://example.org/v': putCounter++ }));
     }
-  }
-
-  // Run operations with measured throughput
-  console.log(`Starting operations (${operations.length} total)...`);
-  const startTime = performance.now();
-  let completedOps = 0;
-  const endTime = startTime + config.testDuration;
-
-  // Create chunks of operations to run in parallel
-  const chunks = [];
-  const chunkSize = operations.length > 100 ? 100 : operations.length;
-
-  for (let i = 0; i < operations.length; i += chunkSize) {
-    chunks.push(operations.slice(i, i + chunkSize));
-  }
-
-  for (const chunk of chunks) {
-    if (performance.now() >= endTime) break;
-
-    await Promise.all(chunk.map(async (operation) => {
-      if (performance.now() < endTime) {
-        await operation();
-        completedOps++;
-      }
-    }));
-  }
-
-  // Calculate throughput (ops/sec)
-  const actualDuration = Math.min(performance.now() - startTime, config.testDuration);
-  const throughput = (completedOps / actualDuration) * 1000;
-  config.results.throughput.push({
-    concurrentUsers,
-    operations: completedOps,
-    duration: actualDuration,
-    throughput
   });
-
-  console.log(`Completed ${completedOps} operations in ${actualDuration.toFixed(2)}ms`);
-  console.log(`Throughput: ${throughput.toFixed(2)} operations/second`);
+  return formatResult(result);
 }
 
-// Generate report
-async function generateReport () {
-  // Calculate averages
-  const averages = {
-    register: calculateAverage(config.results.registerTime),
-    login: calculateAverage(config.results.loginTime),
-    read: calculateAverage(config.results.readTime),
-    write: calculateAverage(config.results.writeTime),
-    delete: calculateAverage(config.results.deleteTime)
-  };
+async function benchmarkPOST() {
+  console.log('📝 Benchmarking POST (create in container)...');
+  const result = await runBenchmark({
+    url: `http://127.0.0.1:${PORT}/bench/public/`,
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/ld+json',
+      'Authorization': `Bearer ${token}`
+    },
+    body: JSON.stringify({ '@id': '#new', 'http://example.org/created': true })
+  });
+  return formatResult(result);
+}
 
-  // Create report
-  const report = {
-    timestamp: new Date().toISOString(),
-    server: config.baseUrl,
-    testDuration: config.testDuration,
-    averageResponseTimes: averages,
-    throughputResults: config.results.throughput
-  };
+async function benchmarkOPTIONS() {
+  console.log('🔍 Benchmarking OPTIONS (discovery)...');
+  const result = await runBenchmark({
+    url: `http://127.0.0.1:${PORT}/bench/public/item0.json`,
+    method: 'OPTIONS'
+  });
+  return formatResult(result);
+}
 
-  // Save report to file
-  await fs.writeFile(
-    `benchmark-report-${new Date().toISOString().replace(/:/g, '-')}.json`,
-    JSON.stringify(report, null, 2)
-  );
+async function benchmarkHEAD() {
+  console.log('📋 Benchmarking HEAD (metadata only)...');
+  const result = await runBenchmark({
+    url: `http://127.0.0.1:${PORT}/bench/public/item0.json`,
+    method: 'HEAD'
+  });
+  return formatResult(result);
+}
 
-  // Display summary
-  console.log('\n=== BENCHMARK RESULTS ===');
-  console.log('Average Response Times (ms):');
-  console.log(`  Register: ${averages.register.toFixed(2)} ms`);
-  console.log(`  Login: ${averages.login.toFixed(2)} ms`);
-  console.log(`  Read: ${averages.read.toFixed(2)} ms`);
-  console.log(`  Write: ${averages.write.toFixed(2)} ms`);
-  console.log(`  Delete: ${averages.delete.toFixed(2)} ms`);
+async function main() {
+  console.log('🚀 JavaScript Solid Server Benchmark');
+  console.log('=====================================');
+  console.log(`Duration: ${DURATION}s per test, ${CONNECTIONS} concurrent connections\n`);
 
-  console.log('\nThroughput Results:');
-  config.results.throughput.forEach(result => {
-    console.log(`  ${result.concurrentUsers} users: ${result.throughput.toFixed(2)} ops/sec`);
-  });
+  await setup();
 
-  console.log('\nReport saved to file.');
-}
+  const results = {};
 
-// Calculate average of an array
-function calculateAverage (array) {
-  if (array.length === 0) return 0;
-  return array.reduce((sum, value) => sum + value, 0) / array.length;
-}
+  results['GET resource'] = await benchmarkGET();
+  results['GET container'] = await benchmarkGETContainer();
+  results['HEAD'] = await benchmarkHEAD();
+  results['OPTIONS'] = await benchmarkOPTIONS();
+  results['PUT'] = await benchmarkPUT();
+  results['POST'] = await benchmarkPOST();
 
-// Main benchmark function
-async function startBenchmark () {
-  console.log('=== JavaScript Solid Server Benchmark ===');
-  console.log(`Server URL: ${config.baseUrl}`);
-  console.log(`Test Duration: ${config.testDuration / 1000} seconds per concurrency level`);
+  console.log('\n📊 Results Summary');
+  console.log('==================\n');
 
-  try {
-    // Check if server is running
-    const response = await fetch(config.baseUrl);
-    if (response.status < 200 || response.status >= 500) {
-      throw new Error(`Server responded with status ${response.status}`);
-    }
-  } catch (error) {
-    console.error('Error connecting to server:', error.message);
-    console.error('Please make sure the server is running before starting the benchmark.');
-    return;
+  // Print as table
+  console.log('| Operation | Req/sec | Avg Latency | p99 Latency |');
+  console.log('|-----------|---------|-------------|-------------|');
+  for (const [op, data] of Object.entries(results)) {
+    console.log(`| ${op.padEnd(13)} | ${String(data['Requests/sec']).padStart(7)} | ${data['Latency avg'].padStart(11)} | ${data['Latency p99'].padStart(11)} |`);
   }
 
-  // Run tests for each concurrency level
-  for (const concurrentUsers of config.concurrentUsers) {
-    await runBenchmark(concurrentUsers);
-  }
+  console.log('\n');
+
+  await teardown();
 
-  // Generate final report
-  await generateReport();
+  // Output JSON for README
+  console.log('JSON results:');
+  console.log(JSON.stringify(results, null, 2));
 }
 
-// Start the benchmark
-startBenchmark().catch(error => {
-  console.error('Benchmark error:', error);
-}); 
+main().catch(console.error);

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "javascript-solid-server",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "description": "A minimal, fast Solid server",
   "main": "src/index.js",
   "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JavaScriptSolidServer/JavaScriptSolidServer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/JavaScriptSolidServer/JavaScriptSolidServer/issues"
+  },
+  "homepage": "https://github.com/JavaScriptSolidServer/JavaScriptSolidServer#readme",
   "scripts": {
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
-    "test": "node --test --test-concurrency=1"
+    "test": "node --test --test-concurrency=1",
+    "benchmark": "node benchmark.js"
   },
   "dependencies": {
+    "@fastify/websocket": "^8.3.1",
     "fastify": "^4.25.2",
     "fs-extra": "^11.2.0",
     "jose": "^6.1.3",
@@ -24,5 +34,8 @@
     "linked-data",
     "decentralized"
   ],
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "autocannon": "^8.0.0"
+  }
 }

package/src/handlers/container.js

@@ -5,6 +5,7 @@ import { generateProfile, generatePreferences, generateTypeIndex, serialize } fr
 import { generateOwnerAcl, generatePrivateAcl, generateInboxAcl, serializeAcl } from '../wac/parser.js';
 import { createToken } from '../auth/token.js';
 import { canAcceptInput, toJsonLd, getVaryHeader, RDF_TYPES } from '../rdf/conneg.js';
+import { emitChange } from '../notifications/events.js';
 
 /**
  * Handle POST request to container (create new resource)
@@ -97,6 +98,12 @@ export async function handlePost(request, reply) {
   headers['Vary'] = getVaryHeader(connegEnabled);
 
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  // Emit change notification for WebSocket subscribers
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
   return reply.code(201).send();
 }