javascript-solid-server 0.0.8 → 0.0.10

package/src/handlers/resource.js

@@ -3,6 +3,7 @@ import { getAllHeaders } from '../ldp/headers.js';
 import { generateContainerJsonLd, serializeJsonLd } from '../ldp/container.js';
 import { isContainer, getContentType, isRdfContentType } from '../utils/url.js';
 import { parseN3Patch, applyN3Patch, validatePatch } from '../patch/n3-patch.js';
+import { parseSparqlUpdate, applySparqlUpdate } from '../patch/sparql-update.js';
 import {
   selectContentType,
   canAcceptInput,
@@ -11,6 +12,8 @@ import {
   getVaryHeader,
   RDF_TYPES
 } from '../rdf/conneg.js';
+import { emitChange } from '../notifications/events.js';
+import { checkIfMatch, checkIfNoneMatchForGet, checkIfNoneMatchForWrite } from '../utils/conditional.js';
 
 /**
  * Handle GET request
@@ -23,6 +26,15 @@ export async function handleGet(request, reply) {
     return reply.code(404).send({ error: 'Not Found' });
   }
 
+  // Check If-None-Match for conditional GET (304 Not Modified)
+  const ifNoneMatch = request.headers['if-none-match'];
+  if (ifNoneMatch) {
+    const check = checkIfNoneMatchForGet(ifNoneMatch, stats.etag);
+    if (!check.ok && check.notModified) {
+      return reply.code(304).send();
+    }
+  }
+
   const origin = request.headers.origin;
   const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
 
@@ -184,8 +196,28 @@ export async function handlePut(request, reply) {
     });
   }
 
-  // Check if resource already exists
-  const existed = await storage.exists(urlPath);
+  // Check if resource already exists and get current ETag
+  const stats = await storage.stat(urlPath);
+  const existed = stats !== null;
+  const currentEtag = stats?.etag || null;
+
+  // Check If-Match header (for safe updates)
+  const ifMatch = request.headers['if-match'];
+  if (ifMatch) {
+    const check = checkIfMatch(ifMatch, currentEtag);
+    if (!check.ok) {
+      return reply.code(check.status).send({ error: check.error });
+    }
+  }
+
+  // Check If-None-Match header (for create-only semantics)
+  const ifNoneMatch = request.headers['if-none-match'];
+  if (ifNoneMatch) {
+    const check = checkIfNoneMatchForWrite(ifNoneMatch, currentEtag);
+    if (!check.ok) {
+      return reply.code(check.status).send({ error: check.error });
+    }
+  }
 
   // Get content from request body
   let content = request.body;
@@ -226,6 +258,12 @@ export async function handlePut(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(existed ? 204 : 201).send();
 }
 
@@ -235,11 +273,21 @@ export async function handlePut(request, reply) {
 export async function handleDelete(request, reply) {
   const urlPath = request.url.split('?')[0];
 
-  const existed = await storage.exists(urlPath);
-  if (!existed) {
+  // Check if resource exists and get current ETag
+  const stats = await storage.stat(urlPath);
+  if (!stats) {
     return reply.code(404).send({ error: 'Not Found' });
   }
 
+  // Check If-Match header (for safe deletes)
+  const ifMatch = request.headers['if-match'];
+  if (ifMatch) {
+    const check = checkIfMatch(ifMatch, stats.etag);
+    if (!check.ok) {
+      return reply.code(check.status).send({ error: check.error });
+    }
+  }
+
   const success = await storage.remove(urlPath);
   if (!success) {
     return reply.code(500).send({ error: 'Delete failed' });
@@ -250,6 +298,11 @@ export async function handleDelete(request, reply) {
   const headers = getAllHeaders({ isContainer: false, origin, resourceUrl });
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 
+  // Emit change notification for WebSocket subscribers
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
   return reply.code(204).send();
 }
 
@@ -274,7 +327,7 @@ export async function handleOptions(request, reply) {
 
 /**
  * Handle PATCH request
- * Supports N3 Patch format (text/n3) for updating RDF resources
+ * Supports N3 Patch format (text/n3) and SPARQL Update for updating RDF resources
  */
 export async function handlePatch(request, reply) {
   const urlPath = request.url.split('?')[0];
@@ -286,14 +339,13 @@ export async function handlePatch(request, reply) {
 
   // Check content type
   const contentType = request.headers['content-type'] || '';
-  const isN3Patch = contentType.includes('text/n3') ||
-                    contentType.includes('application/n3') ||
-                    contentType.includes('application/sparql-update');
+  const isN3Patch = contentType.includes('text/n3') || contentType.includes('application/n3');
+  const isSparqlUpdate = contentType.includes('application/sparql-update');
 
-  if (!isN3Patch) {
+  if (!isN3Patch && !isSparqlUpdate) {
     return reply.code(415).send({
       error: 'Unsupported Media Type',
-      message: 'PATCH requires Content-Type: text/n3 for N3 Patch format'
+      message: 'PATCH requires Content-Type: text/n3 (N3 Patch) or application/sparql-update (SPARQL Update)'
     });
   }
 
@@ -303,6 +355,15 @@ export async function handlePatch(request, reply) {
     return reply.code(404).send({ error: 'Not Found' });
   }
 
+  // Check If-Match header (for safe updates)
+  const ifMatch = request.headers['if-match'];
+  if (ifMatch) {
+    const check = checkIfMatch(ifMatch, stats.etag);
+    if (!check.ok) {
+      return reply.code(check.status).send({ error: check.error });
+    }
+  }
+
   // Read existing content
   const existingContent = await storage.read(urlPath);
   if (existingContent === null) {
@@ -326,31 +387,49 @@ export async function handlePatch(request, reply) {
     : request.body;
 
   const resourceUrl = `${request.protocol}://${request.hostname}${urlPath}`;
-  let patch;
-  try {
-    patch = parseN3Patch(patchContent, resourceUrl);
-  } catch (e) {
-    return reply.code(400).send({
-      error: 'Bad Request',
-      message: 'Invalid N3 Patch format: ' + e.message
-    });
-  }
 
-  // Validate that deletes exist (optional strict mode)
-  // const validation = validatePatch(document, patch, resourceUrl);
-  // if (!validation.valid) {
-  //   return reply.code(409).send({ error: 'Conflict', message: validation.error });
-  // }
-
-  // Apply the patch
   let updatedDocument;
-  try {
-    updatedDocument = applyN3Patch(document, patch, resourceUrl);
-  } catch (e) {
-    return reply.code(409).send({
-      error: 'Conflict',
-      message: 'Failed to apply patch: ' + e.message
-    });
+
+  if (isSparqlUpdate) {
+    // Handle SPARQL Update
+    let update;
+    try {
+      update = parseSparqlUpdate(patchContent, resourceUrl);
+    } catch (e) {
+      return reply.code(400).send({
+        error: 'Bad Request',
+        message: 'Invalid SPARQL Update: ' + e.message
+      });
+    }
+
+    try {
+      updatedDocument = applySparqlUpdate(document, update, resourceUrl);
+    } catch (e) {
+      return reply.code(409).send({
+        error: 'Conflict',
+        message: 'Failed to apply SPARQL Update: ' + e.message
+      });
+    }
+  } else {
+    // Handle N3 Patch
+    let patch;
+    try {
+      patch = parseN3Patch(patchContent, resourceUrl);
+    } catch (e) {
+      return reply.code(400).send({
+        error: 'Bad Request',
+        message: 'Invalid N3 Patch format: ' + e.message
+      });
+    }
+
+    try {
+      updatedDocument = applyN3Patch(document, patch, resourceUrl);
+    } catch (e) {
+      return reply.code(409).send({
+        error: 'Conflict',
+        message: 'Failed to apply patch: ' + e.message
+      });
+    }
   }
 
   // Write updated document
@@ -365,5 +444,10 @@ export async function handlePatch(request, reply) {
   const headers = getAllHeaders({ isContainer: false, origin, resourceUrl });
   Object.entries(headers).forEach(([k, v]) => reply.header(k, v));
 
+  // Emit change notification for WebSocket subscribers
+  if (request.notificationsEnabled) {
+    emitChange(resourceUrl);
+  }
+
   return reply.code(204).send();
 }

package/src/ldp/headers.js

@@ -49,7 +49,7 @@ export function getAclUrl(resourceUrl, isContainer) {
  * @param {object} options
  * @returns {object}
  */
-export function getResponseHeaders({ isContainer = false, etag = null, contentType = null, resourceUrl = null, wacAllow = null, connegEnabled = false }) {
+export function getResponseHeaders({ isContainer = false, etag = null, contentType = null, resourceUrl = null, wacAllow = null, connegEnabled = false, updatesVia = null }) {
   // Calculate ACL URL if resource URL provided
   const aclUrl = resourceUrl ? getAclUrl(resourceUrl, isContainer) : null;
 
@@ -65,6 +65,11 @@ export function getResponseHeaders({ isContainer = false, etag = null, contentTy
   const acceptHeaders = getAcceptHeaders(connegEnabled, isContainer);
   Object.assign(headers, acceptHeaders);
 
+  // Add Updates-Via header for WebSocket notifications discovery
+  if (updatesVia) {
+    headers['Updates-Via'] = updatesVia;
+  }
+
   if (etag) {
     headers['ETag'] = etag;
   }
@@ -86,7 +91,7 @@ export function getCorsHeaders(origin) {
     'Access-Control-Allow-Origin': origin || '*',
     'Access-Control-Allow-Methods': 'GET, HEAD, POST, PUT, DELETE, PATCH, OPTIONS',
     'Access-Control-Allow-Headers': 'Accept, Authorization, Content-Type, If-Match, If-None-Match, Link, Slug, Origin',
-    'Access-Control-Expose-Headers': 'Accept-Patch, Accept-Post, Allow, Content-Type, ETag, Link, Location, WAC-Allow',
+    'Access-Control-Expose-Headers': 'Accept-Patch, Accept-Post, Allow, Content-Type, ETag, Link, Location, Updates-Via, WAC-Allow',
     'Access-Control-Allow-Credentials': 'true',
     'Access-Control-Max-Age': '86400'
   };
@@ -97,9 +102,9 @@ export function getCorsHeaders(origin) {
  * @param {object} options
  * @returns {object}
  */
-export function getAllHeaders({ isContainer = false, etag = null, contentType = null, origin = null, resourceUrl = null, wacAllow = null, connegEnabled = false }) {
+export function getAllHeaders({ isContainer = false, etag = null, contentType = null, origin = null, resourceUrl = null, wacAllow = null, connegEnabled = false, updatesVia = null }) {
   return {
-    ...getResponseHeaders({ isContainer, etag, contentType, resourceUrl, wacAllow, connegEnabled }),
+    ...getResponseHeaders({ isContainer, etag, contentType, resourceUrl, wacAllow, connegEnabled, updatesVia }),
     ...getCorsHeaders(origin)
   };
 }

package/src/notifications/events.js

@@ -0,0 +1,22 @@
+/**
+ * Resource Events Emitter
+ *
+ * Singleton EventEmitter for resource change notifications.
+ * Handlers emit 'change' events here, WebSocket broadcasts to subscribers.
+ */
+
+import { EventEmitter } from 'events';
+
+// Singleton event emitter for resource changes
+export const resourceEvents = new EventEmitter();
+
+// Increase max listeners since many WebSocket connections may subscribe
+resourceEvents.setMaxListeners(1000);
+
+/**
+ * Emit a resource change event
+ * @param {string} resourceUrl - Full URL of the changed resource
+ */
+export function emitChange(resourceUrl) {
+  resourceEvents.emit('change', resourceUrl);
+}

package/src/notifications/index.js

@@ -0,0 +1,49 @@
+/**
+ * Notifications Plugin
+ *
+ * Fastify plugin that adds WebSocket notification support.
+ * Implements the legacy "solid-0.1" protocol for SolidOS compatibility.
+ *
+ * Usage:
+ *   createServer({ notifications: true })
+ *
+ * Discovery:
+ *   OPTIONS /resource returns Updates-Via header with WebSocket URL
+ *
+ * Client usage:
+ *   const ws = new WebSocket(updatesViaUrl);
+ *   ws.send('sub http://example.org/resource');
+ *   ws.onmessage = (e) => { if (e.data.startsWith('pub ')) ... }
+ */
+
+import websocket from '@fastify/websocket';
+import { handleWebSocket, getConnectionCount, getSubscriptionCount } from './websocket.js';
+export { emitChange } from './events.js';
+
+/**
+ * Register the notifications plugin with Fastify
+ * @param {FastifyInstance} fastify
+ * @param {object} options
+ */
+export async function notificationsPlugin(fastify, options) {
+  // Register the WebSocket plugin
+  await fastify.register(websocket);
+
+  // WebSocket route for notifications (dedicated path to avoid route conflicts)
+  // Clients discover this via Updates-Via header
+  // In @fastify/websocket v8, handler receives (connection, request) where connection.socket is the raw WebSocket
+  fastify.get('/.notifications', { websocket: true }, (connection, request) => {
+    handleWebSocket(connection.socket, request);
+  });
+
+  // Optional: Status endpoint for monitoring
+  fastify.get('/.well-known/solid/notifications', async (request, reply) => {
+    return {
+      connections: getConnectionCount(),
+      subscriptions: getSubscriptionCount(),
+      protocol: 'solid-0.1'
+    };
+  });
+}
+
+export default notificationsPlugin;

package/src/notifications/websocket.js

@@ -0,0 +1,183 @@
+/**
+ * WebSocket Handler for Solid Notifications
+ *
+ * Implements the legacy "solid-0.1" protocol used by SolidOS/mashlib.
+ *
+ * Protocol:
+ * - Server sends: "protocol solid-0.1" on connect
+ * - Client sends: "sub <uri>" to subscribe
+ * - Server sends: "ack <uri>" to acknowledge
+ * - Server sends: "pub <uri>" when resource changes
+ */
+
+import { resourceEvents } from './events.js';
+
+// Track subscriptions: WebSocket -> Set<url>
+const subscriptions = new Map();
+
+// Reverse lookup: url -> Set<WebSocket>
+const subscribers = new Map();
+
+/**
+ * Handle new WebSocket connection
+ * @param {WebSocket} socket - The WebSocket connection
+ * @param {Request} request - The HTTP request
+ */
+export function handleWebSocket(socket, request) {
+  // Send protocol greeting
+  socket.send('protocol solid-0.1');
+
+  // Initialize subscription set for this socket
+  subscriptions.set(socket, new Set());
+
+  // Handle incoming messages
+  socket.on('message', (message) => {
+    const msg = message.toString().trim();
+
+    // Handle subscription request
+    if (msg.startsWith('sub ')) {
+      const url = msg.slice(4).trim();
+      if (url) {
+        subscribe(socket, url);
+        socket.send(`ack ${url}`);
+      }
+    }
+
+    // Handle unsubscribe (optional extension)
+    if (msg.startsWith('unsub ')) {
+      const url = msg.slice(6).trim();
+      if (url) {
+        unsubscribe(socket, url);
+      }
+    }
+  });
+
+  // Clean up on close
+  socket.on('close', () => {
+    cleanup(socket);
+  });
+
+  // Clean up on error
+  socket.on('error', () => {
+    cleanup(socket);
+  });
+}
+
+/**
+ * Subscribe a socket to a resource URL
+ */
+function subscribe(socket, url) {
+  // Add to socket's subscriptions
+  const socketSubs = subscriptions.get(socket);
+  if (socketSubs) {
+    socketSubs.add(url);
+  }
+
+  // Add to URL's subscribers
+  if (!subscribers.has(url)) {
+    subscribers.set(url, new Set());
+  }
+  subscribers.get(url).add(socket);
+}
+
+/**
+ * Unsubscribe a socket from a resource URL
+ */
+function unsubscribe(socket, url) {
+  // Remove from socket's subscriptions
+  const socketSubs = subscriptions.get(socket);
+  if (socketSubs) {
+    socketSubs.delete(url);
+  }
+
+  // Remove from URL's subscribers
+  const urlSubs = subscribers.get(url);
+  if (urlSubs) {
+    urlSubs.delete(socket);
+    if (urlSubs.size === 0) {
+      subscribers.delete(url);
+    }
+  }
+}
+
+/**
+ * Clean up all subscriptions for a socket
+ */
+function cleanup(socket) {
+  const urls = subscriptions.get(socket);
+  if (urls) {
+    for (const url of urls) {
+      unsubscribe(socket, url);
+    }
+  }
+  subscriptions.delete(socket);
+}
+
+/**
+ * Broadcast a change notification to all subscribers of a URL
+ * Also notifies subscribers of parent containers
+ */
+export function broadcast(url) {
+  // Notify direct subscribers
+  notifySubscribers(url);
+
+  // Also notify container subscribers (parent directory)
+  // This allows subscribing to a container and getting notified of all child changes
+  const containerUrl = getParentContainer(url);
+  if (containerUrl && containerUrl !== url) {
+    notifySubscribers(containerUrl);
+  }
+}
+
+/**
+ * Send pub message to all subscribers of a URL
+ */
+function notifySubscribers(url) {
+  const subs = subscribers.get(url);
+  if (subs) {
+    const message = `pub ${url}`;
+    for (const socket of subs) {
+      if (socket.readyState === 1) { // WebSocket.OPEN
+        try {
+          socket.send(message);
+        } catch (e) {
+          // Socket may have closed, will be cleaned up on close event
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Get parent container URL from a resource URL
+ */
+function getParentContainer(url) {
+  // Remove trailing slash if present
+  const normalized = url.endsWith('/') ? url.slice(0, -1) : url;
+  const lastSlash = normalized.lastIndexOf('/');
+  if (lastSlash > 0) {
+    return normalized.substring(0, lastSlash + 1);
+  }
+  return null;
+}
+
+/**
+ * Get count of active subscriptions (for monitoring)
+ */
+export function getSubscriptionCount() {
+  let count = 0;
+  for (const urls of subscriptions.values()) {
+    count += urls.size;
+  }
+  return count;
+}
+
+/**
+ * Get count of active connections (for monitoring)
+ */
+export function getConnectionCount() {
+  return subscriptions.size;
+}
+
+// Listen to resource change events and broadcast
+resourceEvents.on('change', broadcast);