Merge pull request #316 from weaviate/feat/collection-alias

Add `alias` namespace with functions for managing collection aliases.

Author: bevzzz

src/alias/index.ts

@@ -0,0 +1,79 @@
+import { ConnectionREST } from '../index.js';
+import { WeaviateAlias, WeaviateAliasResponse } from '../openapi/types.js';
+import { Alias, AliasListAllOptions, CreateAliasArgs, UpdateAliasArgs } from './types.js';
+
+export interface Aliases {
+  /**
+   * Create alias for a collection.
+   *
+   * The collection must exist prior to aliasing it.
+   * One alias cannot be created for multiple collections simultaneously.
+   *
+   * @param {string} args.collection Original collection name.
+   * @param {string} args.alias Alias for collection.
+   * @returns {Promise<void>} Awaitable promise.
+   * */
+  create: (args: CreateAliasArgs) => Promise<void>;
+
+  /**
+   * List all aliases defined in the schema.
+   *
+   * @param {string | undefined} [opts.collection] Get all aliases defined for this collection.
+   * @returns {Promise<Alias[] | undefined>} An array of aliases.
+   */
+  listAll: (opts?: AliasListAllOptions) => Promise<Alias[] | undefined>;
+
+  /**
+   * Get information about an alias.
+   *
+   * @param {string} alias Alias to fetch.
+   * @return {Promise<Alias>} Alias definition.
+   */
+  get: (alias: string) => Promise<Alias>;
+
+  /**
+   * Replace target collection the alias points to.
+   *
+   * To change the alias that points to the collection,
+   * delete the alias and create a new one.
+   *
+   * @param {string} args.alias Alias to update.
+   * @param {string} args.collection New collection the alias should point to.
+   * @return {Promise<void>} Awaitable promise.
+   */
+  update: (args: UpdateAliasArgs) => Promise<void>;
+
+  /**
+   * Delete a collection alias.
+   *
+   * @param {string} alias Alias definition to delete.
+   * @return {Promise<void>} Awaitable promise.
+   */
+  delete: (alias: string) => Promise<void>;
+}
+
+const alias = (connection: ConnectionREST): Aliases => {
+  return {
+    create: (args: CreateAliasArgs) =>
+      connection.postReturn<WeaviateAlias, void>(`/aliases/`, { ...args, class: args.collection }),
+    listAll: (opts?: AliasListAllOptions) =>
+      connection
+        .get<WeaviateAliasResponse>(
+          `/aliases${opts?.collection !== undefined ? '/?class=' + opts.collection : ''}`
+        )
+        .then((aliases) =>
+          aliases.aliases !== undefined
+            ? aliases.aliases.map((alias) => ({ alias: alias.alias, collection: alias.class }))
+            : []
+        ),
+    get: (alias: string) =>
+      connection
+        .get<WeaviateAlias>(`/aliases/${alias}`)
+        .then((alias) => ({ alias: alias.alias!, collection: alias.class! })),
+    update: (args: UpdateAliasArgs) =>
+      connection.put(`/aliases/${args.alias}`, { class: args.newTargetCollection }),
+    delete: (alias: string) => connection.delete(`/aliases/${alias}`, null),
+  };
+};
+
+export default alias;

src/alias/journey.test.ts

@@ -0,0 +1,53 @@
+import weaviate, { WeaviateClient } from '..';
+import { requireAtLeast } from '../../test/version';
+import { Alias } from './types';
+
+requireAtLeast(1, 32, 0).describe('manages collection aliases', () => {
+  let client: WeaviateClient;
+  const collectionsWithAliases = ['PaulHewson', 'GeorgeBarnes', 'ColsonBaker'];
+
+  beforeAll(async () => {
+    client = await weaviate.connectToLocal();
+    await Promise.all(collectionsWithAliases.map(client.collections.delete));
+    await Promise.all(collectionsWithAliases.map((name) => client.collections.create({ name })));
+  });
+
+  it('should create alias', () => {
+    return Promise.all([
+      client.alias.create({ collection: 'PaulHewson', alias: 'Bono' }),
+      client.alias.create({ collection: 'GeorgeBarnes', alias: 'MachineGunKelly' }),
+    ])
+      .then(() => client.alias.listAll())
+      .then((aliases) => {
+        expect(aliases).not.toBeUndefined();
+        expect(aliases).toHaveLength(2);
+        expect(aliases).toEqual<Alias[]>([
+          { collection: 'PaulHewson', alias: 'Bono' },
+          { collection: 'GeorgeBarnes', alias: 'MachineGunKelly' },
+        ]);
+      });
+  });
+
+  it('should update alias', () => {
+    return client.alias
+      .update({ alias: 'MachineGunKelly', newTargetCollection: 'ColsonBaker' })
+      .then(() => client.alias.get('MachineGunKelly'))
+      .then((alias) => {
+        expect(alias.collection).toEqual('ColsonBaker');
+      });
+  });
+
+  it('should delete alias Bono', () => {
+    return client.alias
+      .delete('Bono')
+      .then(() => client.alias.listAll({ collection: 'PaulHewson' }))
+      .then((aliases) => expect(aliases).toEqual([]));
+  });
+
+  it('should delete alias MachineGunKelly', () => {
+    return client.alias
+      .delete('MachineGunKelly')
+      .then(() => client.alias.listAll({ collection: 'ColsonBaker' }))
+      .then((aliases) => expect(aliases).toEqual([]));
+  });
+});

src/alias/types.ts

@@ -0,0 +1,18 @@
+export type Alias = {
+  collection: string;
+  alias: string;
+};
+
+export type CreateAliasArgs = {
+  collection: string;
+  alias: string;
+};
+
+export type UpdateAliasArgs = {
+  newTargetCollection: string;
+  alias: string;
+};
+
+export type AliasListAllOptions = {
+  collection?: string | undefined;
+};

src/index.ts

@@ -38,6 +38,7 @@ import { LiveChecker, OpenidConfigurationGetter, ReadyChecker } from './misc/ind
 
 import weaviateV2 from './v2/index.js';
 
+import alias, { Aliases } from './alias/index.js';
 import filter from './collections/filters/index.js';
 import { ConsistencyLevel } from './data/replication.js';
 import users, { Users } from './users/index.js';
@@ -102,6 +103,7 @@ export type ClientParams = {
 };
 
 export interface WeaviateClient {
+  alias: Aliases;
   backup: Backup;
   cluster: Cluster;
   collections: Collections;
@@ -224,6 +226,7 @@ async function client(params: ClientParams): Promise<WeaviateClient> {
   });
 
   const ifc: WeaviateClient = {
+    alias: alias(connection),
     backup: backup(connection),
     cluster: cluster(connection),
     collections: collections(connection, dbVersionSupport),

src/openapi/types.ts

@@ -74,3 +74,8 @@ export type WeaviateUserType = definitions['UserTypeOutput'];
 export type WeaviateUserTypeInternal = definitions['UserTypeInput'];
 export type WeaviateUserTypeDB = definitions['DBUserInfo']['dbUserType'];
 export type WeaviateAssignedUser = operations['getUsersForRole']['responses']['200']['schema'][0];
+// Alias
+export type WeaviateAlias = definitions['Alias'];
+export type WeaviateAliasResponse = {
+  aliases?: Required<Exclude<definitions['AliasResponse']['aliases'], undefined>[0]>[] | undefined;
+};

src/roles/index.ts

@@ -5,6 +5,7 @@ import {
   Role as WeaviateRole,
 } from '../openapi/types.js';
 import {
+  AliasPermission,
   BackupsPermission,
   ClusterPermission,
   CollectionsPermission,
@@ -150,6 +151,33 @@ const roles = (connection: ConnectionREST): Roles => {
 };
 
 export const permissions = {
+  /**
+   * Create a set of permissions specific to Weaviate's collection aliasing functionality.
+   *
+   * @param {string | string[]} [args.alias] Aliases that will be associated with these permissions.
+   * @returns {AliasPermission[]} The permissions for the specified aliases.
+   */
+  aliases: (args: {
+    alias: string | string[];
+    collection: string | string[];
+    create?: boolean;
+    read?: boolean;
+    update?: boolean;
+    delete?: boolean;
+  }): AliasPermission[] => {
+    const aliases = Array.isArray(args.alias) ? args.alias : [args.alias];
+    const collections = Array.isArray(args.collection) ? args.collection : [args.collection];
+    const combinations = aliases.flatMap((alias) => collections.map((collection) => ({ alias, collection })));
+    return combinations.map(({ collection, alias }) => {
+      const out: AliasPermission = { alias, collection, actions: [] };
+      if (args.create) out.actions.push('create_aliases');
+      if (args.read) out.actions.push('read_aliases');
+      if (args.update) out.actions.push('update_aliases');
+      if (args.delete) out.actions.push('delete_aliases');
+      return out;
+    });
+  },
+
   /**
    * Create a set of permissions specific to Weaviate's backup functionality.
    *

src/roles/integration.test.ts

@@ -16,9 +16,11 @@ type TestCase = {
   roleName: string;
   permissions: Permission[];
   expected: Role;
+  requireVersion?: [number, number, number];
 };
 
 const emptyPermissions = {
+  aliasPermissions: [],
   backupsPermissions: [],
   clusterPermissions: [],
   collectionsPermissions: [],
@@ -277,6 +279,23 @@ const testCases: TestCase[] = [
       usersPermissions: [{ users: 'some-user', actions: ['assign_and_revoke_users', 'read_users'] }],
     },
   },
+  {
+    roleName: 'aliases',
+    requireVersion: [1, 32, 0],
+    permissions: weaviate.permissions.aliases({
+      alias: 'SomeAlias',
+      collection: 'SomeCollection',
+      create: true,
+      delete: true,
+    }),
+    expected: {
+      name: 'aliases',
+      ...emptyPermissions,
+      aliasPermissions: [
+        { alias: 'SomeAlias', collection: 'SomeCollection', actions: ['create_aliases', 'delete_aliases'] },
+      ],
+    },
+  },
 ];
 
 requireAtLeast(1, 29, 0).describe('Integration testing of the roles namespace', () => {
@@ -345,11 +364,14 @@ requireAtLeast(1, 29, 0).describe('Integration testing of the roles namespace',
 
   describe('should be able to create roles using the permissions factory', () => {
     testCases.forEach((testCase) => {
-      it(`with ${testCase.roleName} permissions`, async () => {
-        await client.roles.create(testCase.roleName, testCase.permissions);
-        const role = await client.roles.byName(testCase.roleName);
-        expect(role).toEqual(testCase.expected);
-      });
+      (testCase.requireVersion !== undefined ? requireAtLeast(...testCase.requireVersion).it : it)(
+        `with ${testCase.roleName} permissions`,
+        async () => {
+          await client.roles.create(testCase.roleName, testCase.permissions);
+          const role = await client.roles.byName(testCase.roleName);
+          expect(role).toEqual(testCase.expected);
+        }
+      );
     });
   });
 

src/roles/types.ts

@@ -1,5 +1,9 @@
 import { Action, WeaviateUserType } from '../openapi/types.js';
 
+export type AliasAction = Extract<
+  Action,
+  'create_aliases' | 'read_aliases' | 'update_aliases' | 'delete_aliases'
+>;
 export type BackupsAction = Extract<Action, 'manage_backups'>;
 export type ClusterAction = Extract<Action, 'read_cluster'>;
 export type CollectionsAction = Extract<
@@ -27,6 +31,12 @@ export type UserAssignment = {
   userType: WeaviateUserType;
 };
 
+export type AliasPermission = {
+  alias: string;
+  collection: string;
+  actions: AliasAction[];
+};
+
 export type BackupsPermission = {
   collection: string;
   actions: BackupsAction[];
@@ -71,6 +81,7 @@ export type UsersPermission = {
 
 export type Role = {
   name: string;
+  aliasPermissions: AliasPermission[];
   backupsPermissions: BackupsPermission[];
   clusterPermissions: ClusterPermission[];
   collectionsPermissions: CollectionsPermission[];
@@ -82,6 +93,7 @@ export type Role = {
 };
 
 export type Permission =
+  | AliasPermission
   | BackupsPermission
   | ClusterPermission
   | CollectionsPermission