risicare 0.9.0 → 0.9.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (72) hide show
  1. package/README.md +18 -0
  2. package/dist/frameworks/instructor.cjs +144 -2
  3. package/dist/frameworks/instructor.cjs.map +1 -1
  4. package/dist/frameworks/instructor.js +144 -2
  5. package/dist/frameworks/instructor.js.map +1 -1
  6. package/dist/frameworks/langchain.cjs +144 -2
  7. package/dist/frameworks/langchain.cjs.map +1 -1
  8. package/dist/frameworks/langchain.js +144 -2
  9. package/dist/frameworks/langchain.js.map +1 -1
  10. package/dist/frameworks/langgraph.cjs +144 -2
  11. package/dist/frameworks/langgraph.cjs.map +1 -1
  12. package/dist/frameworks/langgraph.js +144 -2
  13. package/dist/frameworks/langgraph.js.map +1 -1
  14. package/dist/frameworks/llamaindex.cjs +144 -2
  15. package/dist/frameworks/llamaindex.cjs.map +1 -1
  16. package/dist/frameworks/llamaindex.js +144 -2
  17. package/dist/frameworks/llamaindex.js.map +1 -1
  18. package/dist/index.cjs +199 -7
  19. package/dist/index.cjs.map +1 -1
  20. package/dist/index.d.cts +7 -1
  21. package/dist/index.d.ts +7 -1
  22. package/dist/index.js +199 -7
  23. package/dist/index.js.map +1 -1
  24. package/dist/providers/anthropic/index.cjs +144 -2
  25. package/dist/providers/anthropic/index.cjs.map +1 -1
  26. package/dist/providers/anthropic/index.js +144 -2
  27. package/dist/providers/anthropic/index.js.map +1 -1
  28. package/dist/providers/bedrock/index.cjs +144 -2
  29. package/dist/providers/bedrock/index.cjs.map +1 -1
  30. package/dist/providers/bedrock/index.js +144 -2
  31. package/dist/providers/bedrock/index.js.map +1 -1
  32. package/dist/providers/cerebras/index.cjs +144 -2
  33. package/dist/providers/cerebras/index.cjs.map +1 -1
  34. package/dist/providers/cerebras/index.js +144 -2
  35. package/dist/providers/cerebras/index.js.map +1 -1
  36. package/dist/providers/cohere/index.cjs +144 -2
  37. package/dist/providers/cohere/index.cjs.map +1 -1
  38. package/dist/providers/cohere/index.js +144 -2
  39. package/dist/providers/cohere/index.js.map +1 -1
  40. package/dist/providers/google/index.cjs +144 -2
  41. package/dist/providers/google/index.cjs.map +1 -1
  42. package/dist/providers/google/index.js +144 -2
  43. package/dist/providers/google/index.js.map +1 -1
  44. package/dist/providers/groq/index.cjs +144 -2
  45. package/dist/providers/groq/index.cjs.map +1 -1
  46. package/dist/providers/groq/index.js +144 -2
  47. package/dist/providers/groq/index.js.map +1 -1
  48. package/dist/providers/huggingface/index.cjs +144 -2
  49. package/dist/providers/huggingface/index.cjs.map +1 -1
  50. package/dist/providers/huggingface/index.js +144 -2
  51. package/dist/providers/huggingface/index.js.map +1 -1
  52. package/dist/providers/mistral/index.cjs +144 -2
  53. package/dist/providers/mistral/index.cjs.map +1 -1
  54. package/dist/providers/mistral/index.js +144 -2
  55. package/dist/providers/mistral/index.js.map +1 -1
  56. package/dist/providers/ollama/index.cjs +144 -2
  57. package/dist/providers/ollama/index.cjs.map +1 -1
  58. package/dist/providers/ollama/index.js +144 -2
  59. package/dist/providers/ollama/index.js.map +1 -1
  60. package/dist/providers/openai/index.cjs +144 -2
  61. package/dist/providers/openai/index.cjs.map +1 -1
  62. package/dist/providers/openai/index.js +144 -2
  63. package/dist/providers/openai/index.js.map +1 -1
  64. package/dist/providers/together/index.cjs +144 -2
  65. package/dist/providers/together/index.cjs.map +1 -1
  66. package/dist/providers/together/index.js +144 -2
  67. package/dist/providers/together/index.js.map +1 -1
  68. package/dist/providers/vercel-ai/index.cjs +144 -2
  69. package/dist/providers/vercel-ai/index.cjs.map +1 -1
  70. package/dist/providers/vercel-ai/index.js +144 -2
  71. package/dist/providers/vercel-ai/index.js.map +1 -1
  72. package/package.json +1 -1
package/dist/index.cjs CHANGED
@@ -172,6 +172,10 @@ function warn(msg) {
172
172
  process.stderr.write(`[risicare] WARNING: ${msg}
173
173
  `);
174
174
  }
175
+ function info(msg) {
176
+ process.stderr.write(`[risicare] INFO: ${msg}
177
+ `);
178
+ }
175
179
 
176
180
  // src/utils/text.ts
177
181
  function cutCodePoints(text, max) {
@@ -672,7 +676,8 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
672
676
  queue_full: 0,
673
677
  transport_refused: 0,
674
678
  shutdown_residue: 0,
675
- unacknowledged: 0
679
+ unacknowledged: 0,
680
+ quota_exceeded: 0
676
681
  };
677
682
  exportedSpans = 0;
678
683
  /**
@@ -841,9 +846,15 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
841
846
  if (residue > 0) {
842
847
  this._queue.length = 0;
843
848
  this._recordDropped("shutdown_residue", residue);
844
- warn(
845
- `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ${queued} still queued and ${inFlight} in an export that shutdown() stopped. ` + (inFlight > 0 ? `The server may have received the ${inFlight} span(s) of the stopped export. ` : "") + `All ${residue} were not confirmed as delivered, and are counted as dropped. The ${timeoutMs} ms shutdown budget expired or the transport stopped accepting. Pass a larger timeout to shutdown(timeoutMs), or raise your container's termination grace period, to lose less.`
846
- );
849
+ if (this._quotaPaused()) {
850
+ warn(
851
+ `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ${queued} still queued and ${inFlight} in an export that shutdown() stopped. The monthly event quota is used up and export is paused until the next probe, so these spans could not be sent. A longer shutdown timeout does not help. Upgrade the plan or wait for the quota to reset.`
852
+ );
853
+ } else {
854
+ warn(
855
+ `shutdown() gave up with ${residue} span(s) (reason=shutdown_residue): ${queued} still queued and ${inFlight} in an export that shutdown() stopped. ` + (inFlight > 0 ? `The server may have received the ${inFlight} span(s) of the stopped export. ` : "") + `All ${residue} were not confirmed as delivered, and are counted as dropped. The ${timeoutMs} ms shutdown budget expired or the transport stopped accepting. Pass a larger timeout to shutdown(timeoutMs), or raise your container's termination grace period, to lose less.`
856
+ );
857
+ }
847
858
  }
848
859
  for (const exporter of this._exporters) {
849
860
  await shutdownExporter(exporter, Math.max(0, shutdownDeadline - Date.now()));
@@ -863,6 +874,19 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
863
874
  }
864
875
  _enqueue(span, exportAtBatchSize) {
865
876
  if (this._queue.length >= this._maxQueueSize) {
877
+ if (this._quotaPaused()) {
878
+ const oldest = this._queue.shift();
879
+ if (oldest !== void 0) this._retryCounts.delete(oldest.spanId);
880
+ this._recordDropped("quota_exceeded");
881
+ for (const exporter of this._exporters) {
882
+ try {
883
+ exporter.noteQuotaDrop?.(1);
884
+ } catch {
885
+ }
886
+ }
887
+ this._queue.push(span);
888
+ return;
889
+ }
866
890
  this._recordDropped("queue_full");
867
891
  if (this.droppedSpans === 1 || this.droppedSpans % 1e3 === 0) {
868
892
  warn(`Span queue full (${this._maxQueueSize}). ${this.droppedSpans} spans dropped so far.`);
@@ -874,6 +898,22 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
874
898
  void this._exportBatch();
875
899
  }
876
900
  }
901
+ /**
902
+ * True when every exporter that delivers is paused for the monthly quota (S-1). An exporter
903
+ * says so with `quotaPaused()`. A custom exporter has none: not paused.
904
+ */
905
+ _quotaPaused() {
906
+ const deciders = this._exporters.filter((e) => e.countsAsDelivery !== false);
907
+ if (deciders.length === 0) return false;
908
+ for (const exporter of deciders) {
909
+ try {
910
+ if (exporter.quotaPaused?.() !== true) return false;
911
+ } catch {
912
+ return false;
913
+ }
914
+ }
915
+ return true;
916
+ }
877
917
  /** A span that ended after the drain ended: counted, with one WARNING for the first. */
878
918
  _lateSpan() {
879
919
  this._recordDropped("shutdown_residue");
@@ -968,9 +1008,11 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
968
1008
  while (this._queue.length > 0 || this._flushing) {
969
1009
  const remaining = deadline - Date.now();
970
1010
  if (remaining <= 0) return finish(false);
1011
+ if (!this._flushing && this._queue.length > 0 && this._quotaPaused()) return finish(false);
971
1012
  if (!this._flushing && this._queue.length > 0) {
972
1013
  const outcome = await raceDeadline(this._exportBatch(), remaining);
973
1014
  if (outcome === DEADLINE) return finish(false);
1015
+ if (outcome === 4 /* Paused */) await new Promise((r) => setTimeout(r, 20));
974
1016
  } else {
975
1017
  await new Promise((r) => setTimeout(r, 1));
976
1018
  }
@@ -983,6 +1025,9 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
983
1025
  rejectedSpans: this.rejectedSpans,
984
1026
  droppedSpans: this.droppedSpans,
985
1027
  droppedSpansByReason: { ...this.droppedSpansByReason },
1028
+ // Spans dropped because the monthly event quota is used up (S-1). The same number as
1029
+ // `droppedSpansByReason.quota_exceeded`, for a reader that wants one key.
1030
+ droppedQuota: this.droppedSpansByReason.quota_exceeded,
986
1031
  failedExports: this.failedExports,
987
1032
  maskErrors: this.maskErrors,
988
1033
  queueSize: this._queue.length,
@@ -1004,6 +1049,12 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1004
1049
  this.exportedSpans += n;
1005
1050
  return;
1006
1051
  }
1052
+ const quota = Math.min(Math.max(ack.quotaDropped ?? 0, 0), n);
1053
+ if (quota > 0) {
1054
+ this._recordDropped("quota_exceeded", quota);
1055
+ n -= quota;
1056
+ if (n === 0) return;
1057
+ }
1007
1058
  const rejected = Math.min(ack.rejected, n);
1008
1059
  const accepted = Math.min(ack.accepted, n - rejected);
1009
1060
  const unacknowledged = n - accepted - rejected;
@@ -1038,6 +1089,7 @@ var BatchSpanProcessor = class _BatchSpanProcessor {
1038
1089
  async _exportBatch() {
1039
1090
  if (this._flushing) return 3 /* Busy */;
1040
1091
  if (this._queue.length === 0) return 0 /* Empty */;
1092
+ if (this._quotaPaused()) return 4 /* Paused */;
1041
1093
  this._flushing = true;
1042
1094
  let flight = null;
1043
1095
  try {
@@ -2390,7 +2442,111 @@ function markCancel(span, error) {
2390
2442
  }
2391
2443
 
2392
2444
  // src/version.ts
2393
- var SDK_VERSION = "0.9.0";
2445
+ var SDK_VERSION = "0.9.1";
2446
+
2447
+ // src/exporters/quota.ts
2448
+ var QUOTA_REASON = "monthly_quota_exceeded";
2449
+ var QUOTA_HEADER = "X-Risicare-Quota";
2450
+ var QUOTA_HEADER_VALUE = "exceeded";
2451
+ var DEFAULT_RETRY_AFTER_S = 300;
2452
+ var MIN_RETRY_AFTER_S = 1;
2453
+ var MAX_RETRY_AFTER_S = 3600;
2454
+ var QUOTA_WARN_WINDOW_MS = 36e5;
2455
+ var MAX_RESETS_AT_CHARS = 40;
2456
+ function asPositiveCount(v) {
2457
+ if (typeof v === "number") return Number.isFinite(v) && v > 0;
2458
+ if (typeof v === "string" && /^[0-9]+$/.test(v)) return Number(v) > 0;
2459
+ return false;
2460
+ }
2461
+ function boundedRetryAfter(value) {
2462
+ let n;
2463
+ if (typeof value === "number") n = value;
2464
+ else if (typeof value === "string" && value.trim() !== "") n = Number(value);
2465
+ else return DEFAULT_RETRY_AFTER_S;
2466
+ if (!Number.isFinite(n)) return DEFAULT_RETRY_AFTER_S;
2467
+ return Math.min(Math.max(n, MIN_RETRY_AFTER_S), MAX_RETRY_AFTER_S);
2468
+ }
2469
+ function boundedResetsAt(value) {
2470
+ if (typeof value !== "string" || value.length === 0) return null;
2471
+ const cut = value.slice(0, MAX_RESETS_AT_CHARS);
2472
+ return /^[ -~]*$/.test(cut) ? cut : null;
2473
+ }
2474
+ function headerSaysExceeded(headers) {
2475
+ try {
2476
+ const value = headers?.get?.(QUOTA_HEADER);
2477
+ return typeof value === "string" && value.trim().toLowerCase() === QUOTA_HEADER_VALUE;
2478
+ } catch {
2479
+ return false;
2480
+ }
2481
+ }
2482
+ function parseJsonDiscard(payload, headers) {
2483
+ const body = payload !== null && typeof payload === "object" && !Array.isArray(payload) ? payload : {};
2484
+ const stored = (asPositiveCount(body.accepted) || asPositiveCount(body.spansAccepted)) === true;
2485
+ if (body.reason === QUOTA_REASON || headerSaysExceeded(headers) && !stored) {
2486
+ return {
2487
+ retryAfterS: boundedRetryAfter(body.retryAfterSeconds),
2488
+ resetsAt: boundedResetsAt(body.resetsAt)
2489
+ };
2490
+ }
2491
+ return null;
2492
+ }
2493
+ var EPISODE_END_ACCEPTS = 3;
2494
+ var QuotaPause = class {
2495
+ constructor(now = () => performance.now()) {
2496
+ this.now = now;
2497
+ }
2498
+ _until = -Infinity;
2499
+ _inEpisode = false;
2500
+ _accepts = 0;
2501
+ _lastWarn = -Infinity;
2502
+ _lastInfo = -Infinity;
2503
+ /**
2504
+ * Spans dropped since the last WARNING: the full queue's (`addDrops`) and the batches that a
2505
+ * probe lost while the WARNING was held back. The WARNING carries the number.
2506
+ */
2507
+ _drops = 0;
2508
+ addDrops(count) {
2509
+ this._drops += count;
2510
+ }
2511
+ paused() {
2512
+ return this.now() < this._until;
2513
+ }
2514
+ remainingS() {
2515
+ return Math.max(0, (this._until - this.now()) / 1e3);
2516
+ }
2517
+ enter(discard, where, dropped) {
2518
+ const t = this.now();
2519
+ this._until = t + discard.retryAfterS * 1e3;
2520
+ this._inEpisode = true;
2521
+ this._accepts = 0;
2522
+ if (t - this._lastWarn >= QUOTA_WARN_WINDOW_MS) {
2523
+ this._lastWarn = t;
2524
+ const since = this._drops;
2525
+ this._drops = 0;
2526
+ warn(
2527
+ `Risicare: the monthly event quota is used up (monthly_quota_exceeded). ${where} discarded ${dropped} span(s) and will discard new ones until the quota resets (resetsAt=${discard.resetsAt ?? "unknown"}) or the plan changes. The SDK pauses export and sends one batch again in ${Math.round(discard.retryAfterS)} s. Spans that end in the meantime wait in the queue. When it is full the oldest spans are dropped (the most recent are kept) and counted as quota_exceeded in droppedSpansByReason; a batch that is discarded again is dropped and counted the same way. This is not an error and the SDK does not retry the batch. At most one such WARNING an hour.` + (since > 0 ? ` Spans dropped for the quota since the last WARNING: ${since}.` : "")
2528
+ );
2529
+ } else {
2530
+ this._drops += dropped;
2531
+ debug(`Quota discard again: ${dropped} span(s); paused for ${Math.round(discard.retryAfterS)} s`);
2532
+ }
2533
+ }
2534
+ accepted(where) {
2535
+ if (!this._inEpisode) return;
2536
+ this._accepts++;
2537
+ if (this._accepts < EPISODE_END_ACCEPTS) return;
2538
+ this._inEpisode = false;
2539
+ this._accepts = 0;
2540
+ this._until = -Infinity;
2541
+ const t = this.now();
2542
+ if (t - this._lastInfo >= QUOTA_WARN_WINDOW_MS) {
2543
+ this._lastInfo = t;
2544
+ info(`Risicare: ${where} accepts spans again; the export pause for the quota has ended.`);
2545
+ } else {
2546
+ debug("Quota pause ended (INFO already written this hour)");
2547
+ }
2548
+ }
2549
+ };
2394
2550
 
2395
2551
  // src/exporters/http.ts
2396
2552
  var CAPACITY_REFUSAL_STATUSES = /* @__PURE__ */ new Set([429, 503]);
@@ -2431,8 +2587,21 @@ var HttpExporter = class {
2431
2587
  _calls = /* @__PURE__ */ new Map();
2432
2588
  /** The ack of each finished call, by its batch. Read once by `takeAck(spans)`. */
2433
2589
  _acks = /* @__PURE__ */ new WeakMap();
2590
+ /** The batch processor dropped span(s) from a full queue in the quota pause (S-1). */
2591
+ noteQuotaDrop(count = 1) {
2592
+ this._quota.addDrops(count);
2593
+ }
2594
+ /** True while the exporter is paused for the monthly event quota (S-1). */
2595
+ quotaPaused() {
2596
+ return this._quota.paused();
2597
+ }
2434
2598
  /** The spans of each finished call that could not be serialized, by its batch. */
2435
2599
  _unserializable = /* @__PURE__ */ new WeakMap();
2600
+ /**
2601
+ * S-1: the paused state after a monthly-quota discard (see `quota.ts`). A discard is not a
2602
+ * failure: it does not touch the circuit breaker.
2603
+ */
2604
+ _quota = new QuotaPause();
2436
2605
  _circuitOpenUntil = 0;
2437
2606
  _circuitBreakerThreshold = 5;
2438
2607
  _circuitBreakerCooldownMs = 6e4;
@@ -2524,6 +2693,13 @@ var HttpExporter = class {
2524
2693
  }
2525
2694
  async _export(spans, call) {
2526
2695
  const cancelled = call.cancel.signal;
2696
+ if (this._quota.paused()) {
2697
+ debug(
2698
+ `Export skipped: monthly quota pause, ${Math.round(this._quota.remainingS())} s left; ${spans.length} span(s) dropped`
2699
+ );
2700
+ this._acks.set(spans, { accepted: 0, rejected: 0, quotaDropped: spans.length });
2701
+ return "success" /* SUCCESS */;
2702
+ }
2527
2703
  const parts = [];
2528
2704
  const bad = [];
2529
2705
  let errorClass = "";
@@ -2732,6 +2908,11 @@ var HttpExporter = class {
2732
2908
  `HTTP ${response.status} and a body that is not a Risicare ack (content-type: ${response.headers?.get?.("Content-Type") || "none"})`
2733
2909
  );
2734
2910
  }
2911
+ if (ack.quota !== void 0) {
2912
+ this._quota.enter(ack.quota, `The ingest endpoint ${this._safeEndpoint}`, spansSent);
2913
+ } else if (ack.result === "success" /* SUCCESS */) {
2914
+ this._quota.accepted(`the ingest endpoint ${this._safeEndpoint}`);
2915
+ }
2735
2916
  if (ack.result === "success" /* SUCCESS */) this._acks.set(spans, ack.counts);
2736
2917
  if (ack.final) call.noRetry = true;
2737
2918
  return ack.result;
@@ -2798,7 +2979,16 @@ async function checkAck(response, spansSent, scrub) {
2798
2979
  try {
2799
2980
  payload = await response.json();
2800
2981
  } catch {
2801
- return null;
2982
+ payload = void 0;
2983
+ }
2984
+ const discard = parseJsonDiscard(payload, response.headers);
2985
+ if (discard !== null) {
2986
+ return {
2987
+ result: "success" /* SUCCESS */,
2988
+ counts: { accepted: 0, rejected: 0, quotaDropped: spansSent },
2989
+ final: false,
2990
+ quota: discard
2991
+ };
2802
2992
  }
2803
2993
  if (payload === null || typeof payload !== "object" || Array.isArray(payload)) {
2804
2994
  return null;
@@ -4439,8 +4629,10 @@ function getMetrics() {
4439
4629
  queue_full: 0,
4440
4630
  transport_refused: 0,
4441
4631
  shutdown_residue: 0,
4442
- unacknowledged: 0
4632
+ unacknowledged: 0,
4633
+ quota_exceeded: 0
4443
4634
  },
4635
+ droppedQuota: 0,
4444
4636
  failedExports: 0,
4445
4637
  queueSize: 0,
4446
4638
  queueCapacity: 0,