@volter/teams 0.2.11 → 0.2.13

package/event-client.mjs

@@ -1,8 +1,59 @@
 // Public custody door: consumers follow HTTP events without resolving the Teams binary or reading its files.
+// Streams are per team install, not per process: a follow reads through this machine's connector (the daemon's
+// `events` door, one stream the connector holds) whenever it serves the selected context's team and credential, and
+// opens a stream to the server only when it does not (another machine's team, no connector, one source's events).
 import { dirname } from 'node:path';
-import { teamsHome } from './home.mjs';
-import { fromContext } from './context.mjs';
+import { teamsHome, paths } from './home.mjs';
+import { fromContext, WorkspaceContexts } from './context.mjs';
+import { openLocalMachine } from './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});
-  return {team:client.team(context.team_id),context:{name,org:context.team_id,principal:context.principal_id,server:context.origin}};
+  // The machine this home connected to the team: its daemon may serve the follow, and a stream to the server names it,
+  // so the server counts the stream against this install.
+  let machine=null;try{machine=new WorkspaceContexts(supercodeHome).connector(context.server_id,context.team_id).read()?.machine?.id??null;}catch{}
+  client.machine=machine;
+  const team=client.team(context.team_id),remote=team.events.follow;
+  team.events.follow=(query={},options={})=>follow({socket:paths(teamsHome()).socket,context,machine,query,options,remote});
+  return {team,context:{name,org:context.team_id,principal:context.principal_id,server:context.origin}};
+}
+
+async function* follow({socket,context,machine,query,options,remote}) {
+  const stream=machine&&Object.keys(query).every(key=>key==='kinds'||key==='source'&&query.source==null)?await openLocal(socket,context,query,options.after):null;
+  if(!stream){yield* remote(query,options);return;}
+  yield* frames(stream,options.signal);
+}
+
+/** The connector's `events` door for this context, or null when this machine's daemon does not serve it. */
+async function openLocal(socket,context,query,after) {
+  let channel;
+  try{channel=await openLocalMachine(socket,{timeoutMs:2000});}catch{return null;}
+  try{
+    const kinds=query.kinds==null?null:(Array.isArray(query.kinds)?[...query.kinds]:String(query.kinds).split(',')).sort();
+    const stream=await channel.open('events',{server_id:context.server_id,team_id:context.team_id,credential_ref:context.credential_ref,kinds,source:null,after:after??null},{timeoutMs:5000});
+    // The door's first frames (a whole snapshot) arrive with its opening: its reader is attached in this same tick, with
+    // its close, or the stream replays them to no data listener and they are lost.
+    const reader={stream,queue:[],closed:null,wake:null};
+    stream.on('data',chunk=>{reader.queue.push(chunk);reader.wake?.();});
+    stream.on('close',reason=>{reader.closed={reason};reader.wake?.();channel.close();});
+    return reader;
+  }catch{channel.close();return null;}
+}
+
+/** The door's frames as the server's: one JSON frame per message, a terminal frame ends it, a drop is retryable. */
+async function* frames(reader,signal) {
+  const {stream,queue}=reader;
+  const abort=()=>stream.close('aborted');signal?.addEventListener('abort',abort,{once:true});
+  try{
+    for(;;){
+      while(queue.length){const frame=JSON.parse(queue.shift());yield frame;if(frame.terminal)return;}
+      if(signal?.aborted)return;
+      if(reader.closed){
+        const reason=String(reader.closed.reason??'closed');
+        throw Object.assign(new Error(`local published events: ${reason}`),reason.startsWith('invalid_request')?{code:'invalid_request',status:400,retryable:false}:{code:'unavailable',retryable:true});
+      }
+      await new Promise(resolve=>{reader.wake=resolve;});reader.wake=null;
+    }
+  }finally{signal?.removeEventListener('abort',abort);if(!stream.closed)stream.close('done');}
 }

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 }
@@ -139,8 +139,10 @@ export interface TeamClient {
   };
 }
 export declare class TeamsClient {
-  constructor(options: {server: string; credential: string; fetch?: typeof fetch});
+  /** `machine`: this install's enrolled machine id, named on event streams so the server counts them per install. */
+  constructor(options: {server: string; credential: string; fetch?: typeof fetch; machine?: string | null});
   server: string;
+  machine: string | null;
   request<T = unknown>(method: string, path: string, options?: RequestOptions & {body?: unknown}): Promise<T>;
   me(options?: RequestOptions): Promise<unknown>;
   capabilities(options?: RequestOptions): Promise<{version: 1; server_id: string; protocol: 'teams.v1'; operations: string[]; auth_modes: string[]}>;
@@ -149,3 +151,6 @@ export declare class TeamsClient {
   redeemAppCode(body: unknown, options?: RequestOptions): Promise<unknown>;
   team(id: string): TeamClient;
 }
+/** 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,17 +13,20 @@ 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)(?:\/|$)/;
 // Node only (it reads custody files); a browser sends what its person typed, and a bundler must not pull it in.
 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)}){this.server=trimOrigin(server);this.credential=credential;this.fetch=fetchImpl;if(typeof fetchImpl!=='function')throw new TypeError('fetch is required');}
-  async request(method,path,{body,signal,idempotencyKey,ifMatch}={}) {
+  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,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); } }
@@ -227,13 +230,28 @@ async function* attachmentEvents(root, base, attachment, { signal } = {}) {
 }
 const query=q=>{const p=new URLSearchParams();for(const [k,v]of Object.entries(q))if(v!==undefined)p.set(k,String(v));return p.size?'?'+p:'';};
 const retryWait=(delay,signal)=>new Promise((resolve,reject)=>{const done=()=>{signal?.removeEventListener('abort',abort);resolve();},timer=setTimeout(done,delay),abort=()=>{clearTimeout(timer);signal?.removeEventListener('abort',abort);reject(signal.reason);};signal?.addEventListener('abort',abort,{once:true});});
-async function sseError(response){let value=null;try{value=await response.json();}catch{}return Object.assign(new Error(value?.error?.message??`SSE HTTP ${response.status}`),value?.error,{status:response.status,retryable:value?.error?.retryable??(response.status===429||response.status>=500)});}
-async function* events(root,path,{signal,after}={}){
+async function sseError(response){let value=null;try{value=await response.json();}catch{}return Object.assign(new Error(value?.error?.message??`SSE HTTP ${response.status}`),value?.error,{status:response.status,retryable:value?.error?.retryable??(response.status===429||response.status>=500),retryAfterMs:retryAfterMs(value?.error,response)});}
+// How long a refused stream waits before asking again: the server's retry_after (its body, else Retry-After), at least
+// 5 s; a refusal that names none waits 30 s. Null for an error that is not a refusal for load.
+export function retryAfterMs(error,response=null){
+  if(typeof error?.retryAfterMs==='number')return error.retryAfterMs;
+  if(error?.code!=='rate_limited'&&response?.status!==429&&error?.status!==429)return 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);
+}
+// 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}`,...(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='';
@@ -245,7 +263,7 @@ async function* events(root,path,{signal,after}={}){
         }
       }
       lastError=Object.assign(new Error('SSE stream ended before a terminal event'),{retryable:true});
-    }catch(error){if(signal?.aborted)return;if(error.retryable===false||error.status&&error.status!==429&&error.status<500)throw error;lastError=error;}
+    }catch(error){if(signal?.aborted)return;if(error.retryable===false||error.status&&error.status!==429&&error.status<500||error.retryAfterMs)throw error;lastError=error;}
     if(attempt<4)await retryWait(Math.min(250*2**attempt,5000),signal).catch(()=>{});
   }
   if(!signal?.aborted&&lastError)throw lastError;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volter/teams",
-  "version": "0.2.11",
+  "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",

package/server/events.mjs

@@ -15,3 +15,23 @@ export function sseRoom(res,bytes,{cap=SSE_BACKLOG_BYTES,patienceMs=SSE_PATIENCE
     res.on('drain',drained);res.on('close',ended);
   });
 }
+// Open event streams are counted per team install: a credential on one machine (a machine credential's own machine, or
+// the enrolled machine of this team its request names in X-Supercode-Machine), else the credential with no machine.
+// An install's connector holds one published-events stream that its local readers share (dispatchers, agents, apps on
+// that machine read through its door), and its people open a few viewers beside it (session follows, a catalogue
+// watch): one stream, one more while a dropped one is still being noticed, about five viewers, and headroom makes 10.
+// A credential's streams over all its machines stop at 40, so a leaked token cannot hold the server's connections.
+export const STREAMS_PER_INSTALL=10, STREAMS_PER_CREDENTIAL=40;
+// A slot frees only when another stream of the install closes; a refused reader asks again no sooner than this.
+export const STREAM_RETRY_SECONDS=30;
+/** Count one open stream for `auth`'s install, refusing past the limits; resolves the release (idempotent). */
+export async function holdStream(api,auth,req){
+  const named=String(req.headers['x-supercode-machine']??'');
+  let machine=auth.kind==='machine'?auth.machine_id:'';
+  if(!machine&&/^mach_[A-Za-z0-9_-]{1,64}$/.test(named)&&await api.store.one('SELECT 1 FROM machines WHERE team_id=? AND id=? AND revoked_at IS NULL',[auth.team_id,named]))machine=named;
+  const keys=[`install:${auth.credential_id}\0${machine}`,`credential:${auth.credential_id}`],limits=[STREAMS_PER_INSTALL,STREAMS_PER_CREDENTIAL];
+  if(keys.some((key,at)=>(api.openStreams.get(key)??0)>=limits[at]))throw Object.assign(new Error(`too many open event streams for this ${machine?'machine':'credential'}`),{status:429,code:'rate_limited',details:{retry_after_seconds:STREAM_RETRY_SECONDS,streams_per_install:STREAMS_PER_INSTALL,machine:machine||null}});
+  for(const key of keys)api.openStreams.set(key,(api.openStreams.get(key)??0)+1);
+  let held=true;
+  return ()=>{if(!held)return;held=false;for(const key of keys){const next=(api.openStreams.get(key)??1)-1;if(next>0)api.openStreams.set(key,next);else api.openStreams.delete(key);}};
+}

package/server/machine-events.mjs

@@ -1,5 +1,5 @@
 // A retained machine transition log for Teams mailbox subscriptions.
-import { writeSse } from './events.mjs';
+import { writeSse, holdStream } from './events.mjs';
 
 export function machineTransition(api, team, machine, linked) {
   // Serialize the read/change/event across asynchronous store calls. A replaced
@@ -37,11 +37,9 @@ export async function reconcileMachinePresence(api) {
 export async function machineEventStream({api,req,res,auth,url,requestId,fail}) {
   const after = url.searchParams.get('after') ?? req.headers['last-event-id'];
   if (after != null && (!/^\d+$/.test(after) || !Number.isSafeInteger(Number(after)))) fail(400,'invalid_request','after must be a machine event cursor');
-  const count = api.openStreams.get(auth.credential_id) ?? 0;
-  if (count >= 10) fail(429,'rate_limited','too many open streams');
-  api.openStreams.set(auth.credential_id,count+1);
+  const release = await holdStream(api,auth,req);
   let closed=false, cursor=after==null?null:Number(after), work=Promise.resolve();
-  const close=()=>{ if(closed)return;closed=true;clearInterval(timer);unsubscribe();req.off('close',close);api.events.off('shutdown',close);api.openStreams.set(auth.credential_id,Math.max(0,(api.openStreams.get(auth.credential_id)??1)-1));res.end(); };
+  const close=()=>{ if(closed)return;closed=true;clearInterval(timer);unsubscribe();req.off('close',close);api.events.off('shutdown',close);release();res.end(); };
   const write=event=>{if(closed)return;if(res.writableLength>1024*1024){close();return;}writeSse(res,event);};
   const drain=async()=>{
     if(closed)return;

package/server/published-events.mjs

@@ -3,7 +3,7 @@ import { appAuthentication } from './apps.mjs';
 import { isAdmin } from './auth.mjs';
 import { exact } from './request-json.mjs';
 import { canonicalJson } from './wire.mjs';
-import { sseRoom, writeSse } from './events.mjs';
+import { sseRoom, writeSse, holdStream } from './events.mjs';
 import { APP_EVENTS, PUBLISHABLE_EVENTS, eventReadAction } from './event-catalogue.mjs';
 import { EVENT_DATA_LIMIT } from '../event-limits.mjs';
 
@@ -159,10 +159,9 @@ async function eventStream({api,req,res,auth,url,requestId}){
   if([...url.searchParams.keys()].some(key=>!['after','source','kinds'].includes(key))||query.kinds?.some(kind=>!APP_EVENTS.includes(kind)))fail(400,'invalid_request','invalid event subscription');
   auth=await liveAuth(api,auth);let codec=cursorCodec(api,auth,query);
   const after=url.searchParams.get('after')??req.headers['last-event-id'];let cursor=after==null?null:codec.decode(after);
-  const count=api.openStreams.get(auth.credential_id)??0;if(count>=10)fail(429,'rate_limited','too many event subscriptions');
-  api.openStreams.set(auth.credential_id,count+1);
+  const release=await holdStream(api,auth,req);
   let closed=false,running=null,dirty=false;
-  const close=()=>{if(closed)return;closed=true;clearInterval(timer);unsubscribe();req.off('close',close);api.events.off('shutdown',close);api.openStreams.set(auth.credential_id,Math.max(0,(api.openStreams.get(auth.credential_id)??1)-1));res.end();};
+  const close=()=>{if(closed)return;closed=true;clearInterval(timer);unsubscribe();req.off('close',close);api.events.off('shutdown',close);release();res.end();};
   const terminal=(type,reason)=>{if(!closed)writeSse(res,{type,reason,terminal:true});close();};
   const write=async event=>{if(closed)return false;const room=await sseRoom(res,Buffer.byteLength(JSON.stringify(event)));if(closed||room==='closed')return false;if(room==='slow'){terminal('resync_required','slow_reader');return false;}writeSse(res,event);return true;};
   const readable=async event=>{