javascript-solid-server 0.0.7 → 0.0.9

package/src/ldp/headers.js

@@ -2,6 +2,8 @@
  * LDP (Linked Data Platform) header utilities
  */
 
+import { getAcceptHeaders } from '../rdf/conneg.js';
+
 const LDP = 'http://www.w3.org/ns/ldp#';
 
 /**
@@ -47,20 +49,25 @@ export function getAclUrl(resourceUrl, isContainer) {
  * @param {object} options
  * @returns {object}
  */
-export function getResponseHeaders({ isContainer = false, etag = null, contentType = null, resourceUrl = null, wacAllow = null }) {
+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;
 
   const headers = {
     'Link': getLinkHeader(isContainer, aclUrl),
     'WAC-Allow': wacAllow || 'user="read write append control", public="read write append"',
-    'Accept-Patch': 'application/sparql-update',
-    'Allow': 'GET, HEAD, PUT, DELETE, OPTIONS' + (isContainer ? ', POST' : ''),
-    'Vary': 'Accept, Authorization, Origin'
+    'Accept-Patch': 'text/n3, application/sparql-update',
+    'Allow': 'GET, HEAD, PUT, DELETE, PATCH, OPTIONS' + (isContainer ? ', POST' : ''),
+    'Vary': connegEnabled ? 'Accept, Authorization, Origin' : 'Authorization, Origin'
   };
 
-  if (isContainer) {
-    headers['Accept-Post'] = '*/*';
+  // Add Accept-* headers (conneg-aware)
+  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) {
@@ -84,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'
   };
@@ -95,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 }) {
+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 }),
+    ...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);

package/src/rdf/conneg.js

@@ -0,0 +1,215 @@
+/**
+ * Content Negotiation for RDF Resources
+ *
+ * Handles Accept header parsing and format selection.
+ * OFF by default - this is a JSON-LD native implementation.
+ * Enable with { conneg: true } in server options.
+ */
+
+import { turtleToJsonLd, jsonLdToTurtle } from './turtle.js';
+
+// RDF content types we support
+export const RDF_TYPES = {
+  JSON_LD: 'application/ld+json',
+  TURTLE: 'text/turtle',
+  N3: 'text/n3',
+  NTRIPLES: 'application/n-triples',
+  RDF_XML: 'application/rdf+xml'  // Not supported, but recognized
+};
+
+// Content types we can serve (when conneg enabled)
+const SUPPORTED_OUTPUT = [RDF_TYPES.JSON_LD, RDF_TYPES.TURTLE];
+
+// Content types we can accept for input (when conneg enabled)
+const SUPPORTED_INPUT = [RDF_TYPES.JSON_LD, RDF_TYPES.TURTLE, RDF_TYPES.N3];
+
+/**
+ * Parse Accept header and select best content type
+ * @param {string} acceptHeader - Accept header value
+ * @param {boolean} connegEnabled - Whether content negotiation is enabled
+ * @returns {string} Selected content type
+ */
+export function selectContentType(acceptHeader, connegEnabled = false) {
+  // If conneg disabled, always return JSON-LD
+  if (!connegEnabled) {
+    return RDF_TYPES.JSON_LD;
+  }
+
+  if (!acceptHeader) {
+    return RDF_TYPES.JSON_LD;
+  }
+
+  // Parse Accept header
+  const accepts = parseAcceptHeader(acceptHeader);
+
+  // Find best match
+  for (const { type } of accepts) {
+    if (type === '*/*' || type === 'application/*') {
+      return RDF_TYPES.JSON_LD;
+    }
+    if (SUPPORTED_OUTPUT.includes(type)) {
+      return type;
+    }
+    // Handle text/* preference
+    if (type === 'text/*') {
+      return RDF_TYPES.TURTLE;
+    }
+  }
+
+  // Default to JSON-LD
+  return RDF_TYPES.JSON_LD;
+}
+
+/**
+ * Parse Accept header into sorted list
+ */
+function parseAcceptHeader(header) {
+  const types = header.split(',').map(part => {
+    const [type, ...params] = part.trim().split(';');
+    let q = 1;
+
+    for (const param of params) {
+      const [key, value] = param.trim().split('=');
+      if (key === 'q') {
+        q = parseFloat(value) || 0;
+      }
+    }
+
+    return { type: type.trim().toLowerCase(), q };
+  });
+
+  // Sort by q value descending
+  return types.sort((a, b) => b.q - a.q);
+}
+
+/**
+ * Check if content type is RDF
+ */
+export function isRdfType(contentType) {
+  if (!contentType) return false;
+  const type = contentType.split(';')[0].trim().toLowerCase();
+  return Object.values(RDF_TYPES).includes(type) ||
+         type === 'application/json'; // Treat as JSON-LD
+}
+
+/**
+ * Check if we can accept this input type for RDF resources
+ * Non-RDF content types are always accepted (passthrough)
+ */
+export function canAcceptInput(contentType, connegEnabled = false) {
+  if (!contentType) return true; // No content type = accept
+
+  const type = contentType.split(';')[0].trim().toLowerCase();
+
+  // Always accept JSON-LD and JSON
+  if (type === RDF_TYPES.JSON_LD || type === 'application/json') {
+    return true;
+  }
+
+  // Check if it's an RDF type we need to handle
+  const isRdf = Object.values(RDF_TYPES).includes(type);
+
+  // Non-RDF types are accepted as-is (passthrough)
+  if (!isRdf) {
+    return true;
+  }
+
+  // RDF types other than JSON-LD only if conneg enabled
+  if (connegEnabled) {
+    return SUPPORTED_INPUT.includes(type);
+  }
+
+  // RDF type but conneg disabled - reject (should use JSON-LD)
+  return false;
+}
+
+/**
+ * Convert content to JSON-LD (internal storage format)
+ * @param {Buffer|string} content - Input content
+ * @param {string} contentType - Content-Type header
+ * @param {string} baseUri - Base URI
+ * @param {boolean} connegEnabled - Whether conneg is enabled
+ * @returns {Promise<object>} JSON-LD document
+ */
+export async function toJsonLd(content, contentType, baseUri, connegEnabled = false) {
+  const type = (contentType || '').split(';')[0].trim().toLowerCase();
+  const text = Buffer.isBuffer(content) ? content.toString() : content;
+
+  // JSON-LD or JSON
+  if (type === RDF_TYPES.JSON_LD || type === 'application/json' || !type) {
+    return JSON.parse(text);
+  }
+
+  // Turtle/N3 - only if conneg enabled
+  if (connegEnabled && (type === RDF_TYPES.TURTLE || type === RDF_TYPES.N3)) {
+    return turtleToJsonLd(text, baseUri);
+  }
+
+  throw new Error(`Unsupported content type: ${type}`);
+}
+
+/**
+ * Convert JSON-LD to requested format
+ * @param {object} jsonLd - JSON-LD document
+ * @param {string} targetType - Target content type
+ * @param {string} baseUri - Base URI
+ * @param {boolean} connegEnabled - Whether conneg is enabled
+ * @returns {Promise<{content: string, contentType: string}>}
+ */
+export async function fromJsonLd(jsonLd, targetType, baseUri, connegEnabled = false) {
+  // If conneg disabled, always output JSON-LD
+  if (!connegEnabled) {
+    return {
+      content: JSON.stringify(jsonLd, null, 2),
+      contentType: RDF_TYPES.JSON_LD
+    };
+  }
+
+  // JSON-LD
+  if (targetType === RDF_TYPES.JSON_LD || !targetType) {
+    return {
+      content: JSON.stringify(jsonLd, null, 2),
+      contentType: RDF_TYPES.JSON_LD
+    };
+  }
+
+  // Turtle
+  if (targetType === RDF_TYPES.TURTLE) {
+    const turtle = await jsonLdToTurtle(jsonLd, baseUri);
+    return { content: turtle, contentType: RDF_TYPES.TURTLE };
+  }
+
+  // Fallback to JSON-LD
+  return {
+    content: JSON.stringify(jsonLd, null, 2),
+    contentType: RDF_TYPES.JSON_LD
+  };
+}
+
+/**
+ * Get Vary header value for content negotiation
+ */
+export function getVaryHeader(connegEnabled) {
+  return connegEnabled ? 'Accept, Origin' : 'Origin';
+}
+
+/**
+ * Get Accept-* headers for responses
+ */
+export function getAcceptHeaders(connegEnabled, isContainer = false) {
+  const headers = {};
+
+  if (isContainer) {
+    headers['Accept-Post'] = connegEnabled
+      ? `${RDF_TYPES.JSON_LD}, ${RDF_TYPES.TURTLE}, */*`
+      : `${RDF_TYPES.JSON_LD}, */*`;
+  }
+
+  headers['Accept-Put'] = connegEnabled
+    ? `${RDF_TYPES.JSON_LD}, ${RDF_TYPES.TURTLE}, */*`
+    : `${RDF_TYPES.JSON_LD}, */*`;
+
+  headers['Accept-Patch'] = 'text/n3, application/sparql-update';
+
+  return headers;
+}