@blamejs/core 0.14.18 → 0.14.20

package/lib/observability.js

@@ -309,7 +309,12 @@ function timed(name, fn, labels) {
 // pass attribute keys that should match the keys below. The map is
 // frozen — adding a new attribute requires a release.
 //
-// Reference: https://opentelemetry.io/docs/specs/semconv/general/attributes/
+// References:
+//   https://opentelemetry.io/docs/specs/semconv/general/attributes/
+//   https://opentelemetry.io/docs/specs/semconv/resource/  (resource,
+//     telemetry-sdk, deployment-environment)
+//   https://opentelemetry.io/docs/specs/semconv/resource/k8s/
+//   https://opentelemetry.io/docs/specs/semconv/resource/faas/
 var SEMCONV = Object.freeze({
   // HTTP server (stable per OTel semconv)
   HTTP_REQUEST_METHOD:        "http.request.method",
@@ -370,10 +375,33 @@ var SEMCONV = Object.freeze({
   SERVICE_NAME:               "service.name",
   SERVICE_VERSION:             "service.version",
   SERVICE_INSTANCE_ID:        "service.instance.id",
+  // peer.service — logical name of the remote service a span talks to,
+  // distinct from server.address (the host). OTel semconv (general).
+  PEER_SERVICE:               "peer.service",
+  // Deployment environment (aka deployment tier: "production",
+  // "staging"). The bare `deployment.environment` key was deprecated in
+  // favour of `deployment.environment.name`; this carries the current
+  // stable key. OTel semconv resource/deployment-environment.
+  DEPLOYMENT_ENVIRONMENT_NAME: "deployment.environment.name",
   // Telemetry SDK self-identification
   TELEMETRY_SDK_NAME:         "telemetry.sdk.name",
   TELEMETRY_SDK_LANGUAGE:     "telemetry.sdk.language",
   TELEMETRY_SDK_VERSION:      "telemetry.sdk.version",
+  // Telemetry distribution self-identification — the redistribution of
+  // an OTel SDK an operator runs (e.g. a vendor distro). OTel semconv
+  // resource/telemetry-sdk.
+  TELEMETRY_DISTRO_NAME:      "telemetry.distro.name",
+  TELEMETRY_DISTRO_VERSION:   "telemetry.distro.version",
+  // Instrumentation scope self-identification — the scope (library)
+  // that produced a span/metric. OTel semconv otel namespace.
+  OTEL_SCOPE_NAME:            "otel.scope.name",
+  OTEL_SCOPE_VERSION:         "otel.scope.version",
+  // FaaS (serverless) — function-as-a-service execution context. OTel
+  // semconv resource/faas + attributes-registry/faas.
+  FAAS_NAME:                  "faas.name",
+  FAAS_VERSION:               "faas.version",
+  FAAS_INSTANCE:              "faas.instance",
+  FAAS_TRIGGER:               "faas.trigger",
   // GenAI — OpenTelemetry semantic conventions for generative AI
   // workloads (LLM clients, vector DB queries, agent frameworks).
   // Tracking the otel-spec experimental namespace; covers the stable
@@ -410,9 +438,19 @@ var SEMCONV = Object.freeze({
   CONTAINER_ID:                   "container.id",
   CONTAINER_IMAGE_NAME:           "container.image.name",
   CONTAINER_IMAGE_TAG:            "container.image.tag",
+  // Kubernetes — OTel semconv resource/k8s. Namespace / pod /
+  // deployment plus the surrounding workload + node + cluster context.
   K8S_NAMESPACE_NAME:             "k8s.namespace.name",
   K8S_POD_NAME:                   "k8s.pod.name",
   K8S_DEPLOYMENT_NAME:            "k8s.deployment.name",
+  K8S_NODE_NAME:                  "k8s.node.name",
+  K8S_CLUSTER_NAME:               "k8s.cluster.name",
+  K8S_CONTAINER_NAME:             "k8s.container.name",
+  K8S_STATEFULSET_NAME:           "k8s.statefulset.name",
+  K8S_DAEMONSET_NAME:             "k8s.daemonset.name",
+  K8S_JOB_NAME:                   "k8s.job.name",
+  K8S_CRONJOB_NAME:               "k8s.cronjob.name",
+  K8S_REPLICASET_NAME:            "k8s.replicaset.name",
 });
 
 // W3C Trace Context — parse / build the `traceparent` HTTP header

package/lib/openapi-paths-builder.js

@@ -1,6 +1,6 @@
 "use strict";
 /**
- * OpenAPI 3.1 — paths / operations builder.
+ * OpenAPI 3.1 / 3.2 — paths / operations + webhooks builder.
  *
  * Internal to lib/openapi.js. Holds the per-path operation table
  * (method to operationObject) and produces the final `paths` map used
@@ -13,6 +13,14 @@
  *
  * Operation methods accepted: get / put / post / delete / options /
  * head / patch / trace (RFC 9110 + OpenAPI 3.1 §4.8.5).
+ *
+ * `WebhooksBuilder` shares the same Operation Object normalisation but
+ * keys by a free-form webhook NAME (not a URL pattern): the top-level
+ * `webhooks` field is a map of named Path Item Objects describing
+ * out-of-band requests the API initiates (OpenAPI 3.2 §4.8.2, "Fixed
+ * Fields" — `webhooks`; carried forward unchanged from 3.1.0 §4.1).
+ * Webhook keys are not URL templates, so the `/`-prefix and
+ * path-template-placeholder checks are intentionally not applied.
  */
 
 var validateOpts = require("./validate-opts");
@@ -39,25 +47,23 @@ function PathsBuilder() {
   this._paths = {};
 }
 
-PathsBuilder.prototype.add = function (method, urlPattern, opts) {
-  opts = opts || {};
+// _buildOperation — normalise a single Operation Object from operator
+// opts. Shared by PathsBuilder.add and WebhooksBuilder.add. `label` is
+// the caller-facing prefix used in error messages. `declaredPathParams`
+// (out-param object) records every in=path parameter so the caller can
+// verify path-template placeholders against it; webhooks have no URL
+// template so the caller simply ignores it.
+function _buildOperation(method, opts, label, declaredPathParams) {
   if (typeof method !== "string" || VALID_METHODS.indexOf(method.toLowerCase()) === -1) {
     throw new OpenApiError("openapi/bad-method",
-      "paths.add: method must be one of " + VALID_METHODS.join(", ") +
+      label + ": method must be one of " + VALID_METHODS.join(", ") +
       " - got " + JSON.stringify(method));
   }
-  validateOpts.requireNonEmptyString(urlPattern, "paths.add: urlPattern",
-    OpenApiError, "openapi/bad-path");
-  if (urlPattern.charAt(0) !== "/") {
-    throw new OpenApiError("openapi/bad-path",
-      "paths.add: urlPattern must start with '/' - got " +
-      JSON.stringify(urlPattern));
-  }
   validateOpts(opts, [
     "summary", "description", "operationId", "tags",
     "parameters", "requestBody", "responses",
     "security", "deprecated", "servers", "externalDocs",
-  ], "paths.add");
+  ], label);
 
   var op = {};
   if (typeof opts.summary === "string")     op.summary = opts.summary;
@@ -67,50 +73,65 @@ PathsBuilder.prototype.add = function (method, urlPattern, opts) {
     op.tags = opts.tags.map(function (t) {
       if (typeof t !== "string" || t.length === 0) {
         throw new OpenApiError("openapi/bad-tag",
-          "paths.add: tags must be non-empty strings");
+          label + ": tags must be non-empty strings");
       }
       return t;
     });
   }
 
   // Parameters
-  var declaredPathParams = Object.create(null);
   if (Array.isArray(opts.parameters)) {
     op.parameters = [];
     for (var i = 0; i < opts.parameters.length; i += 1) {
-      var p = _normaliseParameter(opts.parameters[i], "paths.add: parameters[" + i + "]");
+      var p = _normaliseParameter(opts.parameters[i], label + ": parameters[" + i + "]");
       op.parameters.push(p);
       if (p.in === "path") declaredPathParams[p.name] = true;
     }
   }
-  // Verify every {placeholder} in path is declared.
-  var placeholders = _extractPathParams(urlPattern);
-  for (var j = 0; j < placeholders.length; j += 1) {
-    if (!declaredPathParams[placeholders[j]]) {
-      throw new OpenApiError("openapi/missing-path-param",
-        "paths.add: path template " + JSON.stringify(urlPattern) +
-        " references {" + placeholders[j] +
-        "} but no parameter with in=path name=" + JSON.stringify(placeholders[j]) +
-        " was declared");
-    }
-  }
 
   // Request body
   if (opts.requestBody) {
-    op.requestBody = _normaliseRequestBody(opts.requestBody, "paths.add: requestBody");
+    op.requestBody = _normaliseRequestBody(opts.requestBody, label + ": requestBody");
   }
 
   // Responses (required)
   if (!opts.responses || typeof opts.responses !== "object") {
     throw new OpenApiError("openapi/missing-responses",
-      "paths.add: responses object is required (per OpenAPI 3.1 §4.8.5)");
+      label + ": responses object is required (per OpenAPI 3.1 §4.8.5)");
   }
-  op.responses = _normaliseResponses(opts.responses, "paths.add: responses");
+  op.responses = _normaliseResponses(opts.responses, label + ": responses");
 
   if (Array.isArray(opts.security)) op.security = opts.security.slice();
   if (opts.deprecated === true)     op.deprecated = true;
   if (Array.isArray(opts.servers))  op.servers = opts.servers.slice();
   if (opts.externalDocs)            op.externalDocs = opts.externalDocs;
+  return op;
+}
+
+PathsBuilder.prototype.add = function (method, urlPattern, opts) {
+  opts = opts || {};
+  validateOpts.requireNonEmptyString(urlPattern, "paths.add: urlPattern",
+    OpenApiError, "openapi/bad-path");
+  if (urlPattern.charAt(0) !== "/") {
+    throw new OpenApiError("openapi/bad-path",
+      "paths.add: urlPattern must start with '/' - got " +
+      JSON.stringify(urlPattern));
+  }
+
+  var declaredPathParams = Object.create(null);
+  var op = _buildOperation(method, opts, "paths.add", declaredPathParams);
+
+  // Verify every {placeholder} in path is declared.
+  var placeholders = _extractPathParams(urlPattern);
+  for (var j = 0; j < placeholders.length; j += 1) {
+    if (!declaredPathParams[placeholders[j]]) {
+      throw new OpenApiError("openapi/missing-path-param",
+        "paths.add: path template " + JSON.stringify(urlPattern) +
+        " references {" + placeholders[j] +
+        "} but no parameter with in=path name=" + JSON.stringify(placeholders[j]) +
+        " was declared");
+    }
+  }
 
   if (!this._paths[urlPattern]) this._paths[urlPattern] = {};
   if (this._paths[urlPattern][method.toLowerCase()]) {
@@ -240,8 +261,63 @@ PathsBuilder.prototype.toMap = function () {
   return out;
 };
 
+// WebhooksBuilder — the top-level `webhooks` field is a map of named
+// Path Item Objects describing requests the API initiates out-of-band
+// (OpenAPI 3.2 §4.8.2 Fixed Fields → `webhooks`; unchanged from
+// 3.1.0 §4.1). Keys are free-form webhook names (e.g. "newPet"), NOT
+// URL templates — no `/`-prefix and no path-template-placeholder
+// validation. Each named entry holds the same Operation Objects as a
+// regular path item.
+function WebhooksBuilder() {
+  // Null-prototype map so a free-form webhook name that collides with an
+  // Object.prototype member (__proto__ / constructor / prototype) becomes
+  // an own property instead of mutating the prototype (CWE-1321).
+  this._webhooks = Object.create(null);
+}
+
+WebhooksBuilder.prototype.add = function (name, method, opts) {
+  opts = opts || {};
+  validateOpts.requireNonEmptyString(name, "webhook.add: name",
+    OpenApiError, "openapi/bad-webhook");
+  if (name === "__proto__" || name === "constructor" || name === "prototype") {
+    throw new OpenApiError("openapi/bad-webhook",
+      "webhook.add: name must not be a reserved object key (" + JSON.stringify(name) + ")");
+  }
+  var declaredPathParams = Object.create(null);
+  var op = _buildOperation(method, opts, "webhook.add", declaredPathParams);
+  if (!this._webhooks[name]) this._webhooks[name] = {};
+  if (this._webhooks[name][method.toLowerCase()]) {
+    throw new OpenApiError("openapi/duplicate-operation",
+      "webhook.add: duplicate operation " + method.toUpperCase() +
+      " on webhook " + JSON.stringify(name));
+  }
+  this._webhooks[name][method.toLowerCase()] = op;
+  return op;
+};
+
+WebhooksBuilder.prototype.count = function () {
+  return Object.keys(this._webhooks).length;
+};
+
+WebhooksBuilder.prototype.toMap = function () {
+  var sorted = Object.keys(this._webhooks).sort();
+  var out = {};
+  for (var i = 0; i < sorted.length; i += 1) {
+    var name = sorted[i];
+    var item = this._webhooks[name];
+    var ordered = {};
+    for (var j = 0; j < VALID_METHODS.length; j += 1) {
+      var method = VALID_METHODS[j];
+      if (item[method]) ordered[method] = item[method];
+    }
+    out[name] = ordered;
+  }
+  return out;
+};
+
 module.exports = {
   PathsBuilder:        PathsBuilder,
+  WebhooksBuilder:     WebhooksBuilder,
   VALID_METHODS:       VALID_METHODS,
   _extractPathParams:  _extractPathParams,
   OpenApiError:        OpenApiError,