@cratis/chronicle 0.0.1 → 0.2.0

package/connection/ChronicleConnectionString.ts

@@ -1,4 +1,330 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-export { ChronicleConnectionString } from '@cratis/chronicle.contracts';
+import * as grpc from '@grpc/grpc-js';
+
+/**
+ * Authentication mode for Chronicle connection.
+ */
+export enum AuthenticationMode {
+    ClientCredentials = 'ClientCredentials',
+    ApiKey = 'ApiKey'
+}
+
+/**
+ * Represents a server address with host and port.
+ */
+export interface ChronicleServerAddress {
+    host: string;
+    port: number;
+}
+
+/**
+ * Builder for constructing Chronicle connection strings.
+ */
+export class ChronicleConnectionStringBuilder {
+    private static readonly _defaultPort = 35000;
+    private static readonly _hostKey = 'Host';
+    private static readonly _portKey = 'Port';
+    private static readonly _usernameKey = 'Username';
+    private static readonly _passwordKey = 'Password';
+    private static readonly _schemeKey = 'Scheme';
+    private static readonly _apiKeyKey = 'apiKey';
+    private static readonly _disableTlsKey = 'disableTls';
+    private static readonly _certificatePathKey = 'certificatePath';
+    private static readonly _certificatePasswordKey = 'certificatePassword';
+
+    private readonly _properties = new Map<string, string>();
+
+    constructor(connectionString?: string) {
+        if (connectionString) {
+            this.parseConnectionString(connectionString);
+        }
+    }
+
+    get host(): string {
+        return this._properties.get(ChronicleConnectionStringBuilder._hostKey) || 'localhost';
+    }
+
+    set host(value: string) {
+        this._properties.set(ChronicleConnectionStringBuilder._hostKey, value);
+    }
+
+    get port(): number {
+        const port = this._properties.get(ChronicleConnectionStringBuilder._portKey);
+        return port ? parseInt(port, 10) : ChronicleConnectionStringBuilder._defaultPort;
+    }
+
+    set port(value: number) {
+        this._properties.set(ChronicleConnectionStringBuilder._portKey, value.toString());
+    }
+
+    get username(): string | undefined {
+        return this._properties.get(ChronicleConnectionStringBuilder._usernameKey);
+    }
+
+    set username(value: string | undefined) {
+        if (value) {
+            this._properties.set(ChronicleConnectionStringBuilder._usernameKey, value);
+            return;
+        }
+
+        this._properties.delete(ChronicleConnectionStringBuilder._usernameKey);
+    }
+
+    get password(): string | undefined {
+        return this._properties.get(ChronicleConnectionStringBuilder._passwordKey);
+    }
+
+    set password(value: string | undefined) {
+        if (value) {
+            this._properties.set(ChronicleConnectionStringBuilder._passwordKey, value);
+            return;
+        }
+
+        this._properties.delete(ChronicleConnectionStringBuilder._passwordKey);
+    }
+
+    get scheme(): string {
+        return this._properties.get(ChronicleConnectionStringBuilder._schemeKey) || 'chronicle';
+    }
+
+    set scheme(value: string) {
+        this._properties.set(ChronicleConnectionStringBuilder._schemeKey, value);
+    }
+
+    get authenticationMode(): AuthenticationMode {
+        const hasClientCredentials = !!this.username && !!this.password;
+        const hasApiKey = !!this.apiKey;
+
+        if (hasClientCredentials && hasApiKey) {
+            throw new Error('Cannot specify both username/password and apiKey in the connection string');
+        }
+
+        if (hasClientCredentials) {
+            return AuthenticationMode.ClientCredentials;
+        }
+
+        if (hasApiKey) {
+            return AuthenticationMode.ApiKey;
+        }
+
+        throw new Error('No authentication method specified. Provide either username/password or apiKey in the connection string');
+    }
+
+    get apiKey(): string | undefined {
+        return this._properties.get(ChronicleConnectionStringBuilder._apiKeyKey);
+    }
+
+    set apiKey(value: string | undefined) {
+        if (value) {
+            this._properties.set(ChronicleConnectionStringBuilder._apiKeyKey, value);
+            return;
+        }
+
+        this._properties.delete(ChronicleConnectionStringBuilder._apiKeyKey);
+    }
+
+    get disableTls(): boolean {
+        return this._properties.get(ChronicleConnectionStringBuilder._disableTlsKey) === 'true';
+    }
+
+    set disableTls(value: boolean) {
+        this._properties.set(ChronicleConnectionStringBuilder._disableTlsKey, value.toString());
+    }
+
+    get certificatePath(): string | undefined {
+        return this._properties.get(ChronicleConnectionStringBuilder._certificatePathKey);
+    }
+
+    set certificatePath(value: string | undefined) {
+        if (value) {
+            this._properties.set(ChronicleConnectionStringBuilder._certificatePathKey, value);
+            return;
+        }
+
+        this._properties.delete(ChronicleConnectionStringBuilder._certificatePathKey);
+    }
+
+    get certificatePassword(): string | undefined {
+        return this._properties.get(ChronicleConnectionStringBuilder._certificatePasswordKey);
+    }
+
+    set certificatePassword(value: string | undefined) {
+        if (value) {
+            this._properties.set(ChronicleConnectionStringBuilder._certificatePasswordKey, value);
+            return;
+        }
+
+        this._properties.delete(ChronicleConnectionStringBuilder._certificatePasswordKey);
+    }
+
+    build(): string {
+        let result = `${this.scheme}://`;
+
+        if (this.username) {
+            result += this.username;
+            if (this.password) {
+                result += `:${this.password}`;
+            }
+            result += '@';
+        }
+
+        result += this.host;
+        result += `:${this.port}`;
+
+        const queryParameters: string[] = [];
+
+        if (this.apiKey) {
+            queryParameters.push(`apiKey=${encodeURIComponent(this.apiKey)}`);
+        }
+
+        if (this.disableTls) {
+            queryParameters.push('disableTls=true');
+        }
+
+        if (this.certificatePath) {
+            queryParameters.push(`certificatePath=${encodeURIComponent(this.certificatePath)}`);
+        }
+
+        if (this.certificatePassword) {
+            queryParameters.push(`certificatePassword=${encodeURIComponent(this.certificatePassword)}`);
+        }
+
+        for (const [key, value] of this._properties) {
+            if (
+                key !== ChronicleConnectionStringBuilder._hostKey &&
+                key !== ChronicleConnectionStringBuilder._portKey &&
+                key !== ChronicleConnectionStringBuilder._usernameKey &&
+                key !== ChronicleConnectionStringBuilder._passwordKey &&
+                key !== ChronicleConnectionStringBuilder._schemeKey &&
+                key !== ChronicleConnectionStringBuilder._apiKeyKey &&
+                key !== ChronicleConnectionStringBuilder._disableTlsKey &&
+                key !== ChronicleConnectionStringBuilder._certificatePathKey &&
+                key !== ChronicleConnectionStringBuilder._certificatePasswordKey
+            ) {
+                queryParameters.push(`${encodeURIComponent(key)}=${encodeURIComponent(value)}`);
+            }
+        }
+
+        if (queryParameters.length > 0) {
+            result += `?${queryParameters.join('&')}`;
+        }
+
+        return result;
+    }
+
+    private parseConnectionString(connectionString: string): void {
+        if (
+            connectionString.startsWith('chronicle://') ||
+            connectionString.startsWith('chronicle+srv://')
+        ) {
+            this.parseUrl(connectionString);
+        }
+    }
+
+    private parseUrl(value: string): void {
+        try {
+            const parsed = new URL(value);
+            this.scheme = parsed.protocol.replace(':', '');
+            this.host = parsed.hostname;
+
+            if (parsed.port) {
+                this.port = parseInt(parsed.port, 10);
+            }
+
+            if (parsed.username) {
+                this.username = decodeURIComponent(parsed.username);
+                if (parsed.password) {
+                    this.password = decodeURIComponent(parsed.password);
+                }
+            }
+
+            for (const [key, queryValue] of new URLSearchParams(parsed.search)) {
+                this._properties.set(key, decodeURIComponent(queryValue));
+            }
+        } catch (error) {
+            throw new Error(`Invalid Chronicle connection string: ${error}`);
+        }
+    }
+}
+
+/**
+ * Represents a Chronicle connection string.
+ */
+export class ChronicleConnectionString {
+    static readonly DEVELOPMENT_CLIENT = 'chronicle-dev-client';
+    static readonly DEVELOPMENT_CLIENT_SECRET = 'chronicle-dev-secret';
+    static readonly Default = new ChronicleConnectionString('chronicle://localhost:35000');
+    static readonly Development = new ChronicleConnectionString(
+        `chronicle://${ChronicleConnectionString.DEVELOPMENT_CLIENT}:${ChronicleConnectionString.DEVELOPMENT_CLIENT_SECRET}@localhost:35000`
+    );
+
+    private readonly _builder: ChronicleConnectionStringBuilder;
+    private readonly _serverAddress: ChronicleServerAddress;
+
+    constructor(connectionString: string) {
+        this._builder = new ChronicleConnectionStringBuilder(connectionString);
+        this._serverAddress = {
+            host: this._builder.host,
+            port: this._builder.port
+        };
+    }
+
+    get serverAddress(): ChronicleServerAddress {
+        return this._serverAddress;
+    }
+
+    get username(): string | undefined {
+        return this._builder.username;
+    }
+
+    get password(): string | undefined {
+        return this._builder.password;
+    }
+
+    get authenticationMode(): AuthenticationMode {
+        return this._builder.authenticationMode;
+    }
+
+    get apiKey(): string | undefined {
+        return this._builder.apiKey;
+    }
+
+    get disableTls(): boolean {
+        return this._builder.disableTls;
+    }
+
+    get certificatePath(): string | undefined {
+        return this._builder.certificatePath;
+    }
+
+    get certificatePassword(): string | undefined {
+        return this._builder.certificatePassword;
+    }
+
+    withCredentials(username: string, password: string): ChronicleConnectionString {
+        const builder = new ChronicleConnectionStringBuilder(this.toString());
+        builder.username = username;
+        builder.password = password;
+        return new ChronicleConnectionString(builder.build());
+    }
+
+    withApiKey(apiKey: string): ChronicleConnectionString {
+        const builder = new ChronicleConnectionStringBuilder(this.toString());
+        builder.apiKey = apiKey;
+        return new ChronicleConnectionString(builder.build());
+    }
+
+    createCredentials(): grpc.ChannelCredentials {
+        if (this.disableTls) {
+            return grpc.credentials.createInsecure();
+        }
+
+        return grpc.credentials.createSsl();
+    }
+
+    toString(): string {
+        return this._builder.build();
+    }
+}

package/connection/ChronicleServices.ts

@@ -1,4 +1,45 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-export { ChronicleServices } from '@cratis/chronicle.contracts';
+import type {
+    ConstraintsClient,
+    EventSeedingClient,
+    EventSequencesClient,
+    EventStoresClient,
+    EventTypesClient,
+    FailedPartitionsClient,
+    IdentitiesClient,
+    JobsClient,
+    NamespacesClient,
+    ObserversClient,
+    ProjectionsClient,
+    ReactorsClient,
+    ReadModelsClient,
+    RecommendationsClient,
+    ReducersClient,
+    ServerClient,
+    WebhooksClient
+} from '@cratis/chronicle.contracts';
+
+/**
+ * Represents all Chronicle gRPC services.
+ */
+export interface ChronicleServices {
+    eventStores: EventStoresClient;
+    namespaces: NamespacesClient;
+    recommendations: RecommendationsClient;
+    identities: IdentitiesClient;
+    eventSequences: EventSequencesClient;
+    eventTypes: EventTypesClient;
+    constraints: ConstraintsClient;
+    observers: ObserversClient;
+    failedPartitions: FailedPartitionsClient;
+    reactors: ReactorsClient;
+    reducers: ReducersClient;
+    projections: ProjectionsClient;
+    readModels: ReadModelsClient;
+    jobs: JobsClient;
+    webhooks: WebhooksClient;
+    eventSeeding: EventSeedingClient;
+    server: ServerClient;
+}

package/connection/Guid.ts

@@ -1,4 +1,30 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-export { Guid } from '@cratis/chronicle.contracts';
+import type { Guid as ContractsGuid } from '@cratis/chronicle.contracts';
+import { Guid as FundamentalGuid } from '@cratis/fundamentals';
+
+export { Guid } from '@cratis/fundamentals';
+
+/**
+ * Converts a Chronicle Guid into the protobuf-net bcl.Guid shape used by the
+ * contracts package.
+ */
+export function toContractsGuid(guid: FundamentalGuid): ContractsGuid {
+    const bytes = guid.bytes ?? FundamentalGuid.empty.bytes ?? [];
+    if (bytes.length !== 16) {
+        throw new Error(`Invalid Guid '${guid.toString()}'. Expected 16 bytes.`);
+    }
+
+    let lo = 0n;
+    let hi = 0n;
+    for (let index = 0; index < 8; index++) {
+        lo |= BigInt(bytes[index]) << BigInt(index * 8);
+        hi |= BigInt(bytes[index + 8]) << BigInt(index * 8);
+    }
+
+    return {
+        lo,
+        hi
+    };
+}

package/connection/TokenProvider.ts

@@ -1,13 +1,135 @@
 // Copyright (c) Cratis. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
-import type { ITokenProvider } from '@cratis/chronicle.contracts';
+import * as http from 'http';
+import * as https from 'https';
 
-export {
-	NoOpTokenProvider,
-	OAuthTokenProvider
-} from '@cratis/chronicle.contracts';
+const TOKEN_EXPIRY_BUFFER_SECONDS = 60;
+const DEFAULT_TOKEN_EXPIRY_SECONDS = 3600;
 
-export type { ITokenProvider } from '@cratis/chronicle.contracts';
+/**
+ * Interface for providing authentication tokens.
+ */
+export interface ITokenProvider {
+    /**
+     * Gets the current access token.
+     * @returns Promise resolving to the access token or undefined if not available.
+     */
+    getAccessToken(): Promise<string | undefined>;
+
+    /**
+     * Refreshes the access token by clearing cached tokens and obtaining a new one.
+     * @returns Promise resolving to the new access token or undefined if not available.
+     */
+    refresh(): Promise<string | undefined>;
+}
+
+/**
+ * No-op token provider for when authentication is not required.
+ */
+export class NoOpTokenProvider implements ITokenProvider {
+    async getAccessToken(): Promise<string | undefined> {
+        return undefined;
+    }
+
+    async refresh(): Promise<string | undefined> {
+        return undefined;
+    }
+}
+
+interface OAuthTokenResponse {
+    access_token: string;
+    expires_in: number;
+}
+
+/**
+ * OAuth token provider using client credentials flow.
+ */
+export class OAuthTokenProvider implements ITokenProvider {
+    private _accessToken?: string;
+    private _tokenExpiry = new Date(0);
+    private _refreshPromise?: Promise<string | undefined>;
+
+    constructor(
+        private readonly _tokenEndpoint: string,
+        private readonly _clientId: string,
+        private readonly _clientSecret: string
+    ) {}
+
+    async getAccessToken(): Promise<string | undefined> {
+        if (this._accessToken && new Date() < this._tokenExpiry) {
+            return this._accessToken;
+        }
+
+        if (this._refreshPromise) {
+            return this._refreshPromise;
+        }
+
+        this._refreshPromise = this.fetchAccessToken();
+        try {
+            return await this._refreshPromise;
+        } finally {
+            this._refreshPromise = undefined;
+        }
+    }
+
+    async refresh(): Promise<string | undefined> {
+        this._accessToken = undefined;
+        this._tokenExpiry = new Date(0);
+        return this.getAccessToken();
+    }
+
+    private async fetchAccessToken(): Promise<string | undefined> {
+        const params = new URLSearchParams();
+        params.append('grant_type', 'client_credentials');
+        params.append('client_id', this._clientId);
+        params.append('client_secret', this._clientSecret);
+
+        const body = params.toString();
+
+        return new Promise((resolve, reject) => {
+            const url = new URL(this._tokenEndpoint);
+            const httpModule = url.protocol === 'https:' ? https : http;
+
+            const req = httpModule.request(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    'Content-Length': Buffer.byteLength(body)
+                }
+            }, response => {
+                let data = '';
+
+                response.on('data', chunk => {
+                    data += chunk;
+                });
+
+                response.on('end', () => {
+                    if (response.statusCode !== 200) {
+                        reject(new Error(`Token request failed with status ${response.statusCode}: ${data}`));
+                        return;
+                    }
+
+                    try {
+                        const tokenResponse = JSON.parse(data) as OAuthTokenResponse;
+                        this._accessToken = tokenResponse.access_token;
+                        const expiresInSeconds = tokenResponse.expires_in || DEFAULT_TOKEN_EXPIRY_SECONDS;
+                        this._tokenExpiry = new Date(Date.now() + (expiresInSeconds - TOKEN_EXPIRY_BUFFER_SECONDS) * 1000);
+                        resolve(this._accessToken);
+                    } catch (error) {
+                        reject(new Error(`Failed to parse token response: ${error instanceof Error ? error.message : String(error)}`));
+                    }
+                });
+            });
+
+            req.on('error', error => {
+                reject(new Error(`Token request failed: ${error.message}`));
+            });
+
+            req.write(body);
+            req.end();
+        });
+    }
+}
 
 export type TokenProvider = ITokenProvider;

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();