javascript-solid-server 0.0.7 → 0.0.8

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;
+}

package/src/rdf/turtle.js

@@ -0,0 +1,411 @@
+/**
+ * Turtle <-> JSON-LD Conversion
+ *
+ * Provides bidirectional conversion between Turtle and JSON-LD formats.
+ * Uses the N3.js library for parsing and serializing Turtle.
+ */
+
+import { Parser, Writer, DataFactory } from 'n3';
+const { namedNode, literal, blankNode, quad } = DataFactory;
+
+// Common prefixes for compact output
+const COMMON_PREFIXES = {
+  rdf: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+  rdfs: 'http://www.w3.org/2000/01/rdf-schema#',
+  xsd: 'http://www.w3.org/2001/XMLSchema#',
+  foaf: 'http://xmlns.com/foaf/0.1/',
+  ldp: 'http://www.w3.org/ns/ldp#',
+  solid: 'http://www.w3.org/ns/solid/terms#',
+  acl: 'http://www.w3.org/ns/auth/acl#',
+  pim: 'http://www.w3.org/ns/pim/space#',
+  dc: 'http://purl.org/dc/terms/',
+  schema: 'http://schema.org/',
+  vcard: 'http://www.w3.org/2006/vcard/ns#'
+};
+
+/**
+ * Parse Turtle to JSON-LD
+ * @param {string} turtle - Turtle content
+ * @param {string} baseUri - Base URI for relative references
+ * @returns {Promise<object>} JSON-LD document
+ */
+export async function turtleToJsonLd(turtle, baseUri) {
+  return new Promise((resolve, reject) => {
+    const parser = new Parser({ baseIRI: baseUri });
+    const quads = [];
+
+    parser.parse(turtle, (error, quad, prefixes) => {
+      if (error) {
+        reject(error);
+        return;
+      }
+
+      if (quad) {
+        quads.push(quad);
+      } else {
+        // Parsing complete
+        try {
+          const jsonLd = quadsToJsonLd(quads, baseUri, prefixes);
+          resolve(jsonLd);
+        } catch (e) {
+          reject(e);
+        }
+      }
+    });
+  });
+}
+
+/**
+ * Convert JSON-LD to Turtle
+ * @param {object} jsonLd - JSON-LD document
+ * @param {string} baseUri - Base URI for the document
+ * @returns {Promise<string>} Turtle content
+ */
+export async function jsonLdToTurtle(jsonLd, baseUri) {
+  return new Promise((resolve, reject) => {
+    try {
+      const quads = jsonLdToQuads(jsonLd, baseUri);
+
+      const writer = new Writer({
+        prefixes: COMMON_PREFIXES,
+        baseIRI: baseUri
+      });
+
+      for (const q of quads) {
+        writer.addQuad(q);
+      }
+
+      writer.end((error, result) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve(result);
+        }
+      });
+    } catch (e) {
+      reject(e);
+    }
+  });
+}
+
+/**
+ * Convert N3.js quads to JSON-LD
+ */
+function quadsToJsonLd(quads, baseUri, prefixes = {}) {
+  if (quads.length === 0) {
+    return { '@context': buildContext(prefixes) };
+  }
+
+  // Group quads by subject
+  const subjects = new Map();
+
+  for (const quad of quads) {
+    const subjectKey = quad.subject.value;
+    if (!subjects.has(subjectKey)) {
+      subjects.set(subjectKey, {
+        '@id': makeRelative(quad.subject.value, baseUri),
+        _quads: []
+      });
+    }
+    subjects.get(subjectKey)._quads.push(quad);
+  }
+
+  // Build nodes
+  const nodes = [];
+  for (const [subjectUri, node] of subjects) {
+    const jsonNode = { '@id': node['@id'] };
+
+    for (const quad of node._quads) {
+      const predicate = quad.predicate.value;
+      const predicateKey = compactUri(predicate, prefixes);
+
+      // Handle rdf:type specially
+      if (predicate === 'http://www.w3.org/1999/02/22-rdf-syntax-ns#type') {
+        const typeValue = compactUri(quad.object.value, prefixes);
+        if (jsonNode['@type']) {
+          if (Array.isArray(jsonNode['@type'])) {
+            jsonNode['@type'].push(typeValue);
+          } else {
+            jsonNode['@type'] = [jsonNode['@type'], typeValue];
+          }
+        } else {
+          jsonNode['@type'] = typeValue;
+        }
+        continue;
+      }
+
+      const objectValue = termToJsonLd(quad.object, baseUri, prefixes);
+
+      if (jsonNode[predicateKey]) {
+        // Multiple values - make array
+        if (Array.isArray(jsonNode[predicateKey])) {
+          jsonNode[predicateKey].push(objectValue);
+        } else {
+          jsonNode[predicateKey] = [jsonNode[predicateKey], objectValue];
+        }
+      } else {
+        jsonNode[predicateKey] = objectValue;
+      }
+    }
+
+    nodes.push(jsonNode);
+  }
+
+  // Build result
+  const context = buildContext(prefixes);
+
+  if (nodes.length === 1) {
+    return { '@context': context, ...nodes[0] };
+  }
+
+  return { '@context': context, '@graph': nodes };
+}
+
+/**
+ * Convert JSON-LD to N3.js quads
+ */
+function jsonLdToQuads(jsonLd, baseUri) {
+  const quads = [];
+  const context = jsonLd['@context'] || {};
+
+  // Handle @graph or single object
+  const nodes = jsonLd['@graph'] || [jsonLd];
+
+  for (const node of nodes) {
+    if (!node['@id']) continue;
+
+    const subjectUri = resolveUri(node['@id'], baseUri);
+    const subject = subjectUri.startsWith('_:')
+      ? blankNode(subjectUri.slice(2))
+      : namedNode(subjectUri);
+
+    // Handle @type
+    if (node['@type']) {
+      const types = Array.isArray(node['@type']) ? node['@type'] : [node['@type']];
+      for (const type of types) {
+        const typeUri = expandUri(type, context);
+        quads.push(quad(
+          subject,
+          namedNode('http://www.w3.org/1999/02/22-rdf-syntax-ns#type'),
+          namedNode(typeUri)
+        ));
+      }
+    }
+
+    // Handle other properties
+    for (const [key, value] of Object.entries(node)) {
+      if (key.startsWith('@')) continue;
+
+      const predicateUri = expandUri(key, context);
+      const predicate = namedNode(predicateUri);
+
+      const values = Array.isArray(value) ? value : [value];
+      for (const v of values) {
+        const object = valueToTerm(v, baseUri, context);
+        if (object) {
+          quads.push(quad(subject, predicate, object));
+        }
+      }
+    }
+  }
+
+  return quads;
+}
+
+/**
+ * Convert N3.js term to JSON-LD value
+ */
+function termToJsonLd(term, baseUri, prefixes) {
+  if (term.termType === 'NamedNode') {
+    const uri = makeRelative(term.value, baseUri);
+    // Check if it looks like a URI or should be @id
+    if (uri.includes('://') || uri.startsWith('#') || uri.startsWith('/')) {
+      return { '@id': uri };
+    }
+    return { '@id': uri };
+  }
+
+  if (term.termType === 'BlankNode') {
+    return { '@id': '_:' + term.value };
+  }
+
+  if (term.termType === 'Literal') {
+    // Check for language tag
+    if (term.language) {
+      return { '@value': term.value, '@language': term.language };
+    }
+
+    // Check for datatype
+    const datatype = term.datatype?.value;
+    if (datatype) {
+      // Handle common XSD types
+      if (datatype === 'http://www.w3.org/2001/XMLSchema#integer') {
+        return parseInt(term.value, 10);
+      }
+      if (datatype === 'http://www.w3.org/2001/XMLSchema#decimal' ||
+          datatype === 'http://www.w3.org/2001/XMLSchema#double' ||
+          datatype === 'http://www.w3.org/2001/XMLSchema#float') {
+        return parseFloat(term.value);
+      }
+      if (datatype === 'http://www.w3.org/2001/XMLSchema#boolean') {
+        return term.value === 'true';
+      }
+      if (datatype === 'http://www.w3.org/2001/XMLSchema#string') {
+        return term.value;
+      }
+      // Other typed literals
+      return { '@value': term.value, '@type': compactUri(datatype, prefixes) };
+    }
+
+    return term.value;
+  }
+
+  return term.value;
+}
+
+/**
+ * Convert JSON-LD value to N3.js term
+ */
+function valueToTerm(value, baseUri, context) {
+  if (value === null || value === undefined) {
+    return null;
+  }
+
+  // Plain values
+  if (typeof value === 'string') {
+    return literal(value);
+  }
+  if (typeof value === 'number') {
+    if (Number.isInteger(value)) {
+      return literal(value.toString(), namedNode('http://www.w3.org/2001/XMLSchema#integer'));
+    }
+    return literal(value.toString(), namedNode('http://www.w3.org/2001/XMLSchema#decimal'));
+  }
+  if (typeof value === 'boolean') {
+    return literal(value.toString(), namedNode('http://www.w3.org/2001/XMLSchema#boolean'));
+  }
+
+  // Object values
+  if (typeof value === 'object') {
+    // @id reference
+    if (value['@id']) {
+      const uri = resolveUri(value['@id'], baseUri);
+      return uri.startsWith('_:')
+        ? blankNode(uri.slice(2))
+        : namedNode(uri);
+    }
+
+    // @value with @language
+    if (value['@value'] && value['@language']) {
+      return literal(value['@value'], value['@language']);
+    }
+
+    // @value with @type
+    if (value['@value'] && value['@type']) {
+      const typeUri = expandUri(value['@type'], context);
+      return literal(value['@value'], namedNode(typeUri));
+    }
+
+    // Plain @value
+    if (value['@value']) {
+      return literal(value['@value']);
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Make URI relative to base
+ */
+function makeRelative(uri, baseUri) {
+  if (uri.startsWith(baseUri)) {
+    const relative = uri.slice(baseUri.length);
+    if (relative.startsWith('#') || relative === '') {
+      return relative || '.';
+    }
+    return relative;
+  }
+  return uri;
+}
+
+/**
+ * Resolve relative URI against base
+ */
+function resolveUri(uri, baseUri) {
+  if (uri.startsWith('http://') || uri.startsWith('https://') || uri.startsWith('_:')) {
+    return uri;
+  }
+  if (uri.startsWith('#')) {
+    return baseUri + uri;
+  }
+  try {
+    return new URL(uri, baseUri).href;
+  } catch {
+    return uri;
+  }
+}
+
+/**
+ * Expand prefixed URI using context
+ */
+function expandUri(uri, context) {
+  if (uri.includes('://')) {
+    return uri;
+  }
+
+  if (uri.includes(':')) {
+    const [prefix, local] = uri.split(':', 2);
+    const ns = context[prefix] || COMMON_PREFIXES[prefix];
+    if (ns) {
+      return ns + local;
+    }
+  }
+
+  // Check if it's a term in context
+  if (context[uri]) {
+    const expansion = context[uri];
+    if (typeof expansion === 'string') {
+      return expansion;
+    }
+    if (expansion['@id']) {
+      return expansion['@id'];
+    }
+  }
+
+  return uri;
+}
+
+/**
+ * Compact URI using prefixes
+ */
+function compactUri(uri, prefixes) {
+  // Check custom prefixes first
+  for (const [prefix, ns] of Object.entries(prefixes)) {
+    if (uri.startsWith(ns)) {
+      return prefix + ':' + uri.slice(ns.length);
+    }
+  }
+
+  // Check common prefixes
+  for (const [prefix, ns] of Object.entries(COMMON_PREFIXES)) {
+    if (uri.startsWith(ns)) {
+      return prefix + ':' + uri.slice(ns.length);
+    }
+  }
+
+  return uri;
+}
+
+/**
+ * Build JSON-LD @context from prefixes
+ */
+function buildContext(prefixes) {
+  const context = { ...COMMON_PREFIXES };
+  for (const [prefix, ns] of Object.entries(prefixes)) {
+    if (prefix && ns) {
+      context[prefix] = ns;
+    }
+  }
+  return context;
+}

package/src/server.js

@@ -6,8 +6,14 @@ import { authorize, handleUnauthorized } from './auth/middleware.js';
 
 /**
  * Create and configure Fastify server
+ * @param {object} options - Server options
+ * @param {boolean} options.logger - Enable logging (default true)
+ * @param {boolean} options.conneg - Enable content negotiation for RDF (default false)
  */
 export function createServer(options = {}) {
+  // Content negotiation is OFF by default - we're a JSON-LD native server
+  const connegEnabled = options.conneg ?? false;
+
   const fastify = Fastify({
     logger: options.logger ?? true,
     trustProxy: true,
@@ -20,6 +26,12 @@ export function createServer(options = {}) {
     done(null, body);
   });
 
+  // Attach server config to requests
+  fastify.decorateRequest('connegEnabled', null);
+  fastify.addHook('onRequest', async (request) => {
+    request.connegEnabled = connegEnabled;
+  });
+
   // Global CORS preflight
   fastify.addHook('onRequest', async (request, reply) => {
     // Add CORS headers to all responses