nucleus-core-ts 0.10.190 → 0.10.192
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.
- package/dist/.build-ok +1 -1
- package/dist/server.js +1 -1
- package/dist/src/Services/Tenant/purgeTenant.d.ts +28 -4
- package/package.json +1 -1
- package/scripts/demo-film/capture/capture.test.ts +73 -0
- package/scripts/demo-film/capture/captureRun.ts +106 -0
- package/scripts/demo-film/capture/director.ts +110 -0
- package/scripts/demo-film/capture/index.ts +12 -0
- package/scripts/demo-film/capture/types.ts +102 -0
- package/scripts/demo-film/fixtures/fixtures.test.ts +66 -0
- package/scripts/demo-film/fixtures/index.ts +13 -0
- package/scripts/demo-film/fixtures/match.ts +46 -0
- package/scripts/demo-film/fixtures/server.ts +80 -0
- package/scripts/demo-film/fixtures/sse.ts +42 -0
- package/scripts/demo-film/fixtures/types.ts +76 -0
- package/scripts/demo-film/index.ts +6 -2
package/dist/.build-ok
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
0.10.
|
|
1
|
+
0.10.192
|
package/dist/server.js
CHANGED
|
@@ -672,4 +672,4 @@ ${content}
|
|
|
672
672
|
ip_address = null, user_agent = null, query = null,
|
|
673
673
|
old_values = '{}'::jsonb, new_values = '{}'::jsonb, summary = ${REDACTED2}
|
|
674
674
|
where user_id::text = ${userId} or entity_id::text = ${userId}
|
|
675
|
-
or entity_id::text = any (${ids}::text[])`),count6=typeof result==="object"&&result!==null?Reflect.get(result,"rowCount"):0;return typeof count6==="number"?count6:0}var log7=logger.scoped("auth.accountErasure"),ERASURE_REASON="Account erasure (KVKK/GDPR right to erasure)";async function plan(executor,schema3,userId,policy2,options){let planned=[],refused=[],foreignKeys=await userReferences(executor,schema3),declared=await declaredReferences(executor,schema3,declaredColumns(options),foreignKeys);for(let ref3 of[...foreignKeys,...declared]){if(ref3.table===AUDIT_TABLE)continue;let rows=await countReferences(executor,schema3,ref3,userId);if(rows===0)continue;let rule=ruleFor(policy2,ref3),name2=`${ref3.table}.${ref3.column}`;if(rule===void 0)refused.push(`${name2}: no rule`);else{let problem=problemOf(ref3,rule);if(problem===null)planned.push({ref:ref3,rule,rows});else refused.push(`${name2}: ${problem}`)}}if(refused.length>0)throw new AccountErasureError(`Erasure refused, references left unhandled: ${refused.join("; ")}`,refused.map((line)=>line.split(":")[0]??line));return planned}async function apply2(executor,schema3,userId,{ref:ref3,rule},summary){let table2=sql47`${sql47.identifier(schema3)}.${sql47.identifier(ref3.table)}`,column3=sql47.identifier(ref3.column),own=ref3.table==="users"?sql47` and id <> ${userId}`:sql47``,returning=ref3.hasId?sql47` returning id`:sql47``;if(rule==="delete"){let done=touchedOf(await executor.execute(sql47`delete from ${table2} where ${column3} = ${userId}${own}${returning}`),ref3.hasId);return summary.deleted[ref3.table]=(summary.deleted[ref3.table]??0)+done.count,done.ids}if(rule==="nullify"){let done=touchedOf(await executor.execute(sql47`update ${table2} set ${column3} = null where ${column3} = ${userId}${own}${returning}`),ref3.hasId);return summary.nullified[ref3.table]=(summary.nullified[ref3.table]??0)+done.count,[]}let rows=(summary.kept[ref3.table]?.rows??0)+await countReferences(executor,schema3,ref3,userId);return summary.kept[ref3.table]={rows,reason:rule.keep},[]}async function eraseUser(unit,userId,policy2,options={}){return assertKeepReasons(policy2),unit.withoutRules(ERASURE_REASON,()=>erase(unit,userId,policy2,options))}async function erase(unit,userId,policy2,options){let executor=executorOf2(unit),schema3=unit.schema,summary={sessions:await endUserSessions(unit,userId),deleted:{},nullified:{},kept:{},users:0,auditScrubbed:0},planned=await plan(executor,schema3,userId,policy2,options),deletedIds=[];for(let step of planned)deletedIds.push(...await apply2(executor,schema3,userId,step,summary));summary.auditScrubbed=await scrubAuditRows(executor,schema3,userId,deletedIds);let removed=await executor.execute(sql47`delete from ${sql47.identifier(schema3)}.users where id = ${userId}`);return summary.users=touchedOf(removed,!1).count,await unit.audit({entityName:"users",operation:"ERASE_USER",summary:"An account was erased.",severity:"info",category:"system",newValues:{...summary}}),log7.info("Account erased",{schema:schema3,...summary}),summary}init_hostPasswordCheck();init_hooks();init_linkAuthorization();init_profileSync();init_profileSyncHooks();import{sql as sql48}from"drizzle-orm";init_Logger2();init_schema();var log8=logger.scoped("tenant.purge"),PROTECTED_SCHEMAS=new Set(["public","information_schema"]);class TenantPurgeRefusedError extends Error{tenantId;status;constructor(tenantId,status){super(`Tenant ${tenantId} is ${status}: purging it needs force`);this.tenantId=tenantId;this.status=status;this.name="TenantPurgeRefusedError"}}function toRow(row){if(row===void 0)return null;return{subdomain:String(Reflect.get(row,"subdomain")),schemaName:String(Reflect.get(row,"schema_name")),status:String(Reflect.get(row,"status"))}}function assertDroppable(schemaName,mainSchema){if(validateIdentifier(schemaName),schemaName===mainSchema||PROTECTED_SCHEMAS.has(schemaName)||schemaName.startsWith("pg_"))throw Error(`Refusing to drop protected schema "${schemaName}"`)}async function purgeTenant(tenantId,options){let registry5=options.registry===void 0?currentRegistry():options.registry,main=sql48.identifier(validateIdentifier(options.mainSchema)),outcome=await options.db.transaction(async(tx)=>{await tx.execute(sql48`select pg_advisory_xact_lock(hashtext(${`tenant_purge:${tenantId}`}))`);let found=await tx.execute(sql48`select subdomain, schema_name, status from ${main}.tenants where id = ${tenantId} for update`),row=toRow(rowsOfResult(found)[0]);if(row===null){let leftover=registry5?.getTenantById(tenantId)?.schemaName;if(leftover!==void 0)assertDroppable(leftover,options.mainSchema),await tx.execute(sql48`drop schema if exists ${sql48.identifier(leftover)} cascade`);return{purged:!1,tenantId,alreadyPurged:!0}}if(row.status==="active"&&options.force!==!0)throw new TenantPurgeRefusedError(tenantId,row.status);return assertDroppable(row.schemaName,options.mainSchema),await writeTenantAudit(tx,options.mainSchema,{entityName:"tenants",entityId:tenantId,operation:"TENANT_PURGE",summary:`${row.subdomain} hard-deleted${options.reason?` (${options.reason})`:""}`,category:"admin",severity:"critical",oldValues:{subdomain:row.subdomain,schemaName:row.schemaName,status:row.status},newValues:{reason:options.reason??null,performedBy:options.performedBy??null}}),await tx.execute(sql48`drop schema if exists ${sql48.identifier(row.schemaName)} cascade`),await tx.execute(sql48`delete from ${main}.tenants where id = ${tenantId}`),{purged:!0,tenantId,subdomain:row.subdomain,schemaName:row.schemaName}});return await registry5?.forgetTenant(tenantId),log8.info(outcome.purged?"Tenant purged":"Tenant already purged",{tenantId}),outcome}function formErrors(rule,fields,context){let merged={...context.item,...context.entered},checked=validateFieldValues(fields,merged,{party:context.actor.side}).errors,errors2=new Map;for(let id of Object.keys(context.entered))if(!rule.form.includes(id))errors2.set(id,"unknown_field");for(let id of rule.form){let code=Object.hasOwn(checked,id)?checked[id]:void 0;if(code===void 0)continue;if(Object.hasOwn(context.entered,id)&&!isEmptyValue(context.entered[id])||code==="required")errors2.set(id,code)}return Object.fromEntries(errors2)}var holdsRole=(rule,context)=>context.actor.roles.some((role)=>rule.roles.includes(role)),onForm=(rule)=>rule.when!==null&&rule.form.includes(rule.when.field),conditionFails=(rule,context)=>rule.when!==null&&!evaluateCondition(rule.when,{...context.item,...context.entered});function ruleFailure(rule,fields,context){if(rule.side!==context.actor.side)return{code:"transition_side_forbidden"};if(!holdsRole(rule,context))return{code:"transition_role_forbidden"};if(rule.onlyCreator&&!context.isCreator)return{code:"transition_creator_only"};if(!onForm(rule)&&conditionFails(rule,context))return{code:"transition_condition_not_met"};if(context.mode==="offer")return null;let fieldErrors=formErrors(rule,fields,context);if(Object.keys(fieldErrors).length>0)return{code:"transition_fields_invalid",fieldErrors};if(onForm(rule)&&conditionFails(rule,context))return{code:"transition_condition_not_met"};if(rule.requireNote&&(context.note??"").trim()==="")return{code:"transition_note_required"};return null}var FLOW_FAILURE_CODES=["transition_unknown","transition_unknown_state","transition_source_mismatch","transition_from_final","transition_start_forbidden","transition_side_forbidden","transition_role_forbidden","transition_creator_only","transition_condition_not_met","transition_fields_invalid","transition_note_required"];function failureCodeOf(message){return FLOW_FAILURE_CODES.find((code)=>code===message)??null}function rulesOf(document){return document.transitions.flatMap((transition)=>{let common={key:transition.key,to:transition.to,side:transition.side,roles:transition.roles,form:transition.form,requireNote:transition.requireNote,onlyCreator:transition.onlyCreator===!0,when:transition.when??null};return(transition.from==="create"?[null]:transition.from).map((from)=>({...common,from}))})}function edgesOf(rules,fields){let grouped=new Map;for(let rule of rules){if(rule.from===null)continue;let targets=grouped.get(rule.from)??new Map;targets.set(rule.to,[...targets.get(rule.to)??[],rule]),grouped.set(rule.from,targets)}let edges=new Map;for(let[from,targets]of grouped)edges.set(from,[...targets].map(([to,edgeRules])=>({to,guard:(context)=>{let rule=edgeRules.find((candidate)=>candidate.key===context.key);if(rule===void 0)return"transition_source_mismatch";return ruleFailure(rule,fields,context)?.code??!0}})));return edges}function buildFlow(document,options={}){let rules=rulesOf(document),fields=document.fields??[],edges=edgesOf(rules,fields),transitions=Object.fromEntries(document.states.map((state)=>[state.key,edges.get(state.key)??[]])),terminal=document.states.filter((state)=>state.terminal===!0||options.isTerminal?.(state)===!0).map((state)=>state.key),declared=new Set(document.states.map((state)=>state.key));return{table:{initial:[...new Set(rules.filter((rule)=>rule.from===null&&declared.has(rule.to)).map((rule)=>rule.to))],terminal,transitions},rules,fields}}var REFUSALS={unknown_state:"transition_unknown_state",terminal_state:"transition_from_final",no_transition:"transition_source_mismatch"};function ruleOf(flow,key2,from){let found=flow.rules.find((rule)=>rule.key===key2&&rule.from===from);if(found!==void 0)return found;return flow.rules.some((rule)=>rule.key===key2)?"transition_source_mismatch":"transition_unknown"}function judge2(flow,rule,context){if(rule.from===null){if(!canStartIn(flow.table,rule.to))return{ok:!1,code:"transition_start_forbidden"};let failure2=ruleFailure(rule,flow.fields,context);return failure2===null?{ok:!0,rule}:{ok:!1,...failure2}}if(!Object.hasOwn(flow.table.transitions,rule.to))return{ok:!1,code:"transition_unknown_state"};let evaluation=evaluate(flow.table,rule.from,rule.to,context);if(evaluation.allowed)return{ok:!0,rule};if(evaluation.reason!=="guard_rejected")return{ok:!1,code:REFUSALS[evaluation.reason]};let failure=ruleFailure(rule,flow.fields,context),code=failure?.code??failureCodeOf(evaluation.message);return code===null?{ok:!1,code:"transition_source_mismatch"}:{ok:!1,code,...failure?.fieldErrors?{fieldErrors:failure.fieldErrors}:{}}}function decideTransition(flow,attempt3){let rule=ruleOf(flow,attempt3.key,attempt3.from);if(typeof rule==="string")return{ok:!1,code:rule};return judge2(flow,rule,{...attempt3,mode:"perform"})}function allowedTransitions(flow,offer){return flow.rules.filter((rule)=>rule.from===offer.state&&ruleOf(flow,rule.key,rule.from)===rule&&judge2(flow,rule,{...offer,from:offer.state,key:rule.key,entered:{},mode:"offer"}).ok)}function flowProblems(document,options={}){let problems=[],add2=(code,subject,message)=>problems.push({code,subject,message}),states=new Set;for(let state of document.states){if(states.has(state.key))add2("duplicate_state",state.key,`State "${state.key}" is declared twice`);states.add(state.key)}let defined=new Set((document.fields??[]).map((field2)=>field2.id)),keys=new Set;for(let transition of document.transitions){if(keys.has(transition.key))add2("duplicate_transition",transition.key,`Transition "${transition.key}" is declared twice`);keys.add(transition.key);let sources=transition.from==="create"?[]:transition.from;if(transition.roles.length===0)add2("no_roles",transition.key,`Transition "${transition.key}" lists no role: nobody could make it`);if(transition.from!=="create"&&sources.length===0)add2("no_source",transition.key,`Transition "${transition.key}" starts from no state`);for(let state of[...sources,transition.to])if(!states.has(state))add2("unknown_state",transition.key,`Transition "${transition.key}" names unknown state "${state}"`);for(let id of transition.form)if(!defined.has(id))add2("unknown_form_field",transition.key,`Transition "${transition.key}" asks for unknown field "${id}"`);if(transition.when!==void 0&&!defined.has(transition.when.field))add2("unknown_condition_field",transition.key,`Transition "${transition.key}" has a condition on unknown field "${transition.when.field}"`)}let flow=buildFlow(document,options);if(!flow.rules.some((rule)=>rule.from===null))add2("no_create_transition","","The flow has no transition that creates an item");for(let message of tableProblems(flow.table))add2("unusable_table","",message);return problems}function numberPeriod(format2,clock={}){if(!format2.yearly)return"";let year=new Intl.DateTimeFormat("en-US",{timeZone:clock.timeZone??"UTC",year:"numeric"}).formatToParts(clock.now??new Date).find((part)=>part.type==="year")?.value;if(year===void 0)throw RangeError("Could not read the year of the clock");return year.padStart(4,"0")}function formatNumber(format2,period,counter){if(!Number.isSafeInteger(counter)||counter<1)throw RangeError("A counter value is a positive integer");let separator=format2.separator??"-",padded=String(counter).padStart(format2.digits,"0");return[format2.prefix,period,padded].filter((part)=>part!=="").join(separator)}var NUMBER_COUNTER_TABLE="number_counters";function numberCounterTable(){return{table_name:NUMBER_COUNTER_TABLE,add_base_columns:!1,excluded_methods:["GET","POST","PUT","PATCH","DELETE","TOGGLE","VERIFICATION"],columns:[{name:"sequence",type:"varchar",length:128,notNull:!0},{name:"period",type:"varchar",length:16,notNull:!0,default:""},{name:"counter",type:"integer",notNull:!0,check:"counter >= 0"}],constraints:{unique:[{name:`${NUMBER_COUNTER_TABLE}_sequence_period_key`,columns:["sequence","period"]}]}}}var MAX_SEQUENCE_LENGTH=128;function assertSequenceKey(key2){if(key2===""||key2.length>MAX_SEQUENCE_LENGTH)throw RangeError(`A sequence key is 1 to ${MAX_SEQUENCE_LENGTH} characters`)}async function nextNumber(unit,sequence,clock={}){assertSequenceKey(sequence.key);let period=numberPeriod(sequence.format,clock),row=await unit.store.from(NUMBER_COUNTER_TABLE).upsert({conflict:{columns:["sequence","period"]},insert:{sequence:sequence.key,period,counter:1},set:{counter:{$inc:1}}});return{reference:formatNumber(sequence.format,period,row.counter),counter:row.counter,period}}async function raiseNumberCounter(unit,sequence,period,atLeast){if(!Number.isSafeInteger(atLeast)||atLeast<0)throw RangeError("A counter is raised to a non-negative integer");assertSequenceKey(sequence);let counters=unit.store.from(NUMBER_COUNTER_TABLE),row=await counters.upsert({conflict:{columns:["sequence","period"]},insert:{sequence,period,counter:atLeast},set:{counter:{$inc:0}}});if(row.counter>=atLeast)return row.counter;let[raised]=await counters.updateWhere({sequence,period,counter:{lt:atLeast}},{counter:atLeast});return raised?.counter??atLeast}export{writeTenantNotifications,writeTenantNotification,writeTenantAudit,visibleFieldIds,viewGroup,viewClaimOf,versionedDocumentTables,versionedDocumentImmutabilitySql,verifyUserPassword,validatePasswordStrength,validateNucleusConfig,validateFieldValues,validateFieldValue,validateFieldDefinitions,upper,unsafeExecutorOf,unitOfWorkFor,translate,toIndexEntries,tableProblems,tableExists,sum,sub,storeFromExecutor,statesOf,serve,safeRegExp,safeCast,runUnitOfWork,runRowView,runMigrations,runAggregateView,rulesOf,ruleFailure,round,resolveProfileSyncUpdates,replace,refreshTenantFeatures,refreshTenant,refreshAllTenants,readView,readMoney,readLedger,readDateRange,raiseNumberCounter,qualified,purgeTenant,purgeExpiredIdempotencyKeys,pruneFieldValues,provisionWithMigrations,profileSyncHooks,payloadHash,parseParams,parseFilterValue,param,ownedObjects,optionLabel,objectExists,numberPeriod,numberCounterTable,nucleusDataOf,now,nextNumber,min,migrationOwnedDropGuard,measure,max,lower,localize,lit,least,json,isTerminal,isTenantFeatureEnabled,isSystemActor,isStringList2 as isStringList,isRowView,isJsonObject2 as isJsonObject,isIndexed,isExpr,isEmptyValue,isCalendarDate,initialFieldValues,indexedFieldIds,indexColumnFor,hiddenFieldIds,hashPassword,hasEntityRules,greatest,getResolvedOptions2 as getResolvedOptions,formatNumber,formatConfigIssues,formErrors,flowProblems,fieldValuesSchema,fieldValueSchema,fieldDefinitionsSchema,fieldDefinitionSchema,failureCodeOf,evaluateCondition,evaluate,eraseUser,endUserSessions,encodeViewCursor,documentTransactionsOf,documentTableNames,documentLeaves,diffSeconds,diffDocuments,defineWebSocketRoute,defineViewRoute,defineRules,defineRoute,defineJobFor,defineJob,defineDocumentType,defineActionFor,defineAction,decodeViewCursor,decodeHeaderList,decideTransition,cursorValues,createViewBuilder,createUserAccount,createPgDocumentTransactions,createNucleusServer,createJobRunner,createEntityStore,createDocumentStore,createBootMigrations,countView,countRowView,countAggregateView,count,configureProfileSync,configureOAuthLinkAuthorization,configureAuthorizationDiscovery,concatWs,concat,computed,completeIdempotency,compileRowView,collectRoutes,col,codePointLength,coalesce,claimIdempotencyKey,checksumOf,caseWhen,canStartIn,canEnter,buildOpenApiDocument,buildNucleus,buildFlow,buildEntityRules,buildConfigViews,buildConfigView,bucket,bindDocumentStore,avg,allowedTransitions,allowedTargets,aggregateOf,add,actionGroup,WhereError,ViewParamError,ViewError,TenantPurgeRefusedError,StoreError,ScopeViolationError,SYSTEM_ACTOR_KINDS,RuleSet,RuleError,RESERVED_IDS,REFERENCE_PATTERN,NucleusTestApp,NUMBER_COUNTER_TABLE,MigrationFailedError,MigrationDefinitionError,MigrationChecksumError,MAX_VIEW_LIMIT,MAX_PREFIX_LENGTH,MAX_OPTIONS,MAX_FIELDS,LOCK_MODES,LENGTH_LIMITS,LEDGER_TABLE,IdempotencyConflictError,ID_PATTERN,IDEMPOTENCY_TABLE,FLOW_FAILURE_CODES,FIELD_PARTIES,FIELD_LOCALES,FIELD_KINDS,FIELD_ERROR_CODES,ExprError,EntityStore,EMAIL_PATTERN,DocumentUnreadableError,DEFINITION_ISSUE_CODES,DEFAULT_VIEW_LIMIT,DEFAULT_LOCK_TIMEOUT_MS,DEFAULT_ARRAY_IDENTITY,ConstraintError,CURRENCY_PATTERN,CONDITION_OPS,ActionError,AccountErasureError};
|
|
675
|
+
or entity_id::text = any (${ids}::text[])`),count6=typeof result==="object"&&result!==null?Reflect.get(result,"rowCount"):0;return typeof count6==="number"?count6:0}var log7=logger.scoped("auth.accountErasure"),ERASURE_REASON="Account erasure (KVKK/GDPR right to erasure)";async function plan(executor,schema3,userId,policy2,options){let planned=[],refused=[],foreignKeys=await userReferences(executor,schema3),declared=await declaredReferences(executor,schema3,declaredColumns(options),foreignKeys);for(let ref3 of[...foreignKeys,...declared]){if(ref3.table===AUDIT_TABLE)continue;let rows=await countReferences(executor,schema3,ref3,userId);if(rows===0)continue;let rule=ruleFor(policy2,ref3),name2=`${ref3.table}.${ref3.column}`;if(rule===void 0)refused.push(`${name2}: no rule`);else{let problem=problemOf(ref3,rule);if(problem===null)planned.push({ref:ref3,rule,rows});else refused.push(`${name2}: ${problem}`)}}if(refused.length>0)throw new AccountErasureError(`Erasure refused, references left unhandled: ${refused.join("; ")}`,refused.map((line)=>line.split(":")[0]??line));return planned}async function apply2(executor,schema3,userId,{ref:ref3,rule},summary){let table2=sql47`${sql47.identifier(schema3)}.${sql47.identifier(ref3.table)}`,column3=sql47.identifier(ref3.column),own=ref3.table==="users"?sql47` and id <> ${userId}`:sql47``,returning=ref3.hasId?sql47` returning id`:sql47``;if(rule==="delete"){let done=touchedOf(await executor.execute(sql47`delete from ${table2} where ${column3} = ${userId}${own}${returning}`),ref3.hasId);return summary.deleted[ref3.table]=(summary.deleted[ref3.table]??0)+done.count,done.ids}if(rule==="nullify"){let done=touchedOf(await executor.execute(sql47`update ${table2} set ${column3} = null where ${column3} = ${userId}${own}${returning}`),ref3.hasId);return summary.nullified[ref3.table]=(summary.nullified[ref3.table]??0)+done.count,[]}let rows=(summary.kept[ref3.table]?.rows??0)+await countReferences(executor,schema3,ref3,userId);return summary.kept[ref3.table]={rows,reason:rule.keep},[]}async function eraseUser(unit,userId,policy2,options={}){return assertKeepReasons(policy2),unit.withoutRules(ERASURE_REASON,()=>erase(unit,userId,policy2,options))}async function erase(unit,userId,policy2,options){let executor=executorOf2(unit),schema3=unit.schema,summary={sessions:await endUserSessions(unit,userId),deleted:{},nullified:{},kept:{},users:0,auditScrubbed:0},planned=await plan(executor,schema3,userId,policy2,options),deletedIds=[];for(let step of planned)deletedIds.push(...await apply2(executor,schema3,userId,step,summary));summary.auditScrubbed=await scrubAuditRows(executor,schema3,userId,deletedIds);let removed=await executor.execute(sql47`delete from ${sql47.identifier(schema3)}.users where id = ${userId}`);return summary.users=touchedOf(removed,!1).count,await unit.audit({entityName:"users",operation:"ERASE_USER",summary:"An account was erased.",severity:"info",category:"system",newValues:{...summary}}),log7.info("Account erased",{schema:schema3,...summary}),summary}init_hostPasswordCheck();init_hooks();init_linkAuthorization();init_profileSync();init_profileSyncHooks();import{sql as sql48}from"drizzle-orm";init_Logger2();init_schema();var log8=logger.scoped("tenant.purge"),PROTECTED_SCHEMAS=new Set(["public","information_schema"]);class TenantPurgeRefusedError extends Error{tenantId;status;constructor(tenantId,status){super(`Tenant ${tenantId} is ${status}: purging it needs force`);this.tenantId=tenantId;this.status=status;this.name="TenantPurgeRefusedError"}}function toRow(row){if(row===void 0)return null;return{subdomain:String(Reflect.get(row,"subdomain")),schemaName:String(Reflect.get(row,"schema_name")),status:String(Reflect.get(row,"status"))}}function assertDroppable(schemaName,mainSchema){if(validateIdentifier(schemaName),schemaName===mainSchema||PROTECTED_SCHEMAS.has(schemaName)||schemaName.startsWith("pg_"))throw Error(`Refusing to drop protected schema "${schemaName}"`)}async function purgeTenant(tenantId,options){let registry5=options.registry===void 0?currentRegistry():options.registry,done=(outcome2)=>{log8.info(outcome2.purged?"Tenant purged":"Tenant already purged",{tenantId})};if(options.unit!==void 0&&options.db!==void 0)throw Error("purgeTenant takes a db or a unit, not both");if(options.unit!==void 0){if(options.unit.schema!==options.mainSchema)throw Error(`purgeTenant joins a unit on the main schema "${options.mainSchema}", not "${options.unit.schema}"`);return options.unit.nested(async(inner)=>{let outcome2=await purgeIn(executorOf2(inner),inner.audit,tenantId,options,registry5);return inner.afterCommit(async()=>{await registry5?.forgetTenant(tenantId),done(outcome2)}),outcome2})}if(options.db===void 0)throw Error("purgeTenant needs a db or a unit");let outcome=await options.db.transaction((tx)=>purgeIn(tx,(entry)=>writeTenantAudit(tx,options.mainSchema,entry),tenantId,options,registry5));return await registry5?.forgetTenant(tenantId),done(outcome),outcome}async function purgeIn(tx,audit,tenantId,options,registry5){let main=sql48.identifier(validateIdentifier(options.mainSchema));await tx.execute(sql48`select pg_advisory_xact_lock(hashtext(${`tenant_purge:${tenantId}`}))`);let found=await tx.execute(sql48`select subdomain, schema_name, status from ${main}.tenants where id = ${tenantId} for update`),row=toRow(rowsOfResult(found)[0]);if(row===null){let leftover=registry5?.getTenantById(tenantId)?.schemaName;if(leftover!==void 0)assertDroppable(leftover,options.mainSchema),await tx.execute(sql48`drop schema if exists ${sql48.identifier(leftover)} cascade`);return{purged:!1,tenantId,alreadyPurged:!0}}if(row.status==="active"&&options.force!==!0)throw new TenantPurgeRefusedError(tenantId,row.status);return assertDroppable(row.schemaName,options.mainSchema),await audit({entityName:"tenants",entityId:tenantId,operation:"TENANT_PURGE",summary:`${row.subdomain} hard-deleted${options.reason?` (${options.reason})`:""}`,category:"admin",severity:"critical",oldValues:{subdomain:row.subdomain,schemaName:row.schemaName,status:row.status},newValues:{reason:options.reason??null,performedBy:options.performedBy??null}}),await tx.execute(sql48`drop schema if exists ${sql48.identifier(row.schemaName)} cascade`),await tx.execute(sql48`delete from ${main}.tenants where id = ${tenantId}`),{purged:!0,tenantId,subdomain:row.subdomain,schemaName:row.schemaName}}function formErrors(rule,fields,context){let merged={...context.item,...context.entered},checked=validateFieldValues(fields,merged,{party:context.actor.side}).errors,errors2=new Map;for(let id of Object.keys(context.entered))if(!rule.form.includes(id))errors2.set(id,"unknown_field");for(let id of rule.form){let code=Object.hasOwn(checked,id)?checked[id]:void 0;if(code===void 0)continue;if(Object.hasOwn(context.entered,id)&&!isEmptyValue(context.entered[id])||code==="required")errors2.set(id,code)}return Object.fromEntries(errors2)}var holdsRole=(rule,context)=>context.actor.roles.some((role)=>rule.roles.includes(role)),onForm=(rule)=>rule.when!==null&&rule.form.includes(rule.when.field),conditionFails=(rule,context)=>rule.when!==null&&!evaluateCondition(rule.when,{...context.item,...context.entered});function ruleFailure(rule,fields,context){if(rule.side!==context.actor.side)return{code:"transition_side_forbidden"};if(!holdsRole(rule,context))return{code:"transition_role_forbidden"};if(rule.onlyCreator&&!context.isCreator)return{code:"transition_creator_only"};if(!onForm(rule)&&conditionFails(rule,context))return{code:"transition_condition_not_met"};if(context.mode==="offer")return null;let fieldErrors=formErrors(rule,fields,context);if(Object.keys(fieldErrors).length>0)return{code:"transition_fields_invalid",fieldErrors};if(onForm(rule)&&conditionFails(rule,context))return{code:"transition_condition_not_met"};if(rule.requireNote&&(context.note??"").trim()==="")return{code:"transition_note_required"};return null}var FLOW_FAILURE_CODES=["transition_unknown","transition_unknown_state","transition_source_mismatch","transition_from_final","transition_start_forbidden","transition_side_forbidden","transition_role_forbidden","transition_creator_only","transition_condition_not_met","transition_fields_invalid","transition_note_required"];function failureCodeOf(message){return FLOW_FAILURE_CODES.find((code)=>code===message)??null}function rulesOf(document){return document.transitions.flatMap((transition)=>{let common={key:transition.key,to:transition.to,side:transition.side,roles:transition.roles,form:transition.form,requireNote:transition.requireNote,onlyCreator:transition.onlyCreator===!0,when:transition.when??null};return(transition.from==="create"?[null]:transition.from).map((from)=>({...common,from}))})}function edgesOf(rules,fields){let grouped=new Map;for(let rule of rules){if(rule.from===null)continue;let targets=grouped.get(rule.from)??new Map;targets.set(rule.to,[...targets.get(rule.to)??[],rule]),grouped.set(rule.from,targets)}let edges=new Map;for(let[from,targets]of grouped)edges.set(from,[...targets].map(([to,edgeRules])=>({to,guard:(context)=>{let rule=edgeRules.find((candidate)=>candidate.key===context.key);if(rule===void 0)return"transition_source_mismatch";return ruleFailure(rule,fields,context)?.code??!0}})));return edges}function buildFlow(document,options={}){let rules=rulesOf(document),fields=document.fields??[],edges=edgesOf(rules,fields),transitions=Object.fromEntries(document.states.map((state)=>[state.key,edges.get(state.key)??[]])),terminal=document.states.filter((state)=>state.terminal===!0||options.isTerminal?.(state)===!0).map((state)=>state.key),declared=new Set(document.states.map((state)=>state.key));return{table:{initial:[...new Set(rules.filter((rule)=>rule.from===null&&declared.has(rule.to)).map((rule)=>rule.to))],terminal,transitions},rules,fields}}var REFUSALS={unknown_state:"transition_unknown_state",terminal_state:"transition_from_final",no_transition:"transition_source_mismatch"};function ruleOf(flow,key2,from){let found=flow.rules.find((rule)=>rule.key===key2&&rule.from===from);if(found!==void 0)return found;return flow.rules.some((rule)=>rule.key===key2)?"transition_source_mismatch":"transition_unknown"}function judge2(flow,rule,context){if(rule.from===null){if(!canStartIn(flow.table,rule.to))return{ok:!1,code:"transition_start_forbidden"};let failure2=ruleFailure(rule,flow.fields,context);return failure2===null?{ok:!0,rule}:{ok:!1,...failure2}}if(!Object.hasOwn(flow.table.transitions,rule.to))return{ok:!1,code:"transition_unknown_state"};let evaluation=evaluate(flow.table,rule.from,rule.to,context);if(evaluation.allowed)return{ok:!0,rule};if(evaluation.reason!=="guard_rejected")return{ok:!1,code:REFUSALS[evaluation.reason]};let failure=ruleFailure(rule,flow.fields,context),code=failure?.code??failureCodeOf(evaluation.message);return code===null?{ok:!1,code:"transition_source_mismatch"}:{ok:!1,code,...failure?.fieldErrors?{fieldErrors:failure.fieldErrors}:{}}}function decideTransition(flow,attempt3){let rule=ruleOf(flow,attempt3.key,attempt3.from);if(typeof rule==="string")return{ok:!1,code:rule};return judge2(flow,rule,{...attempt3,mode:"perform"})}function allowedTransitions(flow,offer){return flow.rules.filter((rule)=>rule.from===offer.state&&ruleOf(flow,rule.key,rule.from)===rule&&judge2(flow,rule,{...offer,from:offer.state,key:rule.key,entered:{},mode:"offer"}).ok)}function flowProblems(document,options={}){let problems=[],add2=(code,subject,message)=>problems.push({code,subject,message}),states=new Set;for(let state of document.states){if(states.has(state.key))add2("duplicate_state",state.key,`State "${state.key}" is declared twice`);states.add(state.key)}let defined=new Set((document.fields??[]).map((field2)=>field2.id)),keys=new Set;for(let transition of document.transitions){if(keys.has(transition.key))add2("duplicate_transition",transition.key,`Transition "${transition.key}" is declared twice`);keys.add(transition.key);let sources=transition.from==="create"?[]:transition.from;if(transition.roles.length===0)add2("no_roles",transition.key,`Transition "${transition.key}" lists no role: nobody could make it`);if(transition.from!=="create"&&sources.length===0)add2("no_source",transition.key,`Transition "${transition.key}" starts from no state`);for(let state of[...sources,transition.to])if(!states.has(state))add2("unknown_state",transition.key,`Transition "${transition.key}" names unknown state "${state}"`);for(let id of transition.form)if(!defined.has(id))add2("unknown_form_field",transition.key,`Transition "${transition.key}" asks for unknown field "${id}"`);if(transition.when!==void 0&&!defined.has(transition.when.field))add2("unknown_condition_field",transition.key,`Transition "${transition.key}" has a condition on unknown field "${transition.when.field}"`)}let flow=buildFlow(document,options);if(!flow.rules.some((rule)=>rule.from===null))add2("no_create_transition","","The flow has no transition that creates an item");for(let message of tableProblems(flow.table))add2("unusable_table","",message);return problems}function numberPeriod(format2,clock={}){if(!format2.yearly)return"";let year=new Intl.DateTimeFormat("en-US",{timeZone:clock.timeZone??"UTC",year:"numeric"}).formatToParts(clock.now??new Date).find((part)=>part.type==="year")?.value;if(year===void 0)throw RangeError("Could not read the year of the clock");return year.padStart(4,"0")}function formatNumber(format2,period,counter){if(!Number.isSafeInteger(counter)||counter<1)throw RangeError("A counter value is a positive integer");let separator=format2.separator??"-",padded=String(counter).padStart(format2.digits,"0");return[format2.prefix,period,padded].filter((part)=>part!=="").join(separator)}var NUMBER_COUNTER_TABLE="number_counters";function numberCounterTable(){return{table_name:NUMBER_COUNTER_TABLE,add_base_columns:!1,excluded_methods:["GET","POST","PUT","PATCH","DELETE","TOGGLE","VERIFICATION"],columns:[{name:"sequence",type:"varchar",length:128,notNull:!0},{name:"period",type:"varchar",length:16,notNull:!0,default:""},{name:"counter",type:"integer",notNull:!0,check:"counter >= 0"}],constraints:{unique:[{name:`${NUMBER_COUNTER_TABLE}_sequence_period_key`,columns:["sequence","period"]}]}}}var MAX_SEQUENCE_LENGTH=128;function assertSequenceKey(key2){if(key2===""||key2.length>MAX_SEQUENCE_LENGTH)throw RangeError(`A sequence key is 1 to ${MAX_SEQUENCE_LENGTH} characters`)}async function nextNumber(unit,sequence,clock={}){assertSequenceKey(sequence.key);let period=numberPeriod(sequence.format,clock),row=await unit.store.from(NUMBER_COUNTER_TABLE).upsert({conflict:{columns:["sequence","period"]},insert:{sequence:sequence.key,period,counter:1},set:{counter:{$inc:1}}});return{reference:formatNumber(sequence.format,period,row.counter),counter:row.counter,period}}async function raiseNumberCounter(unit,sequence,period,atLeast){if(!Number.isSafeInteger(atLeast)||atLeast<0)throw RangeError("A counter is raised to a non-negative integer");assertSequenceKey(sequence);let counters=unit.store.from(NUMBER_COUNTER_TABLE),row=await counters.upsert({conflict:{columns:["sequence","period"]},insert:{sequence,period,counter:atLeast},set:{counter:{$inc:0}}});if(row.counter>=atLeast)return row.counter;let[raised]=await counters.updateWhere({sequence,period,counter:{lt:atLeast}},{counter:atLeast});return raised?.counter??atLeast}export{writeTenantNotifications,writeTenantNotification,writeTenantAudit,visibleFieldIds,viewGroup,viewClaimOf,versionedDocumentTables,versionedDocumentImmutabilitySql,verifyUserPassword,validatePasswordStrength,validateNucleusConfig,validateFieldValues,validateFieldValue,validateFieldDefinitions,upper,unsafeExecutorOf,unitOfWorkFor,translate,toIndexEntries,tableProblems,tableExists,sum,sub,storeFromExecutor,statesOf,serve,safeRegExp,safeCast,runUnitOfWork,runRowView,runMigrations,runAggregateView,rulesOf,ruleFailure,round,resolveProfileSyncUpdates,replace,refreshTenantFeatures,refreshTenant,refreshAllTenants,readView,readMoney,readLedger,readDateRange,raiseNumberCounter,qualified,purgeTenant,purgeExpiredIdempotencyKeys,pruneFieldValues,provisionWithMigrations,profileSyncHooks,payloadHash,parseParams,parseFilterValue,param,ownedObjects,optionLabel,objectExists,numberPeriod,numberCounterTable,nucleusDataOf,now,nextNumber,min,migrationOwnedDropGuard,measure,max,lower,localize,lit,least,json,isTerminal,isTenantFeatureEnabled,isSystemActor,isStringList2 as isStringList,isRowView,isJsonObject2 as isJsonObject,isIndexed,isExpr,isEmptyValue,isCalendarDate,initialFieldValues,indexedFieldIds,indexColumnFor,hiddenFieldIds,hashPassword,hasEntityRules,greatest,getResolvedOptions2 as getResolvedOptions,formatNumber,formatConfigIssues,formErrors,flowProblems,fieldValuesSchema,fieldValueSchema,fieldDefinitionsSchema,fieldDefinitionSchema,failureCodeOf,evaluateCondition,evaluate,eraseUser,endUserSessions,encodeViewCursor,documentTransactionsOf,documentTableNames,documentLeaves,diffSeconds,diffDocuments,defineWebSocketRoute,defineViewRoute,defineRules,defineRoute,defineJobFor,defineJob,defineDocumentType,defineActionFor,defineAction,decodeViewCursor,decodeHeaderList,decideTransition,cursorValues,createViewBuilder,createUserAccount,createPgDocumentTransactions,createNucleusServer,createJobRunner,createEntityStore,createDocumentStore,createBootMigrations,countView,countRowView,countAggregateView,count,configureProfileSync,configureOAuthLinkAuthorization,configureAuthorizationDiscovery,concatWs,concat,computed,completeIdempotency,compileRowView,collectRoutes,col,codePointLength,coalesce,claimIdempotencyKey,checksumOf,caseWhen,canStartIn,canEnter,buildOpenApiDocument,buildNucleus,buildFlow,buildEntityRules,buildConfigViews,buildConfigView,bucket,bindDocumentStore,avg,allowedTransitions,allowedTargets,aggregateOf,add,actionGroup,WhereError,ViewParamError,ViewError,TenantPurgeRefusedError,StoreError,ScopeViolationError,SYSTEM_ACTOR_KINDS,RuleSet,RuleError,RESERVED_IDS,REFERENCE_PATTERN,NucleusTestApp,NUMBER_COUNTER_TABLE,MigrationFailedError,MigrationDefinitionError,MigrationChecksumError,MAX_VIEW_LIMIT,MAX_PREFIX_LENGTH,MAX_OPTIONS,MAX_FIELDS,LOCK_MODES,LENGTH_LIMITS,LEDGER_TABLE,IdempotencyConflictError,ID_PATTERN,IDEMPOTENCY_TABLE,FLOW_FAILURE_CODES,FIELD_PARTIES,FIELD_LOCALES,FIELD_KINDS,FIELD_ERROR_CODES,ExprError,EntityStore,EMAIL_PATTERN,DocumentUnreadableError,DEFINITION_ISSUE_CODES,DEFAULT_VIEW_LIMIT,DEFAULT_LOCK_TIMEOUT_MS,DEFAULT_ARRAY_IDENTITY,ConstraintError,CURRENCY_PATTERN,CONDITION_OPS,ActionError,AccountErasureError};
|
|
@@ -1,8 +1,29 @@
|
|
|
1
|
-
import type { UnitDatabase } from '../../Data/unitTypes';
|
|
1
|
+
import type { AfterCommitCallback, UnitDatabase } from '../../Data/unitTypes';
|
|
2
|
+
import { type TenantAuditRow } from './hostWrites';
|
|
2
3
|
import type { TenantRegistry } from './TenantRegistry';
|
|
4
|
+
/** What the purge needs of the savepoint unit it runs in. */
|
|
5
|
+
interface PurgeInner {
|
|
6
|
+
readonly schema: string;
|
|
7
|
+
audit(entry: TenantAuditRow): Promise<void>;
|
|
8
|
+
afterCommit(callback: AfterCommitCallback): void;
|
|
9
|
+
}
|
|
10
|
+
/**
|
|
11
|
+
* A unit of work on the MAIN schema to purge inside (any `UnitOfWork`, a main-scope job's for one): the
|
|
12
|
+
* purge runs in a savepoint on the unit's own connection, its audit row is the unit's, and the registry
|
|
13
|
+
* forgets the tenant only after the unit's outermost commit.
|
|
14
|
+
*/
|
|
15
|
+
export interface PurgeUnit {
|
|
16
|
+
readonly schema: string;
|
|
17
|
+
nested<T>(work: (inner: PurgeInner) => Promise<T>): Promise<T>;
|
|
18
|
+
}
|
|
3
19
|
export interface PurgeTenantOptions {
|
|
4
|
-
/** The database the purge runs on (a drizzle `db`). */
|
|
5
|
-
db
|
|
20
|
+
/** The database the purge runs on (a drizzle `db`): the purge is its own transaction. */
|
|
21
|
+
db?: UnitDatabase;
|
|
22
|
+
/**
|
|
23
|
+
* Or the unit of work it joins (a job's unit, a request's unit): no second pool connection, and the
|
|
24
|
+
* purge commits or rolls back with the unit. Exactly one of `db` and `unit`.
|
|
25
|
+
*/
|
|
26
|
+
unit?: PurgeUnit;
|
|
6
27
|
/** The main (control-plane) schema holding `tenants`, `tenant_features` and the platform `audit_logs`. */
|
|
7
28
|
mainSchema: string;
|
|
8
29
|
/** The registry to forget the tenant in. Default: the registry of this process (none: nothing to forget). */
|
|
@@ -33,7 +54,9 @@ export declare class TenantPurgeRefusedError extends Error {
|
|
|
33
54
|
constructor(tenantId: string, status: string);
|
|
34
55
|
}
|
|
35
56
|
/**
|
|
36
|
-
* Hard-deletes one tenant, in ONE transaction
|
|
57
|
+
* Hard-deletes one tenant, in ONE transaction (its own on `db`, or a savepoint of the caller's `unit`,
|
|
58
|
+
* which then needs no second pool connection and commits or rolls back the purge with its own work):
|
|
59
|
+
* its schema (`drop schema ... cascade`), its main-schema
|
|
37
60
|
* rows (`tenants`, which cascades `tenant_features`, `tenant_events`, ...) and a `TENANT_PURGE` row in
|
|
38
61
|
* the main schema's `audit_logs`, which outlives the tenant. After the commit the registry forgets the
|
|
39
62
|
* tenant (indices, schema context, hostnames, features, Redis resolution cache), so its host answers
|
|
@@ -46,3 +69,4 @@ export declare class TenantPurgeRefusedError extends Error {
|
|
|
46
69
|
* - Never drops the main schema, `public`, `information_schema` or a `pg_*` schema.
|
|
47
70
|
*/
|
|
48
71
|
export declare function purgeTenant(tenantId: string, options: PurgeTenantOptions): Promise<PurgeTenantOutcome>;
|
|
72
|
+
export {};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "nucleus-core-ts",
|
|
3
|
-
"version": "0.10.
|
|
3
|
+
"version": "0.10.192",
|
|
4
4
|
"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
|
|
5
5
|
"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
|
|
6
6
|
"license": "SEE LICENSE IN LICENSE",
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
import { afterAll, describe, expect, test } from 'bun:test'
|
|
2
|
+
import { existsSync, mkdtempSync, rmSync } from 'node:fs'
|
|
3
|
+
import { tmpdir } from 'node:os'
|
|
4
|
+
import { join } from 'node:path'
|
|
5
|
+
import { createFixtureServer } from '../fixtures'
|
|
6
|
+
import { captureRun } from '.'
|
|
7
|
+
|
|
8
|
+
const PAGE = `<!doctype html><meta charset="utf-8"><body style="margin:0;font:16px sans-serif">
|
|
9
|
+
<h1 id="title" style="position:absolute;left:20px;top:30px;width:200px;height:40px;margin:0">Start</h1>
|
|
10
|
+
<button id="go" onclick="document.getElementById('title').textContent='Done'">Go</button></body>`
|
|
11
|
+
|
|
12
|
+
const site = createFixtureServer({
|
|
13
|
+
routes: [
|
|
14
|
+
{ path: '/', respond: () => new Response(PAGE, { headers: { 'content-type': 'text/html' } }) },
|
|
15
|
+
],
|
|
16
|
+
})
|
|
17
|
+
const outDir = join(mkdtempSync(join(tmpdir(), 'nucleus-capture-test-')), 'run')
|
|
18
|
+
afterAll(async () => {
|
|
19
|
+
await site.stop()
|
|
20
|
+
rmSync(join(outDir, '..'), { recursive: true, force: true })
|
|
21
|
+
})
|
|
22
|
+
|
|
23
|
+
describe('captureRun', () => {
|
|
24
|
+
test('drives the page, writes the frames and a timeline the kit can play', async () => {
|
|
25
|
+
const result = await captureRun({
|
|
26
|
+
outDir,
|
|
27
|
+
locale: 'en',
|
|
28
|
+
theme: 'light',
|
|
29
|
+
format: 'png',
|
|
30
|
+
roles: { desk: { viewport: { width: 320, height: 200, scale: 2 }, url: `${site.origin}/` } },
|
|
31
|
+
scenario: async (director) => {
|
|
32
|
+
await director.settle('desk')
|
|
33
|
+
await director.snap({
|
|
34
|
+
caption: { en: 'Before' },
|
|
35
|
+
focus: 'desk',
|
|
36
|
+
seconds: 2,
|
|
37
|
+
highlight: { desk: '#title' },
|
|
38
|
+
})
|
|
39
|
+
await director.page('desk').click('#go')
|
|
40
|
+
await director.burst({
|
|
41
|
+
caption: { en: 'After' },
|
|
42
|
+
focus: 'desk',
|
|
43
|
+
seconds: 2,
|
|
44
|
+
count: 2,
|
|
45
|
+
everyMs: 10,
|
|
46
|
+
})
|
|
47
|
+
},
|
|
48
|
+
})
|
|
49
|
+
const { timeline } = result
|
|
50
|
+
expect(timeline.version).toBe(1)
|
|
51
|
+
expect(timeline.viewports.desk).toEqual({ width: 320, height: 200, scale: 2 })
|
|
52
|
+
expect(timeline.beats.map((beat) => beat.id)).toEqual(['b01', 'b02', 'b03'])
|
|
53
|
+
expect(timeline.beats[0]?.frames.desk?.highlight).toEqual({ x: 20, y: 30, w: 200, h: 40 })
|
|
54
|
+
expect(timeline.beats[1]?.seconds).toBe(1)
|
|
55
|
+
expect(result.frames).toBe(3)
|
|
56
|
+
expect(existsSync(join(outDir, 'frames', 'b01-desk.png'))).toBe(true)
|
|
57
|
+
expect(existsSync(result.timelinePath)).toBe(true)
|
|
58
|
+
}, 60_000)
|
|
59
|
+
|
|
60
|
+
test('a scenario that takes no beat writes no timeline', async () => {
|
|
61
|
+
const empty = join(outDir, '..', 'empty')
|
|
62
|
+
await expect(
|
|
63
|
+
captureRun({
|
|
64
|
+
outDir: empty,
|
|
65
|
+
locale: 'en',
|
|
66
|
+
theme: 'dark',
|
|
67
|
+
roles: { desk: { viewport: { width: 100, height: 100, scale: 1 } } },
|
|
68
|
+
scenario: async () => undefined,
|
|
69
|
+
})
|
|
70
|
+
).rejects.toThrow('The scenario took no beats')
|
|
71
|
+
expect(existsSync(join(empty, 'timeline.json'))).toBe(false)
|
|
72
|
+
}, 60_000)
|
|
73
|
+
})
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
import { mkdirSync, rmSync, writeFileSync } from 'node:fs'
|
|
2
|
+
import { join } from 'node:path'
|
|
3
|
+
import puppeteer, { type Browser, type Page } from 'puppeteer-core'
|
|
4
|
+
import type { DemoBeat, DemoTimeline } from '../../../fe/components/DemoFilm/_types'
|
|
5
|
+
import { resolveChromePath } from '../chrome'
|
|
6
|
+
import { createDirector } from './director'
|
|
7
|
+
import type { CaptureRole, CaptureRunOptions, CaptureRunResult } from './types'
|
|
8
|
+
|
|
9
|
+
function launch(executablePath: string, headed: boolean): Promise<Browser> {
|
|
10
|
+
return puppeteer.launch({
|
|
11
|
+
executablePath,
|
|
12
|
+
headless: !headed,
|
|
13
|
+
args: [
|
|
14
|
+
'--no-first-run',
|
|
15
|
+
'--hide-scrollbars',
|
|
16
|
+
'--force-color-profile=srgb',
|
|
17
|
+
'--disable-renderer-backgrounding',
|
|
18
|
+
'--disable-background-timer-throttling',
|
|
19
|
+
'--disable-backgrounding-occluded-windows',
|
|
20
|
+
],
|
|
21
|
+
})
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** True when every role has a value: narrows the partial map without a cast. */
|
|
25
|
+
function isComplete<Role extends string, T>(
|
|
26
|
+
roles: readonly Role[],
|
|
27
|
+
map: Partial<Record<Role, T>>
|
|
28
|
+
): map is Record<Role, T> {
|
|
29
|
+
return roles.every((role) => map[role] !== undefined)
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** One window per role (a tab behind another is hidden and stops painting). */
|
|
33
|
+
async function openRole<Role extends string>(
|
|
34
|
+
browser: Browser,
|
|
35
|
+
role: Role,
|
|
36
|
+
spec: CaptureRole,
|
|
37
|
+
options: CaptureRunOptions<Role>
|
|
38
|
+
): Promise<Page> {
|
|
39
|
+
const page = await (await browser.createBrowserContext()).newPage()
|
|
40
|
+
page.on('pageerror', (error) => {
|
|
41
|
+
console.error(`[capture:${role}] ${error instanceof Error ? error.message : String(error)}`)
|
|
42
|
+
})
|
|
43
|
+
const { width, height, scale } = spec.viewport
|
|
44
|
+
await page.setViewport({ width, height, deviceScaleFactor: scale })
|
|
45
|
+
await page.emulateMediaFeatures([
|
|
46
|
+
{ name: 'prefers-color-scheme', value: options.colorScheme ?? options.theme },
|
|
47
|
+
])
|
|
48
|
+
if (options.preload !== undefined) await page.evaluateOnNewDocument(options.preload)
|
|
49
|
+
const cookies = options.cookies?.[role] ?? []
|
|
50
|
+
if (cookies.length > 0) await page.browserContext().setCookie(...cookies)
|
|
51
|
+
if (spec.url !== undefined) await page.goto(spec.url, { waitUntil: 'domcontentloaded' })
|
|
52
|
+
return page
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Captures a demo run from the real product: opens a page per role in headless Chrome, hands the
|
|
57
|
+
* scenario a director that drives the pages and takes beats, and writes `frames/` and a
|
|
58
|
+
* `timeline.json` the DemoFilm kit plays and `renderFilm` encodes. A scenario that throws stops the
|
|
59
|
+
* run and writes no timeline, so a film is only ever made from a run that went through.
|
|
60
|
+
*/
|
|
61
|
+
export async function captureRun<Role extends string>(
|
|
62
|
+
options: CaptureRunOptions<Role>
|
|
63
|
+
): Promise<CaptureRunResult<Role>> {
|
|
64
|
+
const started = performance.now()
|
|
65
|
+
const framesDir = join(options.outDir, 'frames')
|
|
66
|
+
rmSync(options.outDir, { recursive: true, force: true })
|
|
67
|
+
mkdirSync(framesDir, { recursive: true })
|
|
68
|
+
const browser = await launch(resolveChromePath(options.chromePath), options.headed === true)
|
|
69
|
+
const beats: DemoBeat<Role>[] = []
|
|
70
|
+
let frames = 0
|
|
71
|
+
const roleNames = Object.keys(options.roles).filter((name): name is Role => name in options.roles)
|
|
72
|
+
try {
|
|
73
|
+
const pages = new Map<Role, Page>()
|
|
74
|
+
for (const role of roleNames)
|
|
75
|
+
pages.set(role, await openRole(browser, role, options.roles[role], options))
|
|
76
|
+
const director = createDirector({
|
|
77
|
+
pages,
|
|
78
|
+
framesDir,
|
|
79
|
+
format: options.format ?? 'webp',
|
|
80
|
+
quality: options.quality ?? 92,
|
|
81
|
+
beats,
|
|
82
|
+
onFrame: () => {
|
|
83
|
+
frames += 1
|
|
84
|
+
},
|
|
85
|
+
})
|
|
86
|
+
await options.scenario(director)
|
|
87
|
+
} finally {
|
|
88
|
+
await browser.close().catch(() => undefined)
|
|
89
|
+
}
|
|
90
|
+
if (beats.length === 0) throw new Error('The scenario took no beats')
|
|
91
|
+
const viewports: Partial<Record<Role, CaptureRole['viewport']>> = {}
|
|
92
|
+
for (const role of roleNames) viewports[role] = options.roles[role].viewport
|
|
93
|
+
if (!isComplete(roleNames, viewports)) throw new Error('A role has no viewport')
|
|
94
|
+
const timeline: DemoTimeline<Role> = {
|
|
95
|
+
version: 1,
|
|
96
|
+
locale: options.locale,
|
|
97
|
+
theme: options.theme,
|
|
98
|
+
...(options.fixture === true ? { fixture: true } : {}),
|
|
99
|
+
recordedAt: new Date().toISOString(),
|
|
100
|
+
viewports,
|
|
101
|
+
beats,
|
|
102
|
+
}
|
|
103
|
+
const timelinePath = join(options.outDir, 'timeline.json')
|
|
104
|
+
writeFileSync(timelinePath, `${JSON.stringify(timeline, null, 2)}\n`)
|
|
105
|
+
return { timelinePath, timeline, frames, seconds: (performance.now() - started) / 1000 }
|
|
106
|
+
}
|
|
@@ -0,0 +1,110 @@
|
|
|
1
|
+
import { join } from 'node:path'
|
|
2
|
+
import type { Page } from 'puppeteer-core'
|
|
3
|
+
import type { DemoBeat, DemoBox, DemoFrame } from '../../../fe/components/DemoFilm/_types'
|
|
4
|
+
import type { BurstOptions, CaptureFormat, Director, SettleOptions, SnapOptions } from './types'
|
|
5
|
+
|
|
6
|
+
interface DirectorSetup<Role extends string> {
|
|
7
|
+
pages: ReadonlyMap<Role, Page>
|
|
8
|
+
framesDir: string
|
|
9
|
+
format: CaptureFormat
|
|
10
|
+
quality: number
|
|
11
|
+
beats: DemoBeat<Role>[]
|
|
12
|
+
onFrame: () => void
|
|
13
|
+
}
|
|
14
|
+
|
|
15
|
+
const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
|
|
16
|
+
|
|
17
|
+
/** The next free `bNN` id after the beats taken so far. */
|
|
18
|
+
function nextId(beats: readonly DemoBeat<string>[]): string {
|
|
19
|
+
return `b${String(beats.length + 1).padStart(2, '0')}`
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
/** A selector's box on screen in CSS pixels, or the box given; a selector that matches nothing is a scenario bug and throws. */
|
|
23
|
+
async function boxOf(page: Page, target: string | DemoBox): Promise<DemoBox | null> {
|
|
24
|
+
if (typeof target !== 'string') return target
|
|
25
|
+
const element = await page.$(target)
|
|
26
|
+
if (element === null) throw new Error(`Highlight selector matched nothing: ${target}`)
|
|
27
|
+
const box = await element.boundingBox()
|
|
28
|
+
await element.dispose()
|
|
29
|
+
return box === null ? null : { x: box.x, y: box.y, w: box.width, h: box.height }
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* The camera a scenario holds: a page per role, a settle that waits for a still screen, and snaps
|
|
34
|
+
* that write each role's screen into `frames/` and record the beat for the timeline.
|
|
35
|
+
*/
|
|
36
|
+
export function createDirector<Role extends string>(setup: DirectorSetup<Role>): Director<Role> {
|
|
37
|
+
const { pages, framesDir, format, quality, beats, onFrame } = setup
|
|
38
|
+
|
|
39
|
+
const page = (role: Role): Page => {
|
|
40
|
+
const found = pages.get(role)
|
|
41
|
+
if (found === undefined) throw new Error(`No page for role ${role}`)
|
|
42
|
+
return found
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
const settle = async (role: Role, options: SettleOptions = {}): Promise<void> => {
|
|
46
|
+
const target = page(role)
|
|
47
|
+
await target
|
|
48
|
+
.waitForNetworkIdle({ idleTime: options.idleMs ?? 400, timeout: options.timeoutMs ?? 6000 })
|
|
49
|
+
.catch(() => undefined)
|
|
50
|
+
await target.evaluate(async () => {
|
|
51
|
+
await document.fonts.ready
|
|
52
|
+
await new Promise<void>((done) =>
|
|
53
|
+
requestAnimationFrame(() => requestAnimationFrame(() => done()))
|
|
54
|
+
)
|
|
55
|
+
})
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
const capture = async (
|
|
59
|
+
id: string,
|
|
60
|
+
role: Role,
|
|
61
|
+
highlight: string | DemoBox | undefined
|
|
62
|
+
): Promise<DemoFrame> => {
|
|
63
|
+
const name = `${id}-${role}.${format}`
|
|
64
|
+
await page(role).screenshot({
|
|
65
|
+
path: join(framesDir, name),
|
|
66
|
+
type: format,
|
|
67
|
+
...(format === 'png' ? {} : { quality }),
|
|
68
|
+
})
|
|
69
|
+
onFrame()
|
|
70
|
+
return {
|
|
71
|
+
image: `frames/${name}`,
|
|
72
|
+
highlight: highlight === undefined ? null : await boxOf(page(role), highlight),
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
const snap = async (options: SnapOptions<Role>): Promise<string> => {
|
|
77
|
+
const id = options.id ?? nextId(beats)
|
|
78
|
+
if (beats.some((beat) => beat.id === id)) throw new Error(`Beat id ${id} is taken`)
|
|
79
|
+
const roles = options.roles ?? [options.focus]
|
|
80
|
+
const frames: Partial<Record<Role, DemoFrame>> = {}
|
|
81
|
+
for (const role of roles) frames[role] = await capture(id, role, options.highlight?.[role])
|
|
82
|
+
beats.push({
|
|
83
|
+
id,
|
|
84
|
+
caption: options.caption,
|
|
85
|
+
frames,
|
|
86
|
+
focus: options.focus,
|
|
87
|
+
seconds: options.seconds,
|
|
88
|
+
})
|
|
89
|
+
return id
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
const burst = async (options: BurstOptions<Role>): Promise<string[]> => {
|
|
93
|
+
if (options.count < 1) throw new Error('A burst needs at least one beat')
|
|
94
|
+
const ids: string[] = []
|
|
95
|
+
for (let index = 0; index < options.count; index += 1) {
|
|
96
|
+
if (index > 0) await sleep(options.everyMs)
|
|
97
|
+
ids.push(
|
|
98
|
+
await snap({
|
|
99
|
+
caption: options.caption,
|
|
100
|
+
focus: options.focus,
|
|
101
|
+
seconds: options.seconds / options.count,
|
|
102
|
+
highlight: index === options.count - 1 ? options.highlight : undefined,
|
|
103
|
+
})
|
|
104
|
+
)
|
|
105
|
+
}
|
|
106
|
+
return ids
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
return { page, settle, snap, burst, wait: sleep }
|
|
110
|
+
}
|
|
@@ -0,0 +1,102 @@
|
|
|
1
|
+
import type { Page } from 'puppeteer-core'
|
|
2
|
+
import type {
|
|
3
|
+
DemoBox,
|
|
4
|
+
DemoText,
|
|
5
|
+
DemoTheme,
|
|
6
|
+
DemoTimeline,
|
|
7
|
+
DemoViewport,
|
|
8
|
+
} from '../../../fe/components/DemoFilm/_types'
|
|
9
|
+
|
|
10
|
+
/** One role of a run: the screen size it is captured at and where its page opens. */
|
|
11
|
+
export interface CaptureRole {
|
|
12
|
+
viewport: DemoViewport
|
|
13
|
+
/** Opened before the scenario starts; the scenario may navigate anywhere after. */
|
|
14
|
+
url?: string
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** A cookie set on a role's page before its first navigation. */
|
|
18
|
+
export interface CaptureCookie {
|
|
19
|
+
name: string
|
|
20
|
+
value: string
|
|
21
|
+
/** The host the cookie belongs to, e.g. `localhost`. */
|
|
22
|
+
domain: string
|
|
23
|
+
path?: string
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** One beat of the film: what to say, whose screen to show, what to capture and ring. */
|
|
27
|
+
export interface SnapOptions<Role extends string> {
|
|
28
|
+
/** Stable id `b01`..`b99`; the next free one when left out. */
|
|
29
|
+
id?: string
|
|
30
|
+
caption: DemoText
|
|
31
|
+
/** The role the film shows for this beat. */
|
|
32
|
+
focus: Role
|
|
33
|
+
/** Seconds the film spends on this beat. */
|
|
34
|
+
seconds: number
|
|
35
|
+
/** Roles whose screen is captured now; only the focus when left out. */
|
|
36
|
+
roles?: Role[]
|
|
37
|
+
/** A CSS selector (its box on screen) or a box, per role, ringed in this beat. */
|
|
38
|
+
highlight?: Partial<Record<Role, string | DemoBox>>
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** Several beats of one role a short time apart: text streaming in, a clock, a progress bar. */
|
|
42
|
+
export interface BurstOptions<Role extends string> extends Omit<SnapOptions<Role>, 'id' | 'roles'> {
|
|
43
|
+
/** Beats to take; the burst's `seconds` are split evenly over them. */
|
|
44
|
+
count: number
|
|
45
|
+
/** Real time between two captures, in milliseconds. */
|
|
46
|
+
everyMs: number
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export interface SettleOptions {
|
|
50
|
+
/** Network quiet for this long counts as idle; 400 ms by default. */
|
|
51
|
+
idleMs?: number
|
|
52
|
+
/** Gives up waiting for idle after this long (an open stream never idles); 6 s by default. */
|
|
53
|
+
timeoutMs?: number
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** What a scenario drives: one page per role, and the camera. */
|
|
57
|
+
export interface Director<Role extends string> {
|
|
58
|
+
page: (role: Role) => Page
|
|
59
|
+
/** Waits for the network to go quiet, the fonts and two painted frames: a still screen. */
|
|
60
|
+
settle: (role: Role, options?: SettleOptions) => Promise<void>
|
|
61
|
+
/** Captures the beat's roles and records the beat; returns its id. */
|
|
62
|
+
snap: (options: SnapOptions<Role>) => Promise<string>
|
|
63
|
+
/** Captures `count` beats of the focus role, `everyMs` apart; returns their ids. */
|
|
64
|
+
burst: (options: BurstOptions<Role>) => Promise<string[]>
|
|
65
|
+
/** Real time passing between two actions, in milliseconds. */
|
|
66
|
+
wait: (ms: number) => Promise<void>
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
export type CaptureFormat = 'webp' | 'png' | 'jpeg'
|
|
70
|
+
|
|
71
|
+
export interface CaptureRunOptions<Role extends string> {
|
|
72
|
+
/** The run folder: cleared, then `frames/` and `timeline.json` are written into it. */
|
|
73
|
+
outDir: string
|
|
74
|
+
roles: Record<Role, CaptureRole>
|
|
75
|
+
/** Caption language the film starts in. */
|
|
76
|
+
locale: string
|
|
77
|
+
theme: DemoTheme
|
|
78
|
+
/** Drives the product and takes the beats, in order. */
|
|
79
|
+
scenario: (director: Director<Role>) => Promise<void>
|
|
80
|
+
/** `webp` by default. */
|
|
81
|
+
format?: CaptureFormat
|
|
82
|
+
/** 0-100 for webp and jpeg; 92 by default. */
|
|
83
|
+
quality?: number
|
|
84
|
+
chromePath?: string
|
|
85
|
+
cookies?: Partial<Record<Role, CaptureCookie[]>>
|
|
86
|
+
/** Script run before the page's own on every navigation (a fixed clock, a theme switch). */
|
|
87
|
+
preload?: string
|
|
88
|
+
/** The `prefers-color-scheme` the pages see; follows `theme` when left out. */
|
|
89
|
+
colorScheme?: DemoTheme
|
|
90
|
+
/** Shows the browser windows while capturing, for writing a scenario. */
|
|
91
|
+
headed?: boolean
|
|
92
|
+
/** Marks the run as a placeholder a public page must not show. */
|
|
93
|
+
fixture?: boolean
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
export interface CaptureRunResult<Role extends string> {
|
|
97
|
+
timelinePath: string
|
|
98
|
+
timeline: DemoTimeline<Role>
|
|
99
|
+
/** Files written under `frames/`. */
|
|
100
|
+
frames: number
|
|
101
|
+
seconds: number
|
|
102
|
+
}
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
import { afterAll, describe, expect, test } from 'bun:test'
|
|
2
|
+
import { createFixtureServer, matchPath, sseFrame } from '.'
|
|
3
|
+
|
|
4
|
+
describe('matchPath', () => {
|
|
5
|
+
test('named segments become params', () => {
|
|
6
|
+
expect(
|
|
7
|
+
matchPath('/llm/api/v1/conversations/:id/messages', '/llm/api/v1/conversations/c-7/messages')
|
|
8
|
+
).toEqual({ id: 'c-7' })
|
|
9
|
+
})
|
|
10
|
+
test('a different length or literal does not match', () => {
|
|
11
|
+
expect(matchPath('/a/:b', '/a')).toBeNull()
|
|
12
|
+
expect(matchPath('/a/b', '/a/c')).toBeNull()
|
|
13
|
+
})
|
|
14
|
+
test('a trailing * takes the rest of the path', () => {
|
|
15
|
+
expect(matchPath('/cdn/*', '/cdn/x/y.png')).toEqual({ '*': 'x/y.png' })
|
|
16
|
+
})
|
|
17
|
+
test('a RegExp hands over its named groups', () => {
|
|
18
|
+
expect(matchPath(/^\/agents\/(?<id>[^/]+)$/, '/agents/a1')).toEqual({ id: 'a1' })
|
|
19
|
+
})
|
|
20
|
+
})
|
|
21
|
+
|
|
22
|
+
describe('sseFrame', () => {
|
|
23
|
+
test('JSON data, event and id in wire order', () => {
|
|
24
|
+
expect(sseFrame({ data: { a: 1 }, event: 'chunk', id: '3' })).toBe(
|
|
25
|
+
'event: chunk\nid: 3\ndata: {"a":1}\n\n'
|
|
26
|
+
)
|
|
27
|
+
})
|
|
28
|
+
test('a multi-line string becomes one data line per line', () => {
|
|
29
|
+
expect(sseFrame({ data: 'x\ny' })).toBe('data: x\ndata: y\n\n')
|
|
30
|
+
})
|
|
31
|
+
})
|
|
32
|
+
|
|
33
|
+
describe('createFixtureServer', () => {
|
|
34
|
+
const server = createFixtureServer({
|
|
35
|
+
routes: [
|
|
36
|
+
{ path: '/me', json: { id: 'u1', name: 'Demo' } },
|
|
37
|
+
{
|
|
38
|
+
method: 'POST',
|
|
39
|
+
path: '/echo/:id',
|
|
40
|
+
json: async (c) => ({ id: c.params.id ?? '', body: await c.text() }),
|
|
41
|
+
},
|
|
42
|
+
{ path: '/stream', sse: { events: [{ data: { n: 1 } }, { data: { n: 2 }, delayMs: 20 }] } },
|
|
43
|
+
],
|
|
44
|
+
})
|
|
45
|
+
afterAll(() => server.stop())
|
|
46
|
+
|
|
47
|
+
test('answers JSON and dynamic JSON with params and body', async () => {
|
|
48
|
+
expect(await (await fetch(`${server.origin}/me`)).json()).toEqual({ id: 'u1', name: 'Demo' })
|
|
49
|
+
const echoed = await fetch(`${server.origin}/echo/42`, { method: 'POST', body: 'hi' })
|
|
50
|
+
expect(await echoed.json()).toEqual({ id: '42', body: 'hi' })
|
|
51
|
+
})
|
|
52
|
+
|
|
53
|
+
test('plays an SSE script in order', async () => {
|
|
54
|
+
const response = await fetch(`${server.origin}/stream`)
|
|
55
|
+
expect(response.headers.get('content-type')).toBe('text/event-stream')
|
|
56
|
+
expect(await response.text()).toBe('data: {"n":1}\n\ndata: {"n":2}\n\n')
|
|
57
|
+
})
|
|
58
|
+
|
|
59
|
+
test('records what no route answers, and answers CORS', async () => {
|
|
60
|
+
const missing = await fetch(`${server.origin}/nowhere?x=1`)
|
|
61
|
+
expect(missing.status).toBe(404)
|
|
62
|
+
expect(missing.headers.get('access-control-allow-origin')).toBe('*')
|
|
63
|
+
expect(server.unmatched()).toEqual([{ method: 'GET', path: '/nowhere', status: 404 }])
|
|
64
|
+
expect(server.hits().map((hit) => hit.path)).toContain('/me')
|
|
65
|
+
})
|
|
66
|
+
})
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export { findRoute, matchPath } from './match'
|
|
2
|
+
export { createFixtureServer } from './server'
|
|
3
|
+
export { sseFrame, sseResponse } from './sse'
|
|
4
|
+
export type {
|
|
5
|
+
FixtureContext,
|
|
6
|
+
FixtureRequestRecord,
|
|
7
|
+
FixtureRoute,
|
|
8
|
+
FixtureServer,
|
|
9
|
+
FixtureServerOptions,
|
|
10
|
+
JsonValue,
|
|
11
|
+
SseEvent,
|
|
12
|
+
SseScript,
|
|
13
|
+
} from './types'
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
import type { FixtureRoute } from './types'
|
|
2
|
+
|
|
3
|
+
/** The params a route's path takes from `path`, or null when it does not match. */
|
|
4
|
+
export function matchPath(pattern: string | RegExp, path: string): Record<string, string> | null {
|
|
5
|
+
if (pattern instanceof RegExp) {
|
|
6
|
+
const found = pattern.exec(path)
|
|
7
|
+
if (found === null) return null
|
|
8
|
+
const params: Record<string, string> = {}
|
|
9
|
+
for (const [name, value] of Object.entries(found.groups ?? {})) {
|
|
10
|
+
if (value !== undefined) params[name] = value
|
|
11
|
+
}
|
|
12
|
+
return params
|
|
13
|
+
}
|
|
14
|
+
const want = pattern.split('/').filter(Boolean)
|
|
15
|
+
const have = path.split('/').filter(Boolean)
|
|
16
|
+
const rest = want.at(-1) === '*'
|
|
17
|
+
if (rest ? have.length < want.length - 1 : have.length !== want.length) return null
|
|
18
|
+
const params: Record<string, string> = {}
|
|
19
|
+
for (let index = 0; index < want.length; index += 1) {
|
|
20
|
+
const segment = want[index]
|
|
21
|
+
if (segment === '*' && index === want.length - 1) {
|
|
22
|
+
params['*'] = have.slice(index).join('/')
|
|
23
|
+
return params
|
|
24
|
+
}
|
|
25
|
+
const value = have[index]
|
|
26
|
+
if (segment === undefined || value === undefined) return null
|
|
27
|
+
if (segment.startsWith(':')) params[segment.slice(1)] = decodeURIComponent(value)
|
|
28
|
+
else if (segment !== value) return null
|
|
29
|
+
}
|
|
30
|
+
return params
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** The first route that answers `method` on `path`, with its params. */
|
|
34
|
+
export function findRoute(
|
|
35
|
+
routes: readonly FixtureRoute[],
|
|
36
|
+
method: string,
|
|
37
|
+
path: string
|
|
38
|
+
): { route: FixtureRoute; params: Record<string, string> } | null {
|
|
39
|
+
for (const route of routes) {
|
|
40
|
+
const wanted = (route.method ?? 'GET').toUpperCase()
|
|
41
|
+
if (wanted !== '*' && wanted !== method.toUpperCase()) continue
|
|
42
|
+
const params = matchPath(route.path, path)
|
|
43
|
+
if (params !== null) return { route, params }
|
|
44
|
+
}
|
|
45
|
+
return null
|
|
46
|
+
}
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
import { findRoute } from './match'
|
|
2
|
+
import { sseResponse } from './sse'
|
|
3
|
+
import type {
|
|
4
|
+
FixtureContext,
|
|
5
|
+
FixtureRequestRecord,
|
|
6
|
+
FixtureRoute,
|
|
7
|
+
FixtureServer,
|
|
8
|
+
FixtureServerOptions,
|
|
9
|
+
} from './types'
|
|
10
|
+
|
|
11
|
+
const CORS: Record<string, string> = {
|
|
12
|
+
'access-control-allow-origin': '*',
|
|
13
|
+
'access-control-allow-methods': 'GET, POST, PUT, PATCH, DELETE, OPTIONS',
|
|
14
|
+
'access-control-allow-headers': '*',
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
async function answer(
|
|
18
|
+
route: FixtureRoute,
|
|
19
|
+
context: FixtureContext,
|
|
20
|
+
headers: Record<string, string>
|
|
21
|
+
) {
|
|
22
|
+
const status = route.status ?? 200
|
|
23
|
+
const all = { ...headers, ...route.headers }
|
|
24
|
+
if (route.respond !== undefined) return route.respond(context)
|
|
25
|
+
if (route.sse !== undefined) {
|
|
26
|
+
const script = typeof route.sse === 'function' ? await route.sse(context) : route.sse
|
|
27
|
+
return sseResponse(script, all)
|
|
28
|
+
}
|
|
29
|
+
const body = typeof route.json === 'function' ? await route.json(context) : (route.json ?? null)
|
|
30
|
+
return Response.json(body, { status, headers: all })
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* A stand-in API for capturing a product with its own UI and data you choose: every request is
|
|
35
|
+
* answered from the routes (JSON, a scripted SSE stream, or a handler), and every request no route
|
|
36
|
+
* answers is recorded, so writing a scenario is a loop of "run, read `unmatched()`, add a route".
|
|
37
|
+
*/
|
|
38
|
+
export function createFixtureServer(options: FixtureServerOptions): FixtureServer {
|
|
39
|
+
const cors = options.cors !== false
|
|
40
|
+
const headers = cors ? CORS : {}
|
|
41
|
+
const hits: FixtureRequestRecord[] = []
|
|
42
|
+
const misses: FixtureRequestRecord[] = []
|
|
43
|
+
const server = Bun.serve({
|
|
44
|
+
port: options.port ?? 0,
|
|
45
|
+
hostname: options.hostname ?? '127.0.0.1',
|
|
46
|
+
idleTimeout: 0,
|
|
47
|
+
async fetch(request) {
|
|
48
|
+
const url = new URL(request.url)
|
|
49
|
+
if (cors && request.method === 'OPTIONS') return new Response(null, { status: 204, headers })
|
|
50
|
+
const found = findRoute(options.routes, request.method, url.pathname)
|
|
51
|
+
if (found === null) {
|
|
52
|
+
const status = options.unmatchedStatus ?? 404
|
|
53
|
+
misses.push({ method: request.method, path: url.pathname, status })
|
|
54
|
+
return Response.json({ error: 'no fixture', path: url.pathname }, { status, headers })
|
|
55
|
+
}
|
|
56
|
+
let body: string | null = null
|
|
57
|
+
const context: FixtureContext = {
|
|
58
|
+
request,
|
|
59
|
+
url,
|
|
60
|
+
params: found.params,
|
|
61
|
+
text: async () => {
|
|
62
|
+
body ??= await request.text()
|
|
63
|
+
return body
|
|
64
|
+
},
|
|
65
|
+
}
|
|
66
|
+
const response = await answer(found.route, context, headers)
|
|
67
|
+
hits.push({ method: request.method, path: url.pathname, status: response.status })
|
|
68
|
+
return response
|
|
69
|
+
},
|
|
70
|
+
})
|
|
71
|
+
return {
|
|
72
|
+
origin: `http://${server.hostname}:${server.port}`,
|
|
73
|
+
port: server.port ?? 0,
|
|
74
|
+
unmatched: () => [...misses],
|
|
75
|
+
hits: () => [...hits],
|
|
76
|
+
stop: async () => {
|
|
77
|
+
await server.stop(true)
|
|
78
|
+
},
|
|
79
|
+
}
|
|
80
|
+
}
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
import type { SseEvent, SseScript } from './types'
|
|
2
|
+
|
|
3
|
+
const encoder = new TextEncoder()
|
|
4
|
+
const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms))
|
|
5
|
+
|
|
6
|
+
/** One event in the wire format: `event:`, `id:`, then `data:` lines and a blank line. */
|
|
7
|
+
export function sseFrame(event: SseEvent): string {
|
|
8
|
+
const body = typeof event.data === 'string' ? event.data : JSON.stringify(event.data)
|
|
9
|
+
const head = [
|
|
10
|
+
...(event.event === undefined ? [] : [`event: ${event.event}`]),
|
|
11
|
+
...(event.id === undefined ? [] : [`id: ${event.id}`]),
|
|
12
|
+
]
|
|
13
|
+
const data = body.split('\n').map((line) => `data: ${line}`)
|
|
14
|
+
return `${[...head, ...data].join('\n')}\n\n`
|
|
15
|
+
}
|
|
16
|
+
|
|
17
|
+
/** A response that plays the script in real time: each event after its delay. */
|
|
18
|
+
export function sseResponse(script: SseScript, headers: Record<string, string>): Response {
|
|
19
|
+
let cancelled = false
|
|
20
|
+
const stream = new ReadableStream<Uint8Array>({
|
|
21
|
+
async start(controller) {
|
|
22
|
+
for (const event of script.events) {
|
|
23
|
+
if (event.delayMs !== undefined && event.delayMs > 0) await sleep(event.delayMs)
|
|
24
|
+
if (cancelled) return
|
|
25
|
+
controller.enqueue(encoder.encode(sseFrame(event)))
|
|
26
|
+
}
|
|
27
|
+
if (script.holdOpenMs !== undefined && script.holdOpenMs > 0) await sleep(script.holdOpenMs)
|
|
28
|
+
if (!cancelled) controller.close()
|
|
29
|
+
},
|
|
30
|
+
cancel() {
|
|
31
|
+
cancelled = true
|
|
32
|
+
},
|
|
33
|
+
})
|
|
34
|
+
return new Response(stream, {
|
|
35
|
+
headers: {
|
|
36
|
+
'content-type': 'text/event-stream',
|
|
37
|
+
'cache-control': 'no-cache',
|
|
38
|
+
connection: 'keep-alive',
|
|
39
|
+
...headers,
|
|
40
|
+
},
|
|
41
|
+
})
|
|
42
|
+
}
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
/** Any value JSON can carry: what a fixture answers with. */
|
|
2
|
+
export type JsonValue =
|
|
3
|
+
| string
|
|
4
|
+
| number
|
|
5
|
+
| boolean
|
|
6
|
+
| null
|
|
7
|
+
| JsonValue[]
|
|
8
|
+
| { [key: string]: JsonValue }
|
|
9
|
+
|
|
10
|
+
/** What a dynamic fixture receives. */
|
|
11
|
+
export interface FixtureContext {
|
|
12
|
+
request: Request
|
|
13
|
+
url: URL
|
|
14
|
+
/** Values of the route's `:name` segments (or the RegExp's named groups). */
|
|
15
|
+
params: Record<string, string>
|
|
16
|
+
/** The request body as text, read once and kept. */
|
|
17
|
+
text: () => Promise<string>
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** One event of a scripted Server-Sent Events stream. */
|
|
21
|
+
export interface SseEvent {
|
|
22
|
+
/** A string is sent as is; anything else as JSON. */
|
|
23
|
+
data: JsonValue
|
|
24
|
+
event?: string
|
|
25
|
+
id?: string
|
|
26
|
+
/** Wait before this event, in milliseconds: how a reply streams in. */
|
|
27
|
+
delayMs?: number
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
export interface SseScript {
|
|
31
|
+
events: SseEvent[]
|
|
32
|
+
/** Keeps the stream open this long after the last event; it closes at once by default. */
|
|
33
|
+
holdOpenMs?: number
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
type Dynamic<T> = T | ((context: FixtureContext) => T | Promise<T>)
|
|
37
|
+
|
|
38
|
+
/** One answer of the fixture server. Exactly one of `json`, `sse` or `respond`. */
|
|
39
|
+
export interface FixtureRoute {
|
|
40
|
+
/** `GET` by default; `*` answers every method. */
|
|
41
|
+
method?: string
|
|
42
|
+
/** `/llm/api/v1/conversations/:id` style, or a RegExp tested against the path. */
|
|
43
|
+
path: string | RegExp
|
|
44
|
+
status?: number
|
|
45
|
+
headers?: Record<string, string>
|
|
46
|
+
json?: Dynamic<JsonValue>
|
|
47
|
+
sse?: Dynamic<SseScript>
|
|
48
|
+
respond?: (context: FixtureContext) => Response | Promise<Response>
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface FixtureServerOptions {
|
|
52
|
+
routes: FixtureRoute[]
|
|
53
|
+
/** 0 picks a free port; 0 by default. */
|
|
54
|
+
port?: number
|
|
55
|
+
hostname?: string
|
|
56
|
+
/** Answers CORS preflights and adds `Access-Control-Allow-*` to every answer; on by default. */
|
|
57
|
+
cors?: boolean
|
|
58
|
+
/** Status of a request no route answers; 404 by default (the miss is recorded either way). */
|
|
59
|
+
unmatchedStatus?: number
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
export interface FixtureRequestRecord {
|
|
63
|
+
method: string
|
|
64
|
+
path: string
|
|
65
|
+
status: number
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
export interface FixtureServer {
|
|
69
|
+
origin: string
|
|
70
|
+
port: number
|
|
71
|
+
/** Requests no route answered, in order: the endpoints a scenario still has to describe. */
|
|
72
|
+
unmatched: () => FixtureRequestRecord[]
|
|
73
|
+
/** Every request answered, in order. */
|
|
74
|
+
hits: () => FixtureRequestRecord[]
|
|
75
|
+
stop: () => Promise<void>
|
|
76
|
+
}
|
|
@@ -1,11 +1,15 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* `nucleus-core-ts/demo-film`:
|
|
3
|
-
*
|
|
2
|
+
* `nucleus-core-ts/demo-film`: captures a demo run from the real product (`captureRun`, against its
|
|
3
|
+
* own UI and a fixture API from `createFixtureServer`), and renders demo films (the compositions an
|
|
4
|
+
* app builds from `nucleus-core-ts/fe`'s DemoFilm kit) to MP4 or PNG stills with headless Chrome.
|
|
5
|
+
* Server side only,
|
|
4
6
|
* run by Bun. `puppeteer-core` and `mp4-muxer` are optional peer dependencies: install them in the
|
|
5
7
|
* app that renders.
|
|
6
8
|
*/
|
|
7
9
|
|
|
10
|
+
export * from './capture'
|
|
8
11
|
export { resolveChromePath } from './chrome'
|
|
12
|
+
export * from './fixtures'
|
|
9
13
|
export { renderFilm } from './renderFilm'
|
|
10
14
|
export { renderStill } from './renderStill'
|
|
11
15
|
export { runAssetBase } from './session'
|