@volter/teams 0.2.12 → 0.2.13

package/event-client.mjs

@@ -6,7 +6,7 @@ import { dirname } from 'node:path';
 import { teamsHome, paths } from './home.mjs';
 import { fromContext, WorkspaceContexts } from './context.mjs';
 import { openLocalMachine } from './client.mjs';
-export { retryAfterMs } from './http-client.mjs';
+export { retryAfterMs, spentClause } from './http-client.mjs';
 
 export function eventClient({supercodeHome=dirname(teamsHome()),context: name,fetch}={}) {
   const {client,context}=fromContext({supercodeHome,name,fetch});

package/http-client.d.ts

@@ -1,5 +1,5 @@
 /** Neutral HTTP transport. Product extensions keep their payloads in their own contracts. */
-export interface RequestOptions { signal?: AbortSignal; idempotencyKey?: string; ifMatch?: number }
+export interface RequestOptions { signal?: AbortSignal; idempotencyKey?: string; ifMatch?: number; /** this call site's name, appended to the process's X-Supercode-Caller */ caller?: string }
 export interface StreamOptions extends RequestOptions { after?: string }
 export type Query = Record<string, unknown>;
 export interface Result<T = unknown> { version: number; data: T; [key: string]: unknown }
@@ -153,3 +153,4 @@ export declare class TeamsClient {
 }
 /** Milliseconds a stream refused for load waits before asking again (the server's retry_after, at least 5 s), else null. */
 export declare function retryAfterMs(error: unknown, response?: Response | null): number | null;
+export declare function spentClause(error: unknown): string;

package/http-client.mjs

@@ -13,6 +13,9 @@ export function callerName(env=globalThis.process?.env,argv=globalThis.process?.
   return ([script,...words].join(' ')+(session?` in ${session}`:'')).replace(/[^\x20-\x7e]/g,'?').slice(0,120);
 }
 const CALLER=callerName();
+// A call site may name itself after the process (`caller: 'board-relay publish'`), so one process's doors are told
+// apart in the server's tally; the process's own words are kept, the site's words always fit.
+const callerHeader=site=>{if(!CALLER)return {};if(!site)return {'X-Supercode-Caller':CALLER};const named=String(site).replace(/[^\x20-\x7e]/g,'?').slice(0,60);return {'X-Supercode-Caller':`${CALLER.slice(0,119-named.length)} ${named}`};};
 // Every write to a Teams server is redacted (@volter/teams/redact), but a sign-in or credential exchange, whose body is
 // the credential it hands over.
 const SIGN_IN=/\/(?:login|apps\/token|invitations\/accept|credentials|me\/identities)(?:\/|$)/;
@@ -20,10 +23,10 @@ const SIGN_IN=/\/(?:login|apps\/token|invitations\/accept|credentials|me\/identi
 const { redactValue } = globalThis.process?.versions?.node ? await import(`./redact${'.mjs'}`) : { redactValue: (value) => value };
 export class TeamsClient {
   constructor({server,credential,fetch:fetchImpl=(...args)=>globalThis.fetch(...args),machine=null}){this.server=trimOrigin(server);this.credential=credential;this.fetch=fetchImpl;this.machine=machine;if(typeof fetchImpl!=='function')throw new TypeError('fetch is required');}
-  async request(method,path,{body,signal,idempotencyKey,ifMatch}={}) {
+  async request(method,path,{body,signal,idempotencyKey,ifMatch,caller}={}) {
     const key=idempotencyKey??(method==='GET'?null:randomKey());let delay=250,last;
     for(let attempt=0;attempt<5;attempt++) { try {
-      const response=await this.fetch(this.server+path,{method,signal,redirect:'manual',headers:{Accept:'application/json',Authorization:`Bearer ${this.credential}`,...(CALLER?{'X-Supercode-Caller':CALLER}:{}),...(body!==undefined?{'Content-Type':'application/json'}:{}),...(key?{'Idempotency-Key':key}:{}),...(ifMatch!==undefined?{'If-Match':String(ifMatch)}:{})},body:body===undefined?undefined:JSON.stringify(SIGN_IN.test(path)?body:redactValue(body))});
+      const response=await this.fetch(this.server+path,{method,signal,redirect:'manual',headers:{Accept:'application/json',Authorization:`Bearer ${this.credential}`,...callerHeader(caller),...(body!==undefined?{'Content-Type':'application/json'}:{}),...(key?{'Idempotency-Key':key}:{}),...(ifMatch!==undefined?{'If-Match':String(ifMatch)}:{})},body:body===undefined?undefined:JSON.stringify(SIGN_IN.test(path)?body:redactValue(body))});
       if(response.type==='opaqueredirect'||(response.status>=300&&response.status<400))throw Object.assign(new Error('cross-origin redirects are refused'),{code:'invalid_request',status:400,retryable:false});
       const value=response.status===204?null:await response.json();if(!response.ok)throw Object.assign(new Error(value?.error?.message??`HTTP ${response.status}`),value?.error,{status:response.status});return value;
     } catch(error) { last=error;if(method!=='GET'||signal?.aborted||!(!error.status||error.retryable)||attempt===4)throw error;await retryWait(delay,signal);delay=Math.min(delay*2,5000); } }
@@ -236,12 +239,19 @@ export function retryAfterMs(error,response=null){
   const named=error?.details?.retry_after_seconds??error?.retry_after_seconds??response?.headers?.get?.('retry-after'),seconds=named==null||named===''?NaN:Number(named);
   return Math.max(5000,Number.isFinite(seconds)?seconds*1000:30000);
 }
-async function* events(root,path,{signal,after}={}){
+// Who spent the credential's last minute, as a refusal for the rate limit carries it (the server's tally by caller and
+// route), for a log line: `; spent 118/min: caller a=60, b=40; route POST /x=70`. Empty for any other error.
+export function spentClause(error){
+  const spent=error?.code==='rate_limited'?error.details?.spent_last_minute:null;if(!spent)return '';
+  const top=list=>(Array.isArray(list)?list:[]).slice(0,3).map(entry=>`${entry.name}=${entry.count}`).join(', ')||'none';
+  return `; spent ${spent.requests}/min: caller ${top(spent.by_caller)}; route ${top(spent.by_route)}`;
+}
+async function* events(root,path,{signal,after,caller}={}){
   let cursor=after??null,lastYielded=null,lastError=null;
   for(let attempt=0;attempt<5&&!signal?.aborted;attempt++){
     const suffix=cursor?path+(path.includes('?')?'&':'?')+'after='+encodeURIComponent(cursor):path;
     try{
-      const response=await root.fetch(root.server+suffix,{signal,redirect:'manual',headers:{Accept:'text/event-stream',Authorization:`Bearer ${root.credential}`,...(CALLER?{'X-Supercode-Caller':CALLER}:{}),...(root.machine?{'X-Supercode-Machine':root.machine}:{}),...(cursor?{'Last-Event-ID':cursor}:{})}});
+      const response=await root.fetch(root.server+suffix,{signal,redirect:'manual',headers:{Accept:'text/event-stream',Authorization:`Bearer ${root.credential}`,...callerHeader(caller),...(root.machine?{'X-Supercode-Machine':root.machine}:{}),...(cursor?{'Last-Event-ID':cursor}:{})}});
       if(response.type==='opaqueredirect'||response.status>=300&&response.status<400)throw Object.assign(new Error('cross-origin redirects are refused'),{code:'invalid_request',status:400,retryable:false});
       if(!response.ok)throw await sseError(response);
       let buffer='';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.2.12",
+  "version": "0.2.13",
   "type": "module",
   "description": "Volter Teams, the neutral team plane: machine identity and daemon core, the local door and server link, admission from machine grants, product doors, and the Teams server's neutral routes (company RFC 0008).",
   "license": "MIT",