@cratis/chronicle 0.0.1 → 0.1.0

package/Auditing/Causation.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CausationType } from './CausationType';
+
+/**
+ * Represents a causation instance.
+ */
+export class Causation {
+    /**
+     * Creates an unknown causation instance.
+     * @returns A new {@link Causation} with the current time, type set to {@link CausationType.unknown}, and empty properties.
+     */
+    static unknown(): Causation {
+        return new Causation(new Date(), CausationType.unknown, {});
+    }
+
+    /**
+     * Initializes a new instance of the {@link Causation} class.
+     * @param occurred - When it occurred.
+     * @param type - Type of causation.
+     * @param properties - Any properties associated with the causation.
+     */
+    constructor(
+        readonly occurred: Date,
+        readonly type: CausationType,
+        readonly properties: Readonly<Record<string, string>>
+    ) {}
+}

package/Auditing/CausationManager.ts

@@ -0,0 +1,51 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { Causation } from './Causation';
+import { CausationType } from './CausationType';
+import { ICausationManager } from './ICausationManager';
+
+/**
+ * Implements {@link ICausationManager} using {@link AsyncLocalStorage} to scope the causation chain to the active async call context.
+ */
+export class CausationManager implements ICausationManager {
+    private readonly _storage = new AsyncLocalStorage<Causation[]>();
+    private _root: Causation = new Causation(new Date(), CausationType.root, {});
+
+    /** @inheritdoc */
+    get root(): Causation {
+        return this._root;
+    }
+
+    /** @inheritdoc */
+    getCurrentChain(): ReadonlyArray<Causation> {
+        const chain = this._getOrInitChain();
+        return chain;
+    }
+
+    /** @inheritdoc */
+    add(type: CausationType, properties: Record<string, string>): void {
+        const chain = this._getOrInitChain();
+        chain.push(new Causation(new Date(), type, properties));
+    }
+
+    /**
+     * Defines the root causation for the current process.
+     * @param properties - Properties associated with the root causation.
+     */
+    defineRoot(properties: Record<string, string>): void {
+        this._root = new Causation(new Date(), CausationType.root, properties);
+    }
+
+    private _getOrInitChain(): Causation[] {
+        let chain = this._storage.getStore();
+        if (chain === undefined) {
+            chain = [this._root];
+            this._storage.enterWith(chain);
+        } else if (chain.length === 0) {
+            chain.push(this._root);
+        }
+        return chain;
+    }
+}

package/Auditing/CausationType.ts

@@ -0,0 +1,38 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents a type of causation.
+ */
+export class CausationType {
+    /**
+     * Represents the root causation type.
+     */
+    static readonly root = new CausationType('Root');
+
+    /**
+     * Represents the unknown causation type.
+     */
+    static readonly unknown = new CausationType('Unknown');
+
+    /**
+     * Represents the causation type for a single event append via the TypeScript client.
+     */
+    static readonly appendEvent = new CausationType('TypeScriptClient.Append');
+
+    /**
+     * Represents the causation type for a batch event append via the TypeScript client.
+     */
+    static readonly appendManyEvents = new CausationType('TypeScriptClient.AppendMany');
+
+    /**
+     * Initializes a new instance of the {@link CausationType} class.
+     * @param name - The name of the causation type.
+     */
+    constructor(readonly name: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.name;
+    }
+}

package/Auditing/ICausationManager.ts

@@ -0,0 +1,29 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Causation } from './Causation';
+import { CausationType } from './CausationType';
+
+/**
+ * Defines a system that manages causation for the active call context.
+ */
+export interface ICausationManager {
+    /**
+     * Gets the root causation.
+     */
+    readonly root: Causation;
+
+    /**
+     * Gets the full causation chain for the current call context.
+     * The chain always starts with {@link root} if no other causation has been added.
+     * @returns An array of {@link Causation} representing the current chain.
+     */
+    getCurrentChain(): ReadonlyArray<Causation>;
+
+    /**
+     * Adds a causation entry to the current chain.
+     * @param type - The type of causation to add.
+     * @param properties - Properties associated with the causation.
+     */
+    add(type: CausationType, properties: Record<string, string>): void;
+}

package/Auditing/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { Causation } from './Causation';
+export { CausationType } from './CausationType';
+export type { ICausationManager } from './ICausationManager';
+export { CausationManager } from './CausationManager';
+
+import { CausationManager } from './CausationManager';
+
+/**
+ * The default singleton {@link CausationManager} for the process.
+ * Use this to manage the causation chain for the current async call context.
+ */
+export const causationManager = new CausationManager();

package/Correlation/CorrelationId.ts

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Guid } from '@cratis/fundamentals';
+
+/**
+ * Represents a correlation identifier used to track operations across call boundaries.
+ */
+export class CorrelationId {
+    /**
+     * A well-known {@link CorrelationId} representing an unset/empty value.
+     */
+    static readonly notSet = new CorrelationId('00000000-0000-0000-0000-000000000000');
+
+    /**
+     * Creates a new unique {@link CorrelationId}.
+     * @returns A new {@link CorrelationId} backed by a freshly generated GUID.
+     */
+    static create(): CorrelationId {
+        return new CorrelationId(Guid.create().toString());
+    }
+
+    /**
+     * Initializes a new instance of the {@link CorrelationId} class.
+     * @param value - The string value of the correlation identifier.
+     */
+    constructor(readonly value: string) {}
+
+    /** @inheritdoc */
+    toString(): string {
+        return this.value;
+    }
+}

package/Correlation/CorrelationIdManager.ts

@@ -0,0 +1,30 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { CorrelationId } from './CorrelationId';
+import { ICorrelationIdAccessor } from './ICorrelationIdAccessor';
+import { ICorrelationIdSetter } from './ICorrelationIdSetter';
+
+/**
+ * Implements both {@link ICorrelationIdAccessor} and {@link ICorrelationIdSetter},
+ * using {@link AsyncLocalStorage} to scope the correlation identifier to the active async call context.
+ */
+export class CorrelationIdManager implements ICorrelationIdAccessor, ICorrelationIdSetter {
+    private readonly _storage = new AsyncLocalStorage<CorrelationId>();
+
+    /** @inheritdoc */
+    get current(): CorrelationId {
+        return this._storage.getStore() ?? CorrelationId.create();
+    }
+
+    /** @inheritdoc */
+    setCurrent(correlationId: CorrelationId): void {
+        this._storage.enterWith(correlationId);
+    }
+
+    /** @inheritdoc */
+    clear(): void {
+        this._storage.enterWith(CorrelationId.create());
+    }
+}

package/Correlation/ICorrelationIdAccessor.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CorrelationId } from './CorrelationId';
+
+/**
+ * Defines the read side of a correlation identifier provider scoped to the active call context.
+ */
+export interface ICorrelationIdAccessor {
+    /**
+     * Gets the current correlation identifier for the active call context.
+     * @returns The current {@link CorrelationId}.
+     */
+    readonly current: CorrelationId;
+}

package/Correlation/ICorrelationIdSetter.ts

@@ -0,0 +1,21 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { CorrelationId } from './CorrelationId';
+
+/**
+ * Defines the write side of a correlation identifier provider scoped to the active call context.
+ */
+export interface ICorrelationIdSetter {
+    /**
+     * Sets the current correlation identifier for the active call context.
+     * @param correlationId - The {@link CorrelationId} to set.
+     */
+    setCurrent(correlationId: CorrelationId): void;
+
+    /**
+     * Clears the current correlation identifier for the active call context,
+     * causing the next access to generate a new unique identifier.
+     */
+    clear(): void;
+}

package/Correlation/index.ts

@@ -0,0 +1,15 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { CorrelationId } from './CorrelationId';
+export type { ICorrelationIdAccessor } from './ICorrelationIdAccessor';
+export type { ICorrelationIdSetter } from './ICorrelationIdSetter';
+export { CorrelationIdManager } from './CorrelationIdManager';
+
+import { CorrelationIdManager } from './CorrelationIdManager';
+
+/**
+ * The default singleton {@link CorrelationIdManager} for the process.
+ * Use this to get and set the correlation identifier for the current async call context.
+ */
+export const correlationIdManager = new CorrelationIdManager();

package/EventSequences/EventSequence.ts

@@ -1,10 +1,7 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import {
-    ChronicleConnection,
-    Guid as ContractsGuid
-} from '../connection';
+import { ChronicleConnection } from '../connection';
 import { SpanStatusCode } from '@opentelemetry/api';
 import { Guid } from '@cratis/fundamentals';
 import { getEventTypeFor } from '../Events/eventTypeDecorator';
@@ -16,6 +13,10 @@ import { EventSequenceId } from './EventSequenceId';
 import { EventSequenceNumber } from './EventSequenceNumber';
 import { ChronicleTracer } from '../Tracing';
 import { ChronicleMetrics } from '../Metrics';
+import { identityProvider, Identity } from '../Identity';
+import { causationManager, CausationType } from '../Auditing';
+import { correlationIdManager } from '../Correlation';
+import { toContractsGuid } from '../connection/Guid';
 
 /**
  * Implements {@link IEventSequence} by communicating with the Chronicle Kernel
@@ -33,10 +34,14 @@ export class EventSequence implements IEventSequence {
     async append(eventSourceId: string, event: object, options?: AppendOptions): Promise<AppendResult> {
         const eventType = getEventTypeFor(event.constructor as Function);
         const correlationId = options?.correlationId === undefined
-            ? Guid.create()
+            ? Guid.as(correlationIdManager.current.value)
             : Guid.as(options.correlationId);
         const content = JSON.stringify(event);
 
+        causationManager.add(CausationType.appendEvent, { eventType: eventType.id.value });
+        const causationChain = causationManager.getCurrentChain();
+        const identity = identityProvider.getCurrent();
+
         const metricAttributes = {
             'chronicle.event_store': this._eventStoreName,
             'chronicle.namespace': this._namespace,
@@ -68,17 +73,12 @@ export class EventSequence implements IEventSequence {
                         Tombstone: eventType.tombstone
                     },
                     Content: content,
-                    Causation: [{
-                        Occurred: { Value: new Date().toISOString() },
-                        Type: 'TypeScriptClient.Append',
-                        Properties: {}
-                    }],
-                    CausedBy: {
-                        Subject: '5d032c92-9d5e-41eb-947a-ee5314ed0032',
-                        Name: '[System]',
-                        UserName: '[System]',
-                        OnBehalfOf: undefined
-                    },
+                    Causation: causationChain.map(c => ({
+                        Occurred: { Value: c.occurred.toISOString() },
+                        Type: c.type.name,
+                        Properties: { ...c.properties }
+                    })),
+                    CausedBy: toContractsCausedBy(identity),
                     ConcurrencyScope: {
                         // ulong.MaxValue sent as BigInt so the server recognises it as ConcurrencyScope.None (no validation)
                         SequenceNumber: 18446744073709551615n as unknown as number,
@@ -137,9 +137,13 @@ export class EventSequence implements IEventSequence {
     /** @inheritdoc */
     async appendMany(eventSourceId: string, events: object[], options?: AppendOptions): Promise<AppendResult[]> {
         const correlationId = options?.correlationId === undefined
-            ? Guid.create()
+            ? Guid.as(correlationIdManager.current.value)
             : Guid.as(options.correlationId);
 
+        causationManager.add(CausationType.appendManyEvents, { count: String(events.length) });
+        const batchCausationChain = causationManager.getCurrentChain();
+        const identity = identityProvider.getCurrent();
+
         const eventsToAppend = events.map(event => {
             const eventType = getEventTypeFor(event.constructor as Function);
             return {
@@ -153,17 +157,12 @@ export class EventSequence implements IEventSequence {
                     Tombstone: eventType.tombstone
                 },
                 Content: JSON.stringify(event),
-                Causation: [{
-                    Occurred: { Value: new Date().toISOString() },
-                    Type: 'TypeScriptClient.AppendMany.Event',
-                    Properties: {}
-                }],
-                CausedBy: {
-                    Subject: '5d032c92-9d5e-41eb-947a-ee5314ed0032',
-                    Name: '[System]',
-                    UserName: '[System]',
-                    OnBehalfOf: undefined
-                },
+                Causation: batchCausationChain.map(c => ({
+                    Occurred: { Value: c.occurred.toISOString() },
+                    Type: c.type.name,
+                    Properties: { ...c.properties }
+                })),
+                CausedBy: toContractsCausedBy(identity),
                 ConcurrencyScope: {
                     SequenceNumber: 18446744073709551615n as unknown as number,
                     EventSourceId: false,
@@ -199,17 +198,12 @@ export class EventSequence implements IEventSequence {
                     EventSequenceId: this.id.value,
                     CorrelationId: toContractsGuid(correlationId),
                     Events: eventsToAppend,
-                    Causation: [{
-                        Occurred: { Value: new Date().toISOString() },
-                        Type: 'TypeScriptClient.AppendMany.Batch',
-                        Properties: {}
-                    }],
-                    CausedBy: {
-                        Subject: '5d032c92-9d5e-41eb-947a-ee5314ed0032',
-                        Name: '[System]',
-                        UserName: '[System]',
-                        OnBehalfOf: undefined
-                    },
+                    Causation: batchCausationChain.map(c => ({
+                        Occurred: { Value: c.occurred.toISOString() },
+                        Type: c.type.name,
+                        Properties: { ...c.properties }
+                    })),
+                    CausedBy: toContractsCausedBy(identity),
                     ConcurrencyScopes: {}
                 });
 
@@ -355,18 +349,22 @@ export class EventSequence implements IEventSequence {
  * @param guid - The Guid to convert.
  * @returns The converted protobuf Guid with fixed64-safe hi/lo values.
  */
-function toContractsGuid(guid: Guid): ContractsGuid {
-    const hex = guid.toString().replace(/-/g, '');
-    const hi = BigInt(`0x${hex.substring(0, 16)}`);
-    const lo = BigInt(`0x${hex.substring(16, 32)}`);
 
-    // Mask to MAX_SAFE_INTEGER so the contracts package can decode the Guid
-    // from the response without a longToNumber overflow. Correlation IDs are
-    // opaque identifiers, so 52+52 bits of entropy is more than sufficient.
-    const safe = BigInt(Number.MAX_SAFE_INTEGER);
-    return {
-        hi: Number(hi & safe),
-        lo: Number(lo & safe)
+/**
+ * Converts an {@link Identity} into the CausedBy shape used by Chronicle contracts.
+ * @param identity - The identity to convert.
+ * @returns The contracts CausedBy object.
+ */
+function toContractsCausedBy(identity: Identity): object {
+    const result: Record<string, unknown> = {
+        Subject: identity.subject,
+        Name: identity.name,
+        UserName: identity.userName,
+        OnBehalfOf: undefined
     };
+    if (identity.onBehalfOf !== undefined) {
+        result.OnBehalfOf = toContractsCausedBy(identity.onBehalfOf);
+    }
+    return result;
 }
 

package/Identity/IIdentityProvider.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { Identity } from './Identity';
+
+/**
+ * Defines a system that can provide and manage the current {@link Identity} for the active call context.
+ */
+export interface IIdentityProvider {
+    /**
+     * Gets the current identity for the active call context.
+     * @returns The current {@link Identity}, or {@link Identity.system} if none has been set.
+     */
+    getCurrent(): Identity;
+
+    /**
+     * Sets the current identity for the active call context.
+     * @param identity - The {@link Identity} to set.
+     */
+    setCurrentIdentity(identity: Identity): void;
+
+    /**
+     * Clears the current identity for the active call context, resetting it to {@link Identity.system}.
+     */
+    clearCurrentIdentity(): void;
+}

package/Identity/Identity.ts

@@ -0,0 +1,61 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+/**
+ * Represents an identity of something that is responsible for causing a state change.
+ * An identity can be a user, a system, a service or anything else that can be identified.
+ */
+export class Identity {
+    /**
+     * The identity used when not set.
+     */
+    static readonly notSet = new Identity('1efc9b81-0612-4466-962c-86acc4e9a028', '[Not Set]', '[Not Set]');
+
+    /**
+     * The identity used when the identity is not known.
+     */
+    static readonly unknown = new Identity('3321cf62-db16-425e-8173-99fcfefe11dd', '[Unknown]', '[Unknown]');
+
+    /**
+     * The identity used when the system is the cause.
+     */
+    static readonly system = new Identity('5d032c92-9d5e-41eb-947a-ee5314ed0032', '[System]', '[System]');
+
+    /**
+     * Initializes a new instance of the {@link Identity} class.
+     * @param subject - The identifier of the identity, referred to as subject.
+     * @param name - Name of the identity.
+     * @param userName - Optional username, defaults to empty string.
+     * @param onBehalfOf - Optional behalf of {@link Identity}.
+     */
+    constructor(
+        readonly subject: string,
+        readonly name: string,
+        readonly userName: string = '',
+        readonly onBehalfOf?: Identity
+    ) {}
+
+    /**
+     * Returns a new {@link Identity} chain with duplicate subjects removed.
+     * The first occurrence of each subject is kept.
+     * @returns A new {@link Identity} with duplicates removed from the chain.
+     */
+    withoutDuplicates(): Identity {
+        const seen = new Set<string>();
+        const chain: Identity[] = [];
+        let current: Identity | undefined = this;
+        while (current !== undefined) {
+            if (!seen.has(current.subject)) {
+                seen.add(current.subject);
+                chain.push(current);
+            }
+            current = current.onBehalfOf;
+        }
+
+        let result: Identity | undefined;
+        for (let i = chain.length - 1; i >= 0; i--) {
+            result = new Identity(chain[i].subject, chain[i].name, chain[i].userName, result);
+        }
+        return result!;
+    }
+}

package/Identity/IdentityProvider.ts

@@ -0,0 +1,28 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+import { AsyncLocalStorage } from 'async_hooks';
+import { Identity } from './Identity';
+import { IIdentityProvider } from './IIdentityProvider';
+
+/**
+ * Implements {@link IIdentityProvider} using {@link AsyncLocalStorage} to scope the identity to the active async call context.
+ */
+export class IdentityProvider implements IIdentityProvider {
+    private readonly _storage = new AsyncLocalStorage<Identity>();
+
+    /** @inheritdoc */
+    getCurrent(): Identity {
+        return this._storage.getStore() ?? Identity.system;
+    }
+
+    /** @inheritdoc */
+    setCurrentIdentity(identity: Identity): void {
+        this._storage.enterWith(identity);
+    }
+
+    /** @inheritdoc */
+    clearCurrentIdentity(): void {
+        this._storage.enterWith(Identity.system);
+    }
+}

package/Identity/index.ts

@@ -0,0 +1,14 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+export { Identity } from './Identity';
+export type { IIdentityProvider } from './IIdentityProvider';
+export { IdentityProvider } from './IdentityProvider';
+
+import { IdentityProvider } from './IdentityProvider';
+
+/**
+ * The default singleton {@link IdentityProvider} for the process.
+ * Use this to get and set the identity for the current async call context.
+ */
+export const identityProvider = new IdentityProvider();