javascript-solid-server 0.0.2

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)",
+      "Bash(cat:*)",
+      "WebFetch(domain:www.inrupt.com)",
+      "Bash(npm install:*)",
+      "Bash(timeout 3 node:*)",
+      "Bash(PORT=3030 timeout 3 node:*)",
+      "Bash(git commit:*)"
+    ]
+  }
+}

package/README.md

@@ -0,0 +1,209 @@
+# Vision
+
+The goal of this project is to create a hyper-modern, performant, and minimalist JavaScript Solid server. While drawing inspiration from Node Solid Server (NSS), this new implementation will address its shortcomings and prioritize scalability, modularity, and developer usability.
+
+## Key Objectives
+
+- **Performance First:** Capable of handling enterprise-scale loads, targeting thousands to millions of users.
+- **Minimalist Design:** Remove unused and experimental features; focus on what matters most.
+- **Modularity:** Clear separation of identity, authentication, storage, and onboarding.
+- **Developer Friendly:** Clean, well-documented, and extensible codebase that adheres to the Solid specification.
+- **Modern Tooling:** Leverage async/await, native modules, fast HTTP servers like Fastify, and cutting-edge JavaScript runtimes.
+- **HTTP Simplicity:** Prioritize simple HTTP/1.1 compatibility for maximum interoperability.
+- **Frontend Agnostic:** Work with any frontend or application layer via standardized APIs.
+- **Testable and CI Ready:** Fully integrated with Solid test suites and modern CI/CD pipelines.
+
+---
+
+# ARCHITECTURE
+
+## Overview
+
+The architecture is inspired by NSS but modernized and streamlined. Each subsystem is designed to operate independently and follow the single-responsibility principle.
+
+### Components
+
+- **HTTP Layer**
+
+  - Fastify server
+  - Routing and middleware based on HTTP verbs and Solid operations
+  - Blazingly fast, with benchmarks from the start
+
+- **Identity Provider (IDP)**
+
+  - Handles Pod based WebIDs
+  - Handles external WebIDs
+  - Minimal by default, extendable via plugins
+
+- **Authenticaion Module (AUthn)**
+
+  - Handles WebID-based authentication, including WebID-TLS
+  - OIDC-compliant with modular Authentication
+  - Single sign-on including WebID-TLS
+
+- **Authorization Module (Authz)**
+
+  - Supports Web Access Control (WAC)
+  - Token-based permissions model
+  - Modular Authorization system
+
+- **Storage Engine**
+
+  - Modular backend adapters (e.g. file system, S3, memory)
+  - POD-level quota management (optional)
+  - Interoperable with existing Cloud
+
+- **Account and Onboarding**
+  - API-first registration
+  - Public, private, invite modes
+  - Extensible account templates
+
+### Deployment Model
+
+- Works as a single binary or serverless function
+- Container-friendly (Docker, Deno, etc.)
+- CLI for local dev setup and testing
+
+### Separation of Concerns
+
+- Each subsystem lives in its own module/package
+- Clear boundaries between IDP and storage
+- Frontend-independent API endpoints
+
+### Compatibility
+
+- Solid-compliant, LWS Compliant
+- API parity with NSS where applicable
+- API parity with CSS where applicable
+
+---
+
+# MVP Implementation
+
+This is a minimal viable product (MVP) implementation of the JavaScriptSolid server. It includes the core components needed to demonstrate the concept while omitting some of the more complex features for simplicity.
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18 or higher
+
+### Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/javascript-solid-server.git
+cd javascript-solid-server
+
+# Install dependencies
+npm install
+```
+
+### Running the Server
+
+```bash
+# Start the server
+npm start
+```
+
+The server will be available at http://localhost:3000 by default.
+
+## Features Included in MVP
+
+- **HTTP Server**: Based on Fastify for high performance
+- **Basic Identity Provider**: Simple user registration and login with JWT tokens
+- **Simple Authorization**: Basic implementation of WAC (Web Access Control)
+- **File-based Storage**: Local filesystem storage for Solid resources
+- **Basic Solid Protocol Support**: GET, PUT, DELETE, PATCH, and HEAD operations
+
+## Features Omitted in MVP (to be added later)
+
+1. WebID-TLS Authentication
+2. Full OIDC implementation
+3. Advanced WAC features and ACL file parsing
+4. Quotas and resource limits
+5. Advanced container management
+6. SPARQL and N3 Patch support
+7. Notification systems
+
+## API Usage Examples
+
+### User Registration
+
+```bash
+curl -X POST http://localhost:3000/register \
+  -H "Content-Type: application/json" \
+  -d '{"username": "alice", "password": "secret", "email": "alice@example.com"}'
+```
+
+### Login
+
+```bash
+curl -X POST http://localhost:3000/login \
+  -H "Content-Type: application/json" \
+  -d '{"username": "alice", "password": "secret"}'
+```
+
+### Accessing Resources
+
+```bash
+# Get a resource
+curl -X GET http://localhost:3000/alice/profile \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE"
+
+# Create or update a resource
+curl -X PUT http://localhost:3000/alice/profile \
+  -H "Authorization: Bearer YOUR_TOKEN_HERE" \
+  -H "Content-Type: text/turtle" \
+  -d '@prefix foaf: <http://xmlns.com/foaf/0.1/>. <#me> a foaf:Person; foaf:name "Alice".'
+```
+
+## Performance Benchmarking
+
+This project includes a comprehensive benchmarking tool to measure server performance under various loads.
+
+### Running the Benchmark
+
+```bash
+# Make sure the server is running in a separate terminal
+npm start
+
+# In another terminal, run the benchmark
+npm run benchmark
+```
+
+The benchmark will:
+
+1. Create multiple test users
+2. Execute various operations (register, login, read, write, delete)
+3. Measure response times for each operation type
+4. Test different concurrency levels (1, 5, 10, 50, 100 users)
+5. Calculate throughput (operations per second)
+
+### Visualizing Results
+
+After running the benchmark, you can generate a visual report:
+
+```bash
+# Generate an HTML report with charts
+npm run visualize benchmark-report-[timestamp].json
+```
+
+Open the generated HTML file in a browser to see:
+
+- Average response times for each operation type
+- Throughput metrics at different concurrency levels
+- Visual charts for easy performance analysis
+
+### Customizing Benchmarks
+
+You can customize the benchmark parameters in `benchmark.js`:
+
+- Concurrent users levels
+- Operations per user
+- Test duration
+- Test user credentials
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

package/benchmark-report-2025-03-31T14-25-24.234Z.json

@@ -0,0 +1,44 @@
+{
+  "timestamp": "2025-03-31T14:25:24.234Z",
+  "server": "http://nostr.social:3000",
+  "testDuration": 30000,
+  "averageResponseTimes": {
+    "register": 49.28774029878249,
+    "login": 49.07647125548627,
+    "read": 145.50252931779679,
+    "write": 143.20483738812226,
+    "delete": 145.5004399698014
+  },
+  "throughputResults": [
+    {
+      "concurrentUsers": 1,
+      "operations": 300,
+      "duration": 629.3636230230331,
+      "throughput": 476.67197312581374
+    },
+    {
+      "concurrentUsers": 5,
+      "operations": 1500,
+      "duration": 3072.7389999628067,
+      "throughput": 488.16381736885444
+    },
+    {
+      "concurrentUsers": 10,
+      "operations": 3000,
+      "duration": 6042.516402959824,
+      "throughput": 496.4818959416479
+    },
+    {
+      "concurrentUsers": 50,
+      "operations": 14000,
+      "duration": 30000,
+      "throughput": 466.6666666666667
+    },
+    {
+      "concurrentUsers": 100,
+      "operations": 13900,
+      "duration": 30000,
+      "throughput": 463.3333333333333
+    }
+  ]
+}

package/benchmark.js

@@ -0,0 +1,286 @@
+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();
+  });
+
+  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}`, {
+      method: 'PUT',
+      headers: {
+        'Content-Type': 'text/turtle',
+        'Authorization': `Bearer ${token}`
+      },
+      body: turtleContent
+    });
+    return response.status;
+  });
+
+  config.results.writeTime.push(time);
+  return result;
+}
+
+// Read a resource
+async function readResource (username, resourcePath) {
+  const token = tokens.get(username);
+  if (!token) throw new Error(`No token for user ${username}`);
+
+  const { result, time } = await measureTime(async () => {
+    const response = await fetch(`${config.baseUrl}/${username}/${resourcePath}`, {
+      method: 'GET',
+      headers: {
+        'Authorization': `Bearer ${token}`
+      }
+    });
+    return response.status;
+  });
+
+  config.results.readTime.push(time);
+  return result;
+}
+
+// Delete a resource
+async function deleteResource (username, resourcePath) {
+  const token = tokens.get(username);
+  if (!token) throw new Error(`No token for user ${username}`);
+
+  const { result, time } = await measureTime(async () => {
+    const response = await fetch(`${config.baseUrl}/${username}/${resourcePath}`, {
+      method: 'DELETE',
+      headers: {
+        'Authorization': `Bearer ${token}`
+      }
+    });
+    return response.status;
+  });
+
+  config.results.deleteTime.push(time);
+  return 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);
+  }
+
+  // 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));
+    }
+  }
+
+  // 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`);
+}
+
+// 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)
+  };
+
+  // Create report
+  const report = {
+    timestamp: new Date().toISOString(),
+    server: config.baseUrl,
+    testDuration: config.testDuration,
+    averageResponseTimes: averages,
+    throughputResults: config.results.throughput
+  };
+
+  // Save report to file
+  await fs.writeFile(
+    `benchmark-report-${new Date().toISOString().replace(/:/g, '-')}.json`,
+    JSON.stringify(report, null, 2)
+  );
+
+  // 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`);
+
+  console.log('\nThroughput Results:');
+  config.results.throughput.forEach(result => {
+    console.log(`  ${result.concurrentUsers} users: ${result.throughput.toFixed(2)} ops/sec`);
+  });
+
+  console.log('\nReport saved to file.');
+}
+
+// Calculate average of an array
+function calculateAverage (array) {
+  if (array.length === 0) return 0;
+  return array.reduce((sum, value) => sum + value, 0) / array.length;
+}
+
+// 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`);
+
+  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;
+  }
+
+  // Run tests for each concurrency level
+  for (const concurrentUsers of config.concurrentUsers) {
+    await runBenchmark(concurrentUsers);
+  }
+
+  // Generate final report
+  await generateReport();
+}
+
+// Start the benchmark
+startBenchmark().catch(error => {
+  console.error('Benchmark error:', error);
+}); 

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "javascript-solid-server",
+  "version": "0.0.2",
+  "description": "A minimal, fast Solid server",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "test": "node --test"
+  },
+  "dependencies": {
+    "fastify": "^4.25.2",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["solid", "ldp", "linked-data", "decentralized"],
+  "license": "MIT"
+}

package/src/handlers/container.js

@@ -0,0 +1,110 @@
+import * as storage from '../storage/filesystem.js';
+import { getAllHeaders } from '../ldp/headers.js';
+import { isContainer } from '../utils/url.js';
+
+/**
+ * Handle POST request to container (create new resource)
+ */
+export async function handlePost(request, reply) {
+  const urlPath = request.url.split('?')[0];
+
+  // Ensure target is a container
+  if (!isContainer(urlPath)) {
+    return reply.code(405).send({ error: 'POST only allowed on containers' });
+  }
+
+  // Check container exists
+  const stats = await storage.stat(urlPath);
+  if (!stats || !stats.isDirectory) {
+    // Create container if it doesn't exist
+    await storage.createContainer(urlPath);
+  }
+
+  // Get slug from header or generate UUID
+  const slug = request.headers.slug;
+  const linkHeader = request.headers.link || '';
+
+  // Check if creating a container (Link header contains ldp:Container or ldp:BasicContainer)
+  const isCreatingContainer = linkHeader.includes('Container') || linkHeader.includes('BasicContainer');
+
+  // Generate unique filename
+  const filename = await storage.generateUniqueFilename(urlPath, slug, isCreatingContainer);
+  const newPath = urlPath + filename + (isCreatingContainer ? '/' : '');
+
+  let success;
+  if (isCreatingContainer) {
+    success = await storage.createContainer(newPath);
+  } else {
+    // Get content from request body
+    let content = request.body;
+    if (Buffer.isBuffer(content)) {
+      // Already a buffer
+    } else if (typeof content === 'string') {
+      content = Buffer.from(content);
+    } else if (content && typeof content === 'object') {
+      content = Buffer.from(JSON.stringify(content));
+    } else {
+      content = Buffer.from('');
+    }
+    success = await storage.write(newPath, content);
+  }
+
+  if (!success) {
+    return reply.code(500).send({ error: 'Create failed' });
+  }
+
+  const location = `${request.protocol}://${request.hostname}${newPath}`;
+  const origin = request.headers.origin;
+
+  const headers = getAllHeaders({
+    isContainer: isCreatingContainer,
+    origin
+  });
+  headers['Location'] = location;
+
+  Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+  return reply.code(201).send();
+}
+
+/**
+ * Create a pod (container) for a user
+ * POST /.pods with { "name": "alice" }
+ */
+export async function handleCreatePod(request, reply) {
+  const { name } = request.body || {};
+
+  if (!name || typeof name !== 'string') {
+    return reply.code(400).send({ error: 'Pod name required' });
+  }
+
+  // Validate pod name (alphanumeric, dash, underscore)
+  if (!/^[a-zA-Z0-9_-]+$/.test(name)) {
+    return reply.code(400).send({ error: 'Invalid pod name. Use alphanumeric, dash, or underscore only.' });
+  }
+
+  const podPath = `/${name}/`;
+
+  // Check if pod already exists
+  if (await storage.exists(podPath)) {
+    return reply.code(409).send({ error: 'Pod already exists' });
+  }
+
+  // Create pod container
+  const success = await storage.createContainer(podPath);
+  if (!success) {
+    return reply.code(500).send({ error: 'Failed to create pod' });
+  }
+
+  const location = `${request.protocol}://${request.hostname}${podPath}`;
+  const origin = request.headers.origin;
+
+  const headers = getAllHeaders({ isContainer: true, origin });
+  headers['Location'] = location;
+
+  Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
+
+  return reply.code(201).send({
+    name,
+    url: location
+  });
+}