@toa.io/core 1.0.0-alpha.259 → 1.0.0-alpha.262

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [1.0.0-alpha.262](https://github.com/toa-io/toa/compare/v1.0.0-alpha.261...v1.0.0-alpha.262) (2026-08-28)
+
+
+### Features
+
+* **core:** identify the origin of a call with `request.source` ([9da6b66](https://github.com/toa-io/toa/commit/9da6b66df852690351a1e82c7b8cc176fd89774a))
+
+
+
+
+
 # [1.0.0-alpha.259](https://github.com/toa-io/toa/compare/v1.0.0-alpha.258...v1.0.0-alpha.259) (2026-08-24)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/core",
-  "version": "1.0.0-alpha.259",
+  "version": "1.0.0-alpha.262",
   "description": "Toa Core",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -27,5 +27,5 @@
     "openspan": "1.0.0-alpha.254",
     "uuid": "11.1.1"
   },
-  "gitHead": "3f557c2f855f078163128c317e7cb2f3629968aa"
+  "gitHead": "e14059cf5cc364d933f2a4b3d7114f3b5ec0764f"
 }

package/src/call.js

@@ -8,12 +8,14 @@ const { Err } = require('error-value')
 class Call extends Connector {
   #transmitter
   #contract
+  #source
 
-  constructor (transmitter, contract) {
+  constructor (transmitter, contract, source) {
     super()
 
     this.#transmitter = transmitter
     this.#contract = contract
+    this.#source = source
 
     this.depends(transmitter)
   }
@@ -21,6 +23,10 @@ class Call extends Connector {
   async invoke (request = {}) {
     request.input ??= null
 
+    // the caller may have attributed the call itself, as the node bridge does
+    if (this.#source !== undefined)
+      request.source ??= this.#source
+
     this.#contract.fit(request)
 
     // avoid validation on the recipient's side

package/src/context.js

@@ -9,6 +9,7 @@ class Context extends Connector {
   env
   name
   aspects
+  locator
 
   #local
   #discover
@@ -20,6 +21,7 @@ class Context extends Connector {
     this.env = process.env.TOA_ENV
     this.name = process.env.TOA_CONTEXT
     this.aspects = aspects
+    this.locator = local?.locator
 
     this.#local = local
     this.#discover = discover

package/src/contract/request.js

@@ -24,7 +24,11 @@ class Request extends Contract {
   static schema (definition, entity) {
     const schema = {
       type: 'object',
-      properties: { authentic: { type: 'boolean' }, task: { type: 'boolean' } },
+      properties: {
+        authentic: { type: 'boolean' },
+        task: { type: 'boolean' },
+        source: structuredClone(schemas.source)
+      },
       additionalProperties: true
     }
 

package/src/contract/schemas/index.js

@@ -5,3 +5,4 @@ const { load } = require('@toa.io/yaml')
 
 exports.query = load.sync(resolve(__dirname, './query.yaml'))
 exports.error = load.sync(resolve(__dirname, './error.yaml'))
+exports.source = load.sync(resolve(__dirname, './source.yaml'))

package/src/contract/schemas/source.yaml

@@ -0,0 +1,23 @@
+# Origin of a call, see toa.core.Source.
+# Deliberately permissive on required properties: the contract throws on a mismatch,
+# and a strict union would turn a partially stamped source into a failed business call.
+# `additionalProperties: false` combined with `removeAdditional` is what matters here —
+# it strips whatever a peer puts in, bounding the cardinality of the resulting map.
+type: object
+properties:
+  namespace:
+    type: string
+    maxLength: 64
+  component:
+    type: string
+    maxLength: 64
+  operation:
+    type: string
+    maxLength: 64
+  event:
+    type: string
+    maxLength: 64
+  service:
+    type: string
+    maxLength: 64
+additionalProperties: false

package/src/receiver.js

@@ -26,6 +26,9 @@ class Receiver extends Connector {
   /** @type {unknown[]} */
   #arguments
 
+  /** @type {toa.core.Source} */
+  #origin
+
   #local
 
   #bridge
@@ -41,6 +44,7 @@ class Receiver extends Connector {
     this.#label = definition.label ?? operation
     this.#destination = definition.destination ?? this.#label
     this.#arguments = definition.arguments
+    this.#origin = definition.origin
 
     this.#local = local
     this.#bridge = bridge
@@ -59,6 +63,9 @@ class Receiver extends Connector {
 
     add(request, extensions)
 
+    // set after `add`, so that a message field can not spoof the origin
+    if (this.#origin !== undefined) request.source = this.#origin
+
     // continue the trace from the producer span
     const remote = telemetry === undefined ? null : decode(telemetry)
     const task = () => this.#process(request)

package/test/contract/request.test.js

@@ -110,3 +110,42 @@ describe('schema', () => {
     expect(objects.limit).toBeDefined()
   })
 })
+
+describe('source', () => {
+  const schemas = require('@toa.io/schemas')
+
+  const compile = (definition, entity) =>
+    schemas.schema(Request.schema(definition, entity), { removeAdditional: true })
+
+  it('should declare source', () => {
+    const schema = Request.schema({}, dummy)
+
+    expect(schema.properties.source).toBeDefined()
+    expect(schema.properties.source.additionalProperties).toStrictEqual(false)
+  })
+
+  it('should pass known source variants', () => {
+    const schema = compile({}, undefined)
+
+    for (const source of [
+      { namespace: 'a', component: 'b', operation: 'c' },
+      { namespace: 'a', component: 'b', event: 'c' },
+      { service: 'exposition' }
+    ]) {
+      const request = { input: null, query: null, source }
+
+      expect(schema.fit(request)).toStrictEqual(null)
+      expect(request.source).toStrictEqual(source)
+    }
+  })
+
+  // `source` crosses the wire and keys the introspection map, so whatever
+  // a peer adds to it must not survive
+  it('should strip unknown source properties', () => {
+    const schema = compile({}, undefined)
+    const request = { input: null, query: null, source: { service: 'exposition', evil: 'x' } }
+
+    expect(schema.fit(request)).toStrictEqual(null)
+    expect(request.source).toStrictEqual({ service: 'exposition' })
+  })
+})

package/types/context.d.ts

@@ -1,4 +1,5 @@
 import * as _request from './request'
+import { Locator } from './locator'
 import * as _reply from './reply'
 import * as _extensions from './extensions'
 import * as _connector from './connector'
@@ -6,6 +7,8 @@ import * as _connector from './connector'
 export interface Context extends _connector.Connector{
   aspects: _extensions.Aspect[]
 
+  locator: Locator
+
   /**
    * Calls local endpoint
    */

package/types/extensions.d.ts

@@ -20,7 +20,7 @@ export interface Factory {
 
   storage? (storage: _storages.Storage): _storages.Storage
 
-  emitter? (emitter: _bindings.Emitter, label: string): _bindings.Emitter
+  emitter? (emitter: _bindings.Emitter, label: string, locator: _core.Locator): _bindings.Emitter
 
   receiver? (receiver: _core.Receiver, locator: _core.Locator): _core.Receiver
 }

package/types/index.ts

@@ -12,4 +12,4 @@ export type { Exception } from './exception'
 export { Locator } from './locator'
 export type { Receiver } from './receiver'
 export type { Message } from './message'
-export type { Request, Query, Reply } from './request'
+export type { Request, Query, Reply, Source } from './request'

package/types/request.d.ts

@@ -2,6 +2,7 @@ import { Exception } from './exception'
 
 export interface Query {
   id?: string
+  ids?: Array<string>
   criteria?: string
   search?: string
   sample?: number
@@ -13,12 +14,21 @@ export interface Query {
   deleted?: boolean
 }
 
+/**
+ * Origin of a call. Stamped by the caller, sanitized by the request contract.
+ */
+export type Source =
+  | { namespace: string, component: string, operation: string }
+  | { namespace: string, component: string, event: string }
+  | { service: string }
+
 export interface Request {
   input?: any
   query?: Query
   authentic?: boolean
   task?: boolean
   telemetry?: string // W3C traceparent
+  source?: Source
 }
 
 export interface Reply {