@lde/distribution-probe 0.1.4 → 0.1.6

package/dist/probe.d.ts

@@ -46,8 +46,14 @@ declare abstract class ProbeResult {
  * Result of probing a SPARQL endpoint.
  */
 export declare class SparqlProbeResult extends ProbeResult {
-    readonly acceptedContentType: string;
-    constructor(url: string, response: Response, responseTimeMs: number, acceptedContentType: string, failureReason?: string | null);
+    /**
+     * Content types the probe was prepared to accept as a valid answer. A SELECT or
+     * ASK query may be answered with SPARQL results in JSON or XML; the endpoint
+     * chooses, so success is not tied to a single serialization. A single string is
+     * accepted and normalized to a one-element list for backwards compatibility.
+     */
+    readonly acceptedContentTypes: readonly string[];
+    constructor(url: string, response: Response, responseTimeMs: number, acceptedContentTypes: string | readonly string[], failureReason?: string | null);
     isSuccess(): boolean;
 }
 /**

package/dist/probe.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,YAAY,EAAE,MAAM,cAAc,CAAC;AAGnE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;GAEG;AACH,qBAAa,YAAY;aAEL,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;aACf,cAAc,EAAE,MAAM;gBAFtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM;CAEzC;AAED;;GAEG;AACH,uBAAe,WAAW;aAUN,GAAG,EAAE,MAAM;IAT7B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAQ;IACjD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,SAAgB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,SAAgB,QAAQ,EAAE,MAAM,EAAE,CAAM;IACxC,SAAgB,cAAc,EAAE,MAAM,CAAC;gBAGrB,GAAG,EAAE,MAAM,EAC3B,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;IAa9B,SAAS,IAAI,OAAO;CAO5B;AAKD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD,SAAgB,mBAAmB,EAAE,MAAM,CAAC;gBAG1C,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,mBAAmB,EAAE,MAAM,EAC3B,aAAa,GAAE,MAAM,GAAG,IAAW;IAM5B,SAAS,IAAI,OAAO;CAM9B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAGhD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;CAQtC;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,YAAY,CAAC;AAIjB;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,eAAe,CAAC,CAkC1B"}
+{"version":3,"file":"probe.d.ts","sourceRoot":"","sources":["../src/probe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,YAAY,EAAE,MAAM,cAAc,CAAC;AAInE;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAKD;;GAEG;AACH,qBAAa,YAAY;aAEL,GAAG,EAAE,MAAM;aACX,OAAO,EAAE,MAAM;aACf,cAAc,EAAE,MAAM;gBAFtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM;CAEzC;AAED;;GAEG;AACH,uBAAe,WAAW;aAUN,GAAG,EAAE,MAAM;IAT7B,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,UAAU,EAAE,MAAM,CAAC;IACnC,SAAgB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAQ;IACjD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3C,SAAgB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7C,SAAgB,QAAQ,EAAE,MAAM,EAAE,CAAM;IACxC,SAAgB,cAAc,EAAE,MAAM,CAAC;gBAGrB,GAAG,EAAE,MAAM,EAC3B,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;IAa9B,SAAS,IAAI,OAAO;CAO5B;AAMD;;GAEG;AACH,qBAAa,iBAAkB,SAAQ,WAAW;IAChD;;;;;OAKG;IACH,SAAgB,oBAAoB,EAAE,SAAS,MAAM,EAAE,CAAC;gBAGtD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,oBAAoB,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,EAChD,aAAa,GAAE,MAAM,GAAG,IAAW;IAS5B,SAAS,IAAI,OAAO;CAQ9B;AAED;;GAEG;AACH,qBAAa,mBAAoB,SAAQ,WAAW;IAClD,SAAgB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAQ;gBAGhD,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,QAAQ,EAClB,cAAc,EAAE,MAAM,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;CAQtC;AAED,MAAM,MAAM,eAAe,GACvB,iBAAiB,GACjB,mBAAmB,GACnB,YAAY,CAAC;AAIjB;;;;;;;;GAQG;AACH,wBAAsB,KAAK,CACzB,YAAY,EAAE,YAAY,EAC1B,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,eAAe,CAAC,CAkC1B"}

package/dist/probe.js

@@ -1,5 +1,6 @@
 import { compressionMediaTypes } from '@lde/dataset';
-import { Parser } from 'n3';
+import { rdfParser } from 'rdf-parse';
+import { Readable } from 'node:stream';
 const DEFAULT_SPARQL_QUERY = 'SELECT * { ?s ?p ?o } LIMIT 1';
 const DEFAULT_TIMEOUT_MS = 5000;
 /**
@@ -46,19 +47,29 @@ class ProbeResult {
     }
 }
 const SPARQL_RESULTS_JSON = 'application/sparql-results+json';
+const SPARQL_RESULTS_XML = 'application/sparql-results+xml';
 const SPARQL_RDF_RESULTS = 'application/n-triples';
 /**
  * Result of probing a SPARQL endpoint.
  */
 export class SparqlProbeResult extends ProbeResult {
-    acceptedContentType;
-    constructor(url, response, responseTimeMs, acceptedContentType, failureReason = null) {
+    /**
+     * Content types the probe was prepared to accept as a valid answer. A SELECT or
+     * ASK query may be answered with SPARQL results in JSON or XML; the endpoint
+     * chooses, so success is not tied to a single serialization. A single string is
+     * accepted and normalized to a one-element list for backwards compatibility.
+     */
+    acceptedContentTypes;
+    constructor(url, response, responseTimeMs, acceptedContentTypes, failureReason = null) {
         super(url, response, responseTimeMs, failureReason);
-        this.acceptedContentType = acceptedContentType;
+        this.acceptedContentTypes =
+            typeof acceptedContentTypes === 'string'
+                ? [acceptedContentTypes]
+                : acceptedContentTypes;
     }
     isSuccess() {
         return (super.isSuccess() &&
-            (this.contentType?.startsWith(this.acceptedContentType) ?? false));
+            this.acceptedContentTypes.some((type) => this.contentType?.startsWith(type) ?? false));
     }
 }
 /**
@@ -137,18 +148,33 @@ function detectSparqlQueryType(query) {
     const match = /\b(ASK|SELECT|CONSTRUCT|DESCRIBE)\b/i.exec(withoutComments);
     return (match?.[1].toUpperCase() ?? 'SELECT');
 }
-function acceptHeaderForQueryType(queryType) {
+/**
+ * Content types a SPARQL endpoint may legitimately answer with, in preference
+ * order, for the given query type. SELECT and ASK return a results document
+ * (JSON or XML – the endpoint chooses); CONSTRUCT and DESCRIBE return RDF.
+ */
+function acceptableContentTypes(queryType) {
     if (queryType === 'ASK' || queryType === 'SELECT') {
-        return SPARQL_RESULTS_JSON;
+        return [SPARQL_RESULTS_JSON, SPARQL_RESULTS_XML];
     }
-    return SPARQL_RDF_RESULTS;
+    return [SPARQL_RDF_RESULTS];
+}
+/**
+ * Build an `Accept` header that prefers the first content type but still accepts
+ * the rest at a lower q-value, so an endpoint that only serves a later type is
+ * not rejected with a 406.
+ */
+function acceptHeader(contentTypes) {
+    return contentTypes
+        .map((type, index) => (index === 0 ? type : `${type};q=0.9`))
+        .join(', ');
 }
 async function probeSparqlEndpoint(url, _distribution, options, authHeaders, start) {
     const queryType = detectSparqlQueryType(options.sparqlQuery);
-    const accept = acceptHeaderForQueryType(queryType);
+    const acceptedContentTypes = acceptableContentTypes(queryType);
     const headers = new Headers({
         'Content-Type': 'application/x-www-form-urlencoded;charset=UTF-8',
-        Accept: accept,
+        Accept: acceptHeader(acceptedContentTypes),
     });
     for (const [key, value] of authHeaders) {
         headers.set(key, value);
@@ -160,19 +186,19 @@ async function probeSparqlEndpoint(url, _distribution, options, authHeaders, sta
         body: `query=${encodeURIComponent(options.sparqlQuery)}`,
     });
     const actualContentType = response.headers.get('Content-Type');
-    const contentTypeMatches = actualContentType?.startsWith(accept) ?? false;
+    const matchedContentType = acceptedContentTypes.find((type) => actualContentType?.startsWith(type) ?? false);
     let failureReason = null;
-    if (response.ok && contentTypeMatches) {
-        failureReason = await validateSparqlResponse(response, queryType);
+    if (response.ok && matchedContentType !== undefined) {
+        failureReason = await validateSparqlResponse(response, queryType, matchedContentType);
     }
     else {
         // Drain unconsumed body to release the underlying connection.
         await response.body?.cancel();
     }
     const responseTimeMs = Math.round(performance.now() - start);
-    return new SparqlProbeResult(url, response, responseTimeMs, accept, failureReason);
+    return new SparqlProbeResult(url, response, responseTimeMs, acceptedContentTypes, failureReason);
 }
-async function validateSparqlResponse(response, queryType) {
+async function validateSparqlResponse(response, queryType, contentType) {
     const body = await response.text();
     if (body.length === 0) {
         return 'SPARQL endpoint returned an empty response';
@@ -182,6 +208,11 @@ async function validateSparqlResponse(response, queryType) {
         // endpoint answered. Deep parse validation is the data-dump path’s job.
         return null;
     }
+    return contentType.startsWith(SPARQL_RESULTS_XML)
+        ? validateSparqlXmlResults(body, queryType)
+        : validateSparqlJsonResults(body, queryType);
+}
+function validateSparqlJsonResults(body, queryType) {
     let json;
     try {
         json = JSON.parse(body);
@@ -201,6 +232,27 @@ async function validateSparqlResponse(response, queryType) {
     }
     return null;
 }
+/**
+ * Lightweight structural check on a SPARQL Query Results XML document. Mirrors
+ * the JSON path’s intent – confirm the endpoint answered with the expected shape
+ * – without pulling in a full XML parser.
+ */
+function validateSparqlXmlResults(body, queryType) {
+    if (!/<sparql[\s>]/i.test(body)) {
+        return 'SPARQL endpoint returned invalid XML';
+    }
+    if (queryType === 'ASK') {
+        if (!/<boolean>\s*(true|false)\s*<\/boolean>/i.test(body)) {
+            return 'SPARQL endpoint did not return a valid ASK result';
+        }
+        return null;
+    }
+    // SELECT
+    if (!/<results[\s/>]/i.test(body)) {
+        return 'SPARQL endpoint did not return a valid results object';
+    }
+    return null;
+}
 async function probeDataDump(url, distribution, options, authHeaders, start) {
     // Express a preference for the declared media type, but accept anything as a
     // fallback. Servers that implement RFC 9110 §12.5.1 content negotiation will
@@ -237,7 +289,7 @@ async function probeDataDump(url, distribution, options, authHeaders, start) {
         const body = await getResponse.text();
         const isHttpSuccess = getResponse.status >= 200 && getResponse.status < 400;
         const failureReason = isHttpSuccess
-            ? validateBody(body, getResponse.headers.get('Content-Type'))
+            ? await validateBody(body, getResponse.headers.get('Content-Type'), url, options.timeoutMs)
             : null;
         const responseTimeMs = Math.round(performance.now() - start);
         const result = new DataDumpProbeResult(url, getResponse, responseTimeMs, failureReason);
@@ -249,28 +301,83 @@ async function probeDataDump(url, distribution, options, authHeaders, start) {
     checkContentTypeMismatch(result, distribution.mimeType);
     return result;
 }
+// The RDF serializations whose bodies we parse to confirm they carry triples. A
+// non-empty body in one of these formats that yields zero triples — an empty
+// graph such as a JSON-LD `{}`, an `<rdf:RDF/>`, or prefix-only Turtle — is a
+// faulty distribution, not a usable one, so it must be caught here. Other
+// content types (CSV, HTML, …) are left untouched: the probe is not the place
+// to assert what a non-RDF body should contain.
 const rdfContentTypes = [
     'text/turtle',
     'application/n-triples',
     'application/n-quads',
+    'application/trig',
+    'text/n3',
+    'application/ld+json',
+    'application/rdf+xml',
 ];
-function validateBody(body, contentType) {
+async function validateBody(body, contentType, baseIRI, timeoutMs) {
     if (body.length === 0) {
         return 'Distribution is empty';
     }
-    if (contentType && rdfContentTypes.some((t) => contentType.startsWith(t))) {
-        try {
-            const parser = new Parser();
-            const quads = parser.parse(body);
-            if (quads.length === 0) {
-                return 'Distribution contains no RDF triples';
-            }
-        }
-        catch (e) {
-            return e instanceof Error ? e.message : String(e);
-        }
+    const serialization = contentType?.split(';')[0].trim();
+    if (!serialization || !rdfContentTypes.includes(serialization)) {
+        return null;
     }
-    return null;
+    const outcome = await classifyRdfBody(body, serialization, baseIRI, timeoutMs);
+    switch (outcome.type) {
+        case 'empty':
+            return 'Distribution contains no RDF triples';
+        case 'parseError':
+            return outcome.message;
+        // 'hasTriples' proves content. 'inconclusive' means the parse timed out or a
+        // remote JSON-LD @context could not be loaded — a third-party hiccup, not
+        // evidence the distribution is faulty — so neither is reported as a failure.
+        default:
+            return null;
+    }
+}
+/**
+ * Parse an RDF body just far enough to tell whether it carries any triples:
+ * resolve on the first triple (presence is all we need, not a full count), on a
+ * clean end with none ('empty'), or on a parse error. The parse is bounded by
+ * `timeoutMs` because a JSON-LD `@context` is fetched from its origin, and a
+ * slow or hanging context host would otherwise stall the probe past its budget;
+ * on expiry — and likewise when a remote `@context` is unreachable — the outcome
+ * is 'inconclusive', so a valid distribution is never flagged faulty for a
+ * context host's failure. `baseIRI` resolves any relative IRIs in the document.
+ */
+function classifyRdfBody(body, contentType, baseIRI, timeoutMs) {
+    return new Promise((resolve) => {
+        const quads = rdfParser.parse(Readable.from([body]), {
+            contentType,
+            baseIRI,
+        });
+        const timer = setTimeout(() => settle({ type: 'inconclusive' }), timeoutMs);
+        let settled = false;
+        function settle(outcome) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            quads.destroy();
+            resolve(outcome);
+        }
+        quads
+            .on('data', () => settle({ type: 'hasTriples' }))
+            .on('error', (error) => settle(isRemoteContextError(error)
+            ? { type: 'inconclusive' }
+            : { type: 'parseError', message: error.message }))
+            .on('end', () => settle({ type: 'empty' }));
+    });
+}
+/**
+ * Whether a parse error is the RDF parser failing to load a remote JSON-LD
+ * `@context` (an unreachable or broken third-party context host) rather than a
+ * defect in the distribution body itself.
+ */
+function isRemoteContextError(error) {
+    return /remote context/i.test(error.message);
 }
 /**
  * Compare the declared MIME type from the dataset registry against the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lde/distribution-probe",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "repository": {
     "url": "git+https://github.com/ldelements/lde.git",
     "directory": "packages/distribution-probe"
@@ -25,7 +25,7 @@
   ],
   "dependencies": {
     "@lde/dataset": "0.7.4",
-    "n3": "^2.0.1",
+    "rdf-parse": "^5.0.0",
     "tslib": "^2.3.0"
   }
 }