@bett3r-dev/pv3-types 1.0.0

package/src/authentication.ts

@@ -0,0 +1,273 @@
+import S, { mergeMultipleSchemas, mergeSchemas, omitFromSchema } from '@bett3r-dev/jsonschema-definer';
+import { RoutesAuthManagerType } from './routesAuth';
+import { ClusterRoutesConfigType } from './clusterAdministration';
+import { AdapterBase, PortEmitter } from './ports';
+import { Ports } from './ports';
+
+//*******************************************
+// Schemas
+//*******************************************
+/**
+ * @category Schemas
+ */
+export const AuthenticationIdSchema = S.shape({
+  id: S.string()
+});
+/**
+ * @category Schemas
+ */
+export const AuthenticationEmailSchema = S.shape({
+  email: S.string().format( 'email' )
+});
+export type AuthenticationEmail = typeof AuthenticationEmailSchema.type;
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationPasswordSchema = S.shape({
+  password: S.string()
+});
+export type AuthenticationPassword = typeof AuthenticationPasswordSchema.type;
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationRoleSchema = S.shape({
+  role: S.string(),
+});
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationRolesSchema = S.shape({
+  roles: S.array().items( S.string()),
+});
+export type AuthenticationRolesType = typeof AuthenticationRolesSchema.type;
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationProviderIdSchema = S.shape({
+  providerId: S.string(),
+  providerName: S.string(),
+});
+export type AuthenticationProviderId = typeof AuthenticationProviderIdSchema.type
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationProviderUserSchema = mergeSchemas( AuthenticationEmailSchema, AuthenticationProviderIdSchema );
+
+/**
+ * @category Schemas
+ */
+export const UserLoginSchema = mergeSchemas( AuthenticationEmailSchema, AuthenticationPasswordSchema );
+export type UserLogin = typeof UserLoginSchema.type
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationRegistrationSchema = mergeSchemas( UserLoginSchema, AuthenticationRolesSchema );
+export type AuthenticationRegistrationType = typeof AuthenticationRegistrationSchema.type;
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationCustomAttributesSchema = S.shape({
+  attributes: S.shape({}).additionalProperties( true ).optional()
+});
+export type AuthenticationCustomAttributesType = typeof AuthenticationCustomAttributesSchema.type;
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationUserSchema = mergeMultipleSchemas( AuthenticationIdSchema, AuthenticationEmailSchema, AuthenticationRolesSchema, AuthenticationCustomAttributesSchema );
+export type AuthenticationUser = typeof AuthenticationUserSchema.type;
+
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationCreateUserCommandSchema = mergeSchemas( AuthenticationUserSchema, AuthenticationPasswordSchema );
+export type AuthenticationCreateUserCommand = typeof AuthenticationCreateUserCommandSchema.type
+
+export const AuthenticationUpdateUserCommandSchema = mergeSchemas( omitFromSchema( AuthenticationCreateUserCommandSchema, [ 'password', 'id', 'roles' ]).partial(), S.shape({ providerId: S.string() }));
+export type AuthenticationUpdateUserCommand = typeof AuthenticationUpdateUserCommandSchema.type;
+
+/**
+ * @category Schemas
+ */
+export const AuthenticationResponseSchema = mergeSchemas( AuthenticationRolesSchema, S.shape({
+  'expires_in': S.number(),
+  'refresh_expires_in': S.number(),
+  'not-before-policy': S.number(),
+  'access_token': S.string(),
+  'refresh_token': S.string(),
+  'token_type': S.string(),
+  'session_state': S.string(),
+  'scope': S.string(),
+}));
+export type AuthenticationResponseType = typeof AuthenticationResponseSchema.type;
+
+
+//*******************************************
+// Identity Provider
+//*******************************************
+
+
+/**
+ * Logs a user in the Application.
+ * @category Authentication Port
+ * @param email Email of the user
+ * @param password Password of the user
+ */
+export declare function loginUser ( email:string, password:string ): Promise<AuthenticationResponseType>;
+
+/**
+ * Inits the Recover Password process for the user with the given email.
+ * @category Authentication Port
+ * @param email Email of the user
+ */
+export declare function recoverPassword ( email:string ): Promise<void>;
+
+/**
+ * Marks the user email address as validated.
+ * @category Authentication Port
+ * @param email Email of the user
+ */
+export declare function verifyEmail ( email: string ): Promise<void>;
+
+/**
+ * Logs out a user from the application
+ * @category Authentication Port
+ * @param token Session Token to mark as logged out
+ */
+export declare function logoutUser ( token: string ): Promise<void>;
+
+/**
+ * Refreshes the user sesssion given the refresh token.
+ * @category Authentication Port
+ * @param refreshToken Session Refresh Token
+ */
+export declare function refreshToken ( refreshToken: string ): Promise<AuthenticationResponseType>;
+
+/**
+ * Changes the password of the user
+ * @category Authentication Port
+ * @param email User Email Address
+ * @param password New Password for the User
+ */
+export declare function resetPassword ( email:string, password:string ): Promise<void>;
+
+/**
+ * Creates a new Role in the Application in the Authentication Provider
+ * @category Authentication Port
+ * @param name The name of the Role To Create
+ */
+export declare function createRole ( name: string ): Promise<void>;
+
+/**
+ * Fetches from the Authentication Provider the list of existing Roles for the given tenant or the default one.
+ * @category Authentication Port
+ * @param tenant [Optional] The tenant for the role list to be retrieved
+ */
+export declare function getRoles ( tenant?: string ): Promise<void>;
+
+/**
+ * Deletes a Role from the Authentication Provider.
+ * @category Authentication Port
+ * @param name The name of the Role to Delete
+ */
+export declare function deleteRole ( name: string ): Promise<void>;
+
+/**
+ * Creates a new User in the Authentication Provider
+ * @category Authentication Port
+ * @param id Application Id of the User to create
+ * @param email The Email address of the user
+ * @param roles The roles to create the user with
+ * @param attributes Additional Attributes to add to the auth token
+ */
+export declare function createUser ( id:string, email:string, password:string, roles: string[], attributes?: Record<string, any> ): Promise<string>;
+/**
+ * Creates a new User in the Authentication Provider
+ * @category Authentication Port
+ * @param id Provider Id of the User to create
+ * @param email The Email address of the user
+ * @param attributes Additional Attributes to add to the auth token
+ */
+export declare function updateUser ( providerId:string, email?:string, attributes?: Record<string, any> ): Promise<string>;
+
+/**
+ * Assigns a list of roles to a given user
+ * @category Authentication Port
+ * @param email The User Email Address
+ * @param roles The Roles to assign to the user
+ */
+export declare function assignUserRoles ( email:string, roles: string[]): Promise<void>;
+
+/**
+ * Removes a list of roles from a given user
+ * @category Authentication Port
+ * @param email The User Email Address
+ * @param roles The roles to remove from the user
+ */
+export declare function removeUserRoles ( email:string, roles: string[]): Promise<void>;
+
+/**
+ * Performs the Authorization process for a request to a resource given the user Access Token.
+ * This function is the response of the `authorizeRequest` curried execution.
+ * @param accessToken JWT Access Token of the request
+ * @param method The HTTP method accessing the resource
+ * @param uri The resource uri
+ * @see {@link authorizeRequest}
+ */
+export declare function authorizeRequestFunction( accessToken: string, method: string, uri: string ): Promise<void>
+
+/**
+ * Curried function that will receive the routeManager as parameter and
+ * return another function with the actual authorization functionality
+ * @category Authentication Port
+ * @param routeManager The route manager to use to perform the authorization process of the resource requested.
+ * @see {@link authorizeRequestFunction}
+ */
+export declare function authorizeRequest ( routeManager: RoutesAuthManagerType ): typeof authorizeRequestFunction
+
+/**
+ * @category Main Types
+ */
+export type AuthenticationType = {
+  name: string,
+  loginUser: typeof loginUser
+  recoverPassword: typeof recoverPassword
+  verifyEmail: typeof verifyEmail
+  logoutUser: typeof logoutUser
+  refreshToken: typeof refreshToken
+  resetPassword: typeof resetPassword
+  createRole: typeof createRole
+  getRoles: typeof getRoles
+  deleteRole: typeof deleteRole
+  createUser: typeof createUser
+  updateUser: typeof updateUser
+  assignUserRoles: typeof assignUserRoles
+  removeUserRoles: typeof removeUserRoles
+  authorizeRequest: typeof authorizeRequest
+}
+
+/**
+ * @category Main Types
+ */
+export type AuthenticationPort = PortEmitter & AuthenticationType & {
+  RouteManager: ( ports: Pick<Ports, 'database'|'eventstore'>, config: ClusterRoutesConfigType, eventstore?: Ports['eventstore']) => RoutesAuthManagerType
+};
+
+/**
+ * Defines the concrete implementation for the Authentication Port.
+ *
+ * __start__ Stablishes the connection with the Authentication Provider with a Service Account with administrative
+ * Priviledges that will effect all the operations.
+ *
+ * __stop__ Disconnects the Service Account from the Authentication Provider
+ * @category Main Types
+*/
+export type AuthenticationAdapter = AuthenticationType & AdapterBase

package/src/cache.ts

@@ -0,0 +1,109 @@
+import { AdapterBase, PortEmitter } from './ports';
+
+/**
+ * @category Main Types
+ */
+export type CacheAdapter<T = any> = CacheType & AdapterBase<T> & {
+  flushAll: () => Promise<void>
+}
+
+/**
+ * @category Main Types
+ */
+export type CachePort = PortEmitter & CacheType;
+
+/**
+ * @hidden
+ */
+export declare function set<T extends Record<string, any>>( key: string ) : ( value: T, expirationSeconds?: number | boolean ) => Promise<T>
+/**
+ * Stores a key value pair in cache
+ * @category Cache Port
+ * @param key The key to store in cache
+ * @param value The value to store in the key. Bear in mind that the value will be JSON stringified
+ * @param expirationSeconds TTL for the cache, in case of `false` passed, the cache would not expire
+ */
+export declare function set<T>( key: string, value: T, expirationSeconds?: number | false ): Promise<T>
+/**
+ * @category Cache Port
+ * @param key
+ */
+export declare function get<T>( key: string ): Promise<T>
+/**
+ * @category Cache Port
+ * @param key
+ */
+export declare function remove( key: string ): Promise<void>
+/**
+ * @category Cache Port
+ * @param key
+ * @param value
+ */
+export declare function incrementBy( key:string, value: number ): Promise<number>
+/**
+ * @category Cache Port
+ * @param function
+ */
+export declare function memoize<F extends Function>( func: F, expirationSeconds?: number | false ): F
+
+/**
+ * @category Cache Port
+ * @param pattern
+ */
+export declare function keys( pattern: string ): Promise<string[]>
+
+//*******************************************
+// HASHES
+//*******************************************
+/**
+ * HEXISTS
+ * @category Cache Port
+ * */
+export declare function hashExists( key: string, hash:string ): Promise<boolean>
+/** HGET */
+export declare function hashGet<T>( key: string, hash:string ): Promise<T>
+/**
+ * HGExTALL
+ * It will always return a Record<string, string>, further coerce of types must be implemented by client
+ * @category Cache Port
+ */
+export declare function hashGetAll( key: string ): Promise<Record<string, string>>
+/**
+ * HSET
+ * @category Cache Port
+ * */
+export declare function hashSet<T>( key: string, hash:string, value: T ): Promise<boolean>
+/**
+ * HSETNX
+ * @category Cache Port
+ * */
+export declare function hashSetIfNotExists<T>( key: string, hash:string, value: T ): Promise<boolean>
+/**
+ * HINCRBY
+ * @category Cache Port
+ * */
+export declare function hashIncrementBy( key: string, hash:string, value: number ): Promise<boolean>
+/**
+ * HDEL
+ * @category Cache Port
+ * */
+export declare function hashDel( key: string, hash:string ): Promise<boolean>
+
+/**
+ * @category Main Types
+ */
+export type CacheType = {
+  set: typeof set
+  get: typeof get
+  keys: typeof keys
+  memoize: typeof memoize
+  remove: typeof remove
+  incrementBy: typeof incrementBy
+  hashExists: typeof hashExists
+  hashGet: typeof hashGet
+  hashGetAll: typeof hashGetAll
+  hashSet: typeof hashSet
+  hashSetIfNotExists: typeof hashSetIfNotExists
+  hashIncrementBy: typeof hashIncrementBy
+  hashDel: typeof hashDel
+}

package/src/clusterAdministration.ts

@@ -0,0 +1,216 @@
+import S, { mergeSchemas, omitFromSchema } from '@bett3r-dev/jsonschema-definer';
+import { CommittedEvent, Event } from '@bett3r-dev/pv3-types';
+
+export type ClusterStructureType = {
+  getCurrentState: ( id?: string ) => Promise<StructureState>,
+  getStructureRevision: ( version:number ) => Promise<StructureState | null>,
+  subscribeToStructureChanges: ( onStructureChanges: ( change: StructureState ) => void ) => Promise<{ unsubscribe: () => void }>,
+  stop: () => Promise<void>,
+} & {
+  [key in keyof CommandTypes]: ( payload: CommandTypes[key], expectedVersion?: number ) => Promise<StructureState>;
+}
+
+export type StructureState = {
+  state: StructureAggregateType,
+  version: number,
+}
+
+export type StructureCommittedEventType = CommittedEvent<StructureAggregateType & {
+  change: {
+    broker: {host: string};
+    service: {host: string};
+    subscriptions: {subscriptions: Record<string,number>};
+  }
+}>
+
+export const StructureServiceSchema = S.shape({
+  hosts: S.array().items( S.string()),
+  port: S.number().default( 1984 ).optional(),
+  channel: S.string().enum( 'tcp', 'http', 'local' ).default( 'http' ).optional(),
+  isExternal: S.boolean().default( false ).optional(),
+  possibleSubscriptions: S.array().items( S.string()).optional(),
+  possibleModules: S.shape({}).additionalProperties( S.array().items( S.string())).optional(),
+  isService: S.boolean().optional(),
+  isBroker: S.boolean().optional(),
+  endpoints: S.array().items( S.string()).optional(),
+  openApiEndpoint: S.string().optional().default( '/documentation/json' ),
+  produces: S.shape({}).additionalProperties( S.array().items( S.string())).optional(),
+  consumes: S.shape({}).additionalProperties( S.array().items( S.string())).optional(),
+});
+export type StructureServiceType = typeof StructureServiceSchema.type;
+
+export const RetryableStatuses = [ 429, 503, 504 ];
+
+export const StructureSubscriptionSchema = S.shape({
+  producers: S.array().items( S.string()),
+  module: S.string(),
+  consumer: S.string(),
+  load: S.number().optional(),
+  eventstore: S.string().optional(),
+  events: S.array().items( S.string()).optional(),
+  manualDataSplits: S.number().minimum( 1 ).optional(),
+  mirrorDataSplitsWithConsumers: S.boolean().optional().default( true ),
+  customDataSplits: S.array().items( S.array().items( S.string())).optional(),
+  streams: S.string().optional(),
+  endpoint: S.string().optional(),
+  retryAfterSecs: S.number().optional(),
+  retryableStatuses: S.array().items( S.number()).default( RetryableStatuses ).optional(),
+  dataSplits: S.shape({
+    custom: S.array().items( S.string()),
+    manual: S.array().items( S.string()),
+    automatic: S.array().items( S.string()),
+  }).partial().optional(),
+});
+export type StructureSubscriptionType = typeof StructureSubscriptionSchema.type;
+
+export const StructureBrokerSubscriptionSchema = S.shape({
+  host: S.string(),
+  index: S.number(),
+  custom: S.array().items( S.string()).optional()
+});
+export type StructureBrokerSubscriptionType = typeof StructureBrokerSubscriptionSchema.type;
+
+export const StructureBrokerSchema = S.shape({
+  host: S.string(),
+  subscriptions: S.shape({}).additionalProperties(
+    S.shape({}).additionalProperties( StructureBrokerSubscriptionSchema )
+  ),
+});
+export type StructureBrokerType = typeof StructureBrokerSchema.type;
+
+export const StructureSubscriptionsSchema = S.shape({})
+  .additionalProperties( StructureSubscriptionSchema );
+
+export const StructureServicesSchema = S.shape({})
+  .additionalProperties( StructureServiceSchema );
+export type StructureServicesType = typeof StructureServicesSchema.type;
+
+export const StructureBrokersSchema = S.shape({})
+  .additionalProperties( omitFromSchema( StructureBrokerSchema, ['host']));
+
+export const StructureAggregateSchema = S.shape({
+  subscriptions: StructureSubscriptionsSchema,
+  services: StructureServicesSchema,
+  brokers: StructureBrokersSchema,
+  clusterRevision: S.number(),
+  servicesRevisionAck: S.array().items( S.string())
+});
+export type StructureAggregateType = typeof StructureAggregateSchema.type;
+
+export const AddSubscriptionsCommandSchema = S.shape({
+  subscriptions: StructureSubscriptionsSchema, doNotRebalance: S.boolean().optional()
+});
+export const EditSubscriptionCommandSchema = S.shape({
+  id: S.string(),
+  subscription: StructureSubscriptionSchema.partial(),
+  doNotRebalance: S.boolean().optional()
+});
+export const DeleteSubscriptionCommandSchema = S.shape({
+  id: S.string(),
+  doNotRebalance: S.boolean().optional()
+});
+
+export const UpsertHostCommandSchema = mergeSchemas( omitFromSchema( StructureServiceSchema, ['hosts']), S.shape({
+  service: S.string(),
+  host: S.string(),
+  doNotRebalance: S.boolean().optional()
+}));
+export type UpsertHostCommandType = typeof UpsertHostCommandSchema.type;
+
+export const RemoveHostCommandSchema = S.shape({ host: S.string() });
+
+export const SetStructureUpsertHostCommandSchema = mergeSchemas( StructureServiceSchema, S.shape({
+  service: S.string(),
+}));
+export const SetStructureCommandSchema = S.shape({
+  upsertHosts: S.array().items( UpsertHostCommandSchema ),
+  removeHosts: S.array().items( S.string()),
+  subscriptions: StructureSubscriptionsSchema.optional()
+});
+
+export const RebalanceSubscriptionsCommandSchema = S.shape({})
+  .additionalProperties( omitFromSchema( StructureBrokerSchema, ['host']));
+export type RebalanceSubscriptionsCommandType = typeof RebalanceSubscriptionsCommandSchema.type;
+
+export const RemoveBrokerCommandSchema = S.shape({ host: S.string() });
+
+export const AckStructureSchema = S.shape({ host: S.string(), revision: S.number() });
+
+export type CommandTypes = {
+  UpsertHost: typeof UpsertHostCommandSchema.type
+  RemoveHost: typeof RemoveHostCommandSchema.type
+  RebalanceSubscriptions: typeof RebalanceSubscriptionsCommandSchema.type
+  AddSubscriptions: typeof AddSubscriptionsCommandSchema.type
+  EditSubscription: typeof EditSubscriptionCommandSchema.type
+  DeleteSubscription: typeof DeleteSubscriptionCommandSchema.type
+  SetStructure: typeof SetStructureCommandSchema.type
+  AckStructure: typeof AckStructureSchema.type
+}
+
+//*******************************************
+// EVENTS
+//*******************************************
+
+export const structureEvents = {
+  HostUpserted: () => Event({
+    schema: S.shape({
+      services: StructureServicesSchema,
+      brokers: StructureBrokersSchema.optional(),
+      doNotRebalance: S.boolean().optional(),
+    })
+  }),
+  HostRemoved: () => Event({
+    schema: S.shape({
+      brokers: StructureBrokersSchema,
+      host: S.string(),
+      service: S.string()
+    })
+  }),
+  SubscriptionsRebalanced: () => Event({
+    schema: S.shape({
+      brokers: StructureBrokersSchema,
+    })
+  }),
+  SubscriptionsAdded: () => Event({
+    schema: S.shape({
+      brokers: StructureBrokersSchema.optional(),
+      subscriptions: StructureSubscriptionsSchema,
+      doNotRebalance: S.boolean().optional(),
+    })
+  }),
+  SubscriptionEdited: () => Event({
+    schema: S.shape({
+      brokers: StructureBrokersSchema.optional(),
+      subscriptions: StructureSubscriptionsSchema,
+      doNotRebalance: S.boolean().optional(),
+    })
+  }),
+  SubscriptionDeleted: () => Event({
+    schema: S.shape({
+      id: S.string(),
+      doNotRebalance: S.boolean().optional(),
+      brokers: StructureBrokersSchema.optional(),
+    })
+  }),
+  StructureSet: () => Event({
+    schema: StructureAggregateSchema
+  }),
+  StructureAcked: () => Event({
+    schema: AckStructureSchema
+  })
+};
+
+
+export const ClusterRoutesConfigSchema = S.shape({
+  clusterRoutesAggregateCollection: S.string().optional(),
+  clusterRoutesEventstoreCollection: S.string().optional(),
+  clusterRoutesEventstoreStream: S.string().optional(),
+});
+export type ClusterRoutesConfigType = typeof ClusterRoutesConfigSchema.type;
+
+export const ClusterStructureConfigSchema = S.shape({
+  structureEventstoreStream: S.string().default( 'environment' ).optional(),
+  structureAggregateCollection: S.string().default( 'cluster_infrastructure' ).optional(),
+  structureEventstoreCollection: S.string().default( 'cluster_eventstore' ).optional(),
+});
+export type ClusterStructureConfigType = typeof ClusterStructureConfigSchema.type;

package/src/configuration.ts

@@ -0,0 +1,71 @@
+import { ObjectSchema } from '@bett3r-dev/jsonschema-definer';
+import { AdapterBase, PortEmitter, PortEmitterEvents } from './ports';
+import { TypedEventEmitter } from './typedEventEmitter';
+
+export type ConfigurationPortEmitterEvents = PortEmitterEvents & {
+  argsApplied: {config: any},
+}
+
+/**
+ * Patches the configuration of the system with a specified object
+ * @param config The object to patch the configuration with
+ */
+export declare function applyConfig( config: Record<string, any> ): Promise<Record<string, any>>
+
+/**
+ * @category Main Types
+*/
+export type ConfigurationAdapter = AdapterBase & {
+  applyConfig: typeof applyConfig
+}
+
+/**
+ * Returns a configuration for an specific module in the system
+ * @category Configuration Port
+ * @param name The name of the key in the config file structure
+ * @param schema The schema of the specific configuration piece
+ */
+export declare function getModuleConfig <CONFIG extends object>( name:string, schema: ObjectSchema<CONFIG, true> | ObjectSchema<CONFIG, false> ): {
+  config: CONFIG,
+  onArgsApplied: ( callback: ( config: CONFIG ) => void ) => void
+}
+
+export type CliArgDefinition = {
+  type: 'string' | 'number' | 'boolean',
+  name: string,
+  alias?: string,
+  description?: string,
+  default?: any
+}
+
+export type CliCommandDefinition = {
+  /** The name of the command, accepts positional arguments. Use <> for required and [] for optionals. Optionals might optionally accept and array like [optional..]
+   * @example
+   * 'test <required|requiredAlias> [optional1] [optional2..]'
+  */
+  name: string,
+  alias?: string,
+  description?: string,
+  /** The descriptions for the positional arguements of the command. MUST BE SPECIFIED IN THE NAME FIRST */
+  arguments?: CliArgDefinition[],
+  handler: ( args: Record<string, any> ) => void;
+}
+
+/**
+ * @category Main Types
+*/
+export type ConfigurationType = {
+  _getConfig: () => Record<string, any>,
+  getModuleConfig: typeof getModuleConfig,
+  getModules: () => string[],
+  getArgs: () => Promise<Record<string, any>>,
+  applyArgs: () => Promise<Record<string, any>>,
+  emitter: TypedEventEmitter<ConfigurationPortEmitterEvents>,
+  configureCliArg: ( options: CliArgDefinition ) => void,
+  configureCliCommand: ( options: CliCommandDefinition ) => void,
+}
+
+/**
+ * @category Main Types
+*/
+export type ConfigurationPort = Omit<PortEmitter, 'emitter'> & ConfigurationType