@rancher/shell 3.0.12-rc.2 → 3.0.12-rc.3

package/apis/resources/resources-api-class.ts

@@ -0,0 +1,187 @@
+import {
+  ResourceType, FindMethodOptions, FindAllMethodOptions, FindFilteredPageOptions, FindFilteredLabelSelectorOptions,
+  FindFilteredPageResponse, FindFilteredLabelSelectorResponse
+} from '@shell/apis/intf/resources-api/resource-base';
+import { ResourcesApi } from '@shell/apis/intf/resources-api/resources-api';
+import { SteveListResponse, SteveGetResponse } from '@shell/types/rancher/steve.api';
+import { Store } from 'vuex';
+
+export class ResourcesApiClassImpl implements ResourcesApi {
+  private store: Store<any>;
+
+  private storeType: 'cluster' | 'management' | string;
+
+  private surfaceError(message: string, e?: any): never {
+    console.error(`Resource API error - ${ this.storeType } - ${ message }`); // eslint-disable-line no-console
+    throw new Error(`Resource API error - ${ this.storeType } - ${ message }`, { cause: e });
+  }
+
+  private isNamespaced(resourceType: ResourceType): boolean {
+    const schema = this.store.getters[`${ this.storeType }/schemaFor`]?.(resourceType);
+
+    return !!schema?.attributes?.namespaced;
+  }
+
+  constructor(store: Store<any>, storeType: 'cluster' | 'management' | string) {
+    this.store = store;
+    this.storeType = storeType;
+  }
+
+  /**
+   * Finds a specific resource by its type and ID.
+   *
+   * @template T - The type of the resource (defaults to SteveGetResponse)
+   * @param resourceType - The type of the resource to find (use **{@link K8S}** constant). See also {@link ResourceType}.
+   * @param resourceId - The unique identifier of the resource to find. If the resource is namespaced, this should be in the format `namespace/name`.
+   * @param options - Optional find arguments
+   * @returns The found resource item or null if not found.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   *
+   * const resources = useResources();
+   *
+   * // Namespaced resource - ID must be in "namespace/name" format
+   * const pod = await resources.cluster.find(K8S.POD, 'default/my-pod-123');
+   *
+   * // Cluster-scoped resource - ID is just the name
+   * const node = await resources.cluster.find(K8S.NODE, 'worker-1');
+   * ```
+   */
+  async find<T = SteveGetResponse>(
+    resourceType: ResourceType,
+    resourceId: string,
+    options?: FindMethodOptions
+  ): Promise<T | null> {
+    if (this.isNamespaced(resourceType) && !resourceId.includes('/')) {
+      this.surfaceError(`Resource "${ resourceType }" is namespaced. The resourceId must be in "namespace/name" format, but received "${ resourceId }"`);
+    }
+
+    try {
+      const resource = await this.store.dispatch(`${ this.storeType }/find`, {
+        type: resourceType,
+        id:   resourceId,
+        opt:  options || {}
+      });
+
+      return (resource as T) ?? null;
+    } catch (e: unknown) {
+      this.surfaceError(`Failed to find resource ${ resourceType }/${ resourceId }: ${ (e as Error).message }`, e);
+    }
+  }
+
+  /**
+   * Finds resources using pagination mode with server-side filtering, sorting, and pagination.
+   *
+   * Requires `ui-sql-cache` to be enabled.
+   *
+   * @template T - The type of the resources (defaults to SteveListResponse)
+   * @param resourceType - The type of the resources to find
+   * @param options - Pagination options with server-side filtering and sorting
+   * @returns Response containing resource items (may be transient if requested, otherwise cached array)
+   * @throws If pagination mode is requested but `ui-sql-cache` is not enabled
+   */
+  findFiltered<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options: FindFilteredPageOptions
+  ): Promise<FindFilteredPageResponse<T>>;
+
+  /**
+   * Finds resources using label selector matching.
+   *
+   * Filters resources by Kubernetes labels. The store automatically handles pagination:
+   * - If `ui-sql-cache` is enabled: uses server-side pagination
+   * - Otherwise: uses native Kubernetes API pagination
+   *
+   * @template T - The type of the resources (defaults to SteveListResponse)
+   * @param resourceType - The type of the resources to find
+   * @param options - Label selector options for filtering
+   * @returns Response containing resource items (may be transient if requested, otherwise cached array)
+   */
+  findFiltered<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options: FindFilteredLabelSelectorOptions
+  ): Promise<FindFilteredLabelSelectorResponse<T>>;
+
+  /**
+   * @internal Implementation - use one of the overloads above
+   */
+  async findFiltered<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options: FindFilteredPageOptions | FindFilteredLabelSelectorOptions
+  ): Promise<FindFilteredPageResponse<T> | FindFilteredLabelSelectorResponse<T>> {
+    try {
+      if ('pagination' in options) { // pagination mode
+        const canPaginate = this.store.getters[`${ this.storeType }/paginationEnabled`]?.(resourceType);
+
+        if (!canPaginate) {
+          return this.surfaceError('findFiltered requests with FindFilteredPageOptions are only supported when ui-sql-cache is enabled');
+        }
+
+        const safeOption = options as FindFilteredPageOptions;
+        const response = await this.store.dispatch(`${ this.storeType }/findPage`, {
+          type: resourceType,
+          opt:  safeOption
+        });
+
+        return response as FindFilteredPageResponse<T>;
+      } else if ('labelSelector' in options) { // label selector mode
+        const safeOption = options as FindFilteredLabelSelectorOptions;
+        const { labelSelector, namespaced, ...rest } = safeOption;
+        const resources = await this.store.dispatch(`${ this.storeType }/findLabelSelector`, {
+          type:     resourceType,
+          matching: {
+            namespace: namespaced,
+            labelSelector
+          },
+          opt: rest
+        });
+
+        return resources as FindFilteredLabelSelectorResponse<T>;
+      } else {
+        return this.surfaceError('findFiltered request was made with unknown options');
+      }
+    } catch (e: unknown) {
+      this.surfaceError(`Failed to find filtered resources ${ resourceType }: ${ (e as Error).message }`, e);
+    }
+  }
+
+  /**
+   * Fetches all resources of a specific type with advanced options.
+   * This method provides additional capabilities like incremental loading and namespace filtering.
+   *
+   * @template T - The type of the resources (defaults to SteveListResponse)
+   * @param resourceType - The type of the resources to find (use **{@link K8S}** constant). See also {@link ResourceType}.
+   * @param options - Optional advanced fetch options (incremental loading, namespace filtering, etc.)
+   * @returns An array of resource items or an empty array if none are found.
+   *
+   * @example
+   * ```ts
+   * import { useResources, K8S } from '@shell/apis';
+   * import type { Pod } from '@shell/types/resources';
+   *
+   * const resources = useResources();
+   *
+   * // Fetch all pods in specific namespaces
+   * const pods = await resources.cluster.findAll<Pod>(K8S.POD, {
+   *   namespaced: ['default', 'kube-system']
+   * });
+   * ```
+   */
+  async findAll<T = SteveListResponse>(
+    resourceType: ResourceType,
+    options?: FindAllMethodOptions
+  ): Promise<T[]> {
+    try {
+      const resources = await this.store.dispatch(`${ this.storeType }/findAll`, {
+        type: resourceType,
+        opt:  options || {}
+      });
+
+      return resources as T[];
+    } catch (e: unknown) {
+      this.surfaceError(`Failed to find all resources ${ resourceType }: ${ (e as Error).message }`, e);
+    }
+  }
+}

package/apis/shell/__tests__/proxy.test.ts

@@ -0,0 +1,369 @@
+// proxy.test.ts
+
+import {
+  describe, it, expect, jest, beforeEach
+} from '@jest/globals';
+import { ProxyApiImpl, createDepaginator } from '../proxy';
+import { Store } from 'vuex';
+
+const PROXY_PREFIX = '/meta/proxy/';
+
+describe('proxyApiImpl', () => {
+  let mockStore: Store<any>;
+  let mockDispatch: jest.Mock;
+  let proxyApi: ProxyApiImpl;
+
+  beforeEach(() => {
+    mockDispatch = jest.fn() as any;
+    mockStore = { dispatch: mockDispatch } as any;
+    proxyApi = new ProxyApiImpl(mockStore);
+  });
+
+  // ---------------------------------------------------------------------------
+  // prepareRequest — URL building
+  // ---------------------------------------------------------------------------
+
+  describe('prepareRequest: URL building', () => {
+    it('should prepend /meta/proxy/ to a url, stripping the https scheme', () => {
+      const { url } = proxyApi.prepareRequest({ url: new URL('https://api.example.com/v1/things') });
+
+      expect(url).toBe(`${ PROXY_PREFIX }api.example.com/v1/things`);
+    });
+
+    it('should preserve http:/ (one slash) for plain-HTTP urls', () => {
+      const { url } = proxyApi.prepareRequest({ url: new URL('http://api.example.com:1234/v1/things') });
+
+      expect(url).toBe(`${ PROXY_PREFIX }http:/api.example.com:1234/v1/things`);
+    });
+
+    it('should preserve query params', () => {
+      const input = new URL('https://api.example.com/v1/things');
+
+      input.searchParams.set('region', 'us-east-1');
+      input.searchParams.set('page', '2');
+
+      const { url } = proxyApi.prepareRequest({ url: input });
+
+      expect(url).toBe(`${ PROXY_PREFIX }api.example.com/v1/things?region=us-east-1&page=2`);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // prepareRequest — header building
+  // ---------------------------------------------------------------------------
+
+  describe('prepareRequest: header building', () => {
+    it('should set Accept to application/json by default', () => {
+      const { headers } = proxyApi.prepareRequest({ url: new URL('https://api.example.com') });
+
+      expect(headers['Accept']).toBe('application/json');
+    });
+
+    it('should override Accept when accept option is provided', () => {
+      const { headers } = proxyApi.prepareRequest({ url: new URL('https://api.example.com'), accept: 'text/plain' });
+
+      expect(headers['Accept']).toBe('text/plain');
+    });
+
+    it('should merge caller-supplied headers', () => {
+      const { headers } = proxyApi.prepareRequest({
+        url:     new URL('https://api.example.com'),
+        headers: { 'X-Custom': 'value' },
+      });
+
+      expect(headers['X-Custom']).toBe('value');
+    });
+
+    it('should set x-api-auth-header with Bearer scheme for a token by default', () => {
+      const { headers } = proxyApi.prepareRequest({
+        url:            new URL('https://api.example.com'),
+        authentication: { token: 'my-token' },
+      });
+
+      expect(headers['x-api-auth-header']).toBe('Bearer my-token');
+    });
+
+    it('should use the supplied authSigner as the scheme for a token', () => {
+      const { headers } = proxyApi.prepareRequest({
+        url:            new URL('https://api.example.com'),
+        authentication: { token: 'encoded==', authSigner: 'basic' },
+      });
+
+      expect(headers['x-api-auth-header']).toBe('basic encoded==');
+    });
+
+    it('should set x-api-cattleauth-header with signer and credID', () => {
+      const { headers } = proxyApi.prepareRequest({
+        url:            new URL('https://api.example.com'),
+        authentication: {
+          id:            'cattle-global-data:my-cred',
+          authSigner:    'bearer',
+          passwordField: 'token',
+        },
+      });
+
+      expect(headers['x-api-cattleauth-header']).toContain('bearer ');
+      expect(headers['x-api-cattleauth-header']).toContain('credID=cattle-global-data:my-cred');
+      expect(headers['x-api-cattleauth-header']).toContain('passwordField=token');
+    });
+
+    it('should include usernameField in x-api-cattleauth-header when provided', () => {
+      const { headers } = proxyApi.prepareRequest({
+        url:            new URL('https://api.example.com'),
+        authentication: {
+          id:            'cattle-global-data:my-cred',
+          authSigner:    'basic',
+          usernameField: 'username',
+          passwordField: 'password',
+        },
+      });
+
+      expect(headers['x-api-cattleauth-header']).toContain('usernameField=username');
+      expect(headers['x-api-cattleauth-header']).toContain('passwordField=password');
+    });
+
+    it('should not set x-api-cattleauth-header when no authentication is provided', () => {
+      const { headers } = proxyApi.prepareRequest({ url: new URL('https://api.example.com') });
+
+      expect(headers['x-api-cattleauth-header']).toBeUndefined();
+    });
+
+    it('should not set x-api-auth-header when no authentication is provided', () => {
+      const { headers } = proxyApi.prepareRequest({ url: new URL('https://api.example.com') });
+
+      expect(headers['x-api-auth-header']).toBeUndefined();
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // request
+  // ---------------------------------------------------------------------------
+
+  describe('request', () => {
+    it('should dispatch management/request with the built url and headers', async() => {
+      mockDispatch.mockResolvedValue({ data: [] });
+
+      await proxyApi.request({ url: new URL('https://api.example.com/v1/items') });
+
+      expect(mockDispatch).toHaveBeenCalledWith(
+        'management/request',
+        expect.objectContaining({
+          url:                  `${ PROXY_PREFIX }api.example.com/v1/items`,
+          redirectUnauthorized: false,
+        }),
+        { root: true }
+      );
+    });
+
+    it('should pass method through to management/request', async() => {
+      mockDispatch.mockResolvedValue({});
+
+      await proxyApi.request({ url: new URL('https://api.example.com/token'), method: 'POST' });
+
+      expect(mockDispatch).toHaveBeenCalledWith(
+        'management/request',
+        expect.objectContaining({ method: 'POST' }),
+        { root: true }
+      );
+    });
+
+    it('should return the response directly when no postProcess is set', async() => {
+      const mockResponse = { items: ['a', 'b'] };
+
+      mockDispatch.mockResolvedValue(mockResponse);
+
+      const result = await proxyApi.request({ url: new URL('https://api.example.com/items') });
+
+      expect(result).toStrictEqual(mockResponse);
+    });
+
+    it('should call postProcess with the response and return its result', async() => {
+      const raw = { items: ['a'] };
+      const processed = { items: ['a', 'b'] };
+
+      mockDispatch.mockResolvedValue(raw);
+      const postProcess = jest.fn().mockResolvedValue(processed) as jest.Mock;
+
+      const result = await proxyApi.request({ url: new URL('https://api.example.com/items'), postProcess });
+
+      expect(postProcess).toHaveBeenCalledWith(raw);
+      expect(result).toStrictEqual(processed);
+    });
+
+    it('createDepaginator: should follow next links and merge results', async() => {
+      const page1 = {
+        items: ['a', 'b'],
+        links: { pages: { next: 'https://api.example.com/v1/items?page=2' } },
+      };
+      const page2 = {
+        items: ['c'],
+        links: { pages: { next: null } },
+      };
+
+      mockDispatch
+        .mockResolvedValueOnce(page1)
+        .mockResolvedValueOnce(page2);
+
+      const baseOptions = { url: new URL('https://api.example.com/v1/items') };
+      const result = await proxyApi.request({
+        ...baseOptions,
+        postProcess: createDepaginator(proxyApi, baseOptions, { mergeKey: 'items' }),
+      });
+
+      expect(result.items).toStrictEqual(['a', 'b', 'c']);
+      expect(mockDispatch).toHaveBeenCalledTimes(2);
+    });
+
+    it('createDepaginator: should use a custom nextUrlPath when provided', async() => {
+      const page1 = {
+        data:   ['x'],
+        paging: { next: 'https://api.example.com/v1/things?cursor=abc' },
+      };
+      const page2 = {
+        data:   ['y'],
+        paging: { next: null },
+      };
+
+      mockDispatch
+        .mockResolvedValueOnce(page1)
+        .mockResolvedValueOnce(page2);
+
+      const baseOptions = { url: new URL('https://api.example.com/v1/things') };
+      const result = await proxyApi.request({
+        ...baseOptions,
+        postProcess: createDepaginator(proxyApi, baseOptions, {
+          nextUrlPath: 'paging.next',
+          mergeKey:    'data',
+        }),
+      });
+
+      expect(result.data).toStrictEqual(['x', 'y']);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // allowDomains
+  // ---------------------------------------------------------------------------
+
+  describe('allowDomains', () => {
+    it('should dispatch management/create with the correct type and routes', async() => {
+      const mockSave = jest.fn().mockResolvedValue({ spec: { routes: [] } });
+
+      mockDispatch.mockResolvedValue({ save: mockSave });
+
+      await proxyApi.allowDomains(['api.example.com', '%.amazonaws.com'], 'my-cr');
+
+      expect(mockDispatch).toHaveBeenCalledWith('management/create', {
+        type:     'management.cattle.io.proxyEndpoint',
+        metadata: { name: 'my-cr' },
+        spec:     {
+          routes: [
+            { domain: 'api.example.com' },
+            { domain: '%.amazonaws.com' },
+          ],
+        },
+      });
+
+      expect(mockSave).toHaveBeenCalledTimes(1);
+    });
+
+    it('should use an generateName when none is supplied', async() => {
+      const mockSave = jest.fn().mockResolvedValue({});
+
+      mockDispatch.mockResolvedValue({ save: mockSave });
+
+      await proxyApi.allowDomains(['api.example.com']);
+
+      expect(mockDispatch).toHaveBeenCalledWith('management/create', expect.objectContaining({
+        metadata: { generateName: 'endpoints-' }, spec: { routes: [{ domain: 'api.example.com' }] }, type: 'management.cattle.io.proxyEndpoint'
+      }));
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // isDomainAllowed
+  // ---------------------------------------------------------------------------
+
+  describe('isDomainAllowed', () => {
+    it('should return true when the domain is found in a ProxyEndpoint CR', async() => {
+      mockDispatch.mockResolvedValue([
+        { spec: { routes: [{ domain: 'api.example.com' }, { domain: 'other.example.com' }] } },
+      ]);
+
+      const result = await proxyApi.isDomainAllowed('api.example.com');
+
+      expect(result).toBe(true);
+    });
+
+    it('should match case-insensitively', async() => {
+      mockDispatch.mockResolvedValue([
+        { spec: { routes: [{ domain: 'API.EXAMPLE.COM' }] } },
+      ]);
+
+      const result = await proxyApi.isDomainAllowed('api.example.com');
+
+      expect(result).toBe(true);
+    });
+
+    it('should return false when the domain is not found in any CR', async() => {
+      mockDispatch.mockResolvedValue([
+        { spec: { routes: [{ domain: 'other.example.com' }] } },
+      ]);
+
+      const result = await proxyApi.isDomainAllowed('api.example.com');
+
+      expect(result).toBe(false);
+    });
+
+    it('should return false when there are no ProxyEndpoint CRs', async() => {
+      mockDispatch.mockResolvedValue([]);
+
+      const result = await proxyApi.isDomainAllowed('api.example.com');
+
+      expect(result).toBe(false);
+    });
+
+    it('should return false when a CR has no routes', async() => {
+      mockDispatch.mockResolvedValue([{ spec: {} }]);
+
+      const result = await proxyApi.isDomainAllowed('api.example.com');
+
+      expect(result).toBe(false);
+    });
+  });
+
+  // ---------------------------------------------------------------------------
+  // hasProxyEndpoint
+  // ---------------------------------------------------------------------------
+
+  describe('hasProxyEndpoint', () => {
+    it('should return true when management/find resolves', async() => {
+      mockDispatch.mockResolvedValue({ metadata: { name: 'my-cr' } });
+
+      const result = await proxyApi.hasProxyEndpoint('my-cr');
+
+      expect(result).toBe(true);
+      expect(mockDispatch).toHaveBeenCalledWith('management/find', {
+        type: 'management.cattle.io.proxyEndpoint',
+        id:   'my-cr',
+        opt:  { force: false },
+      });
+    });
+
+    it('should return false when management/find rejects with status 404', async() => {
+      mockDispatch.mockRejectedValue({ status: 404 });
+
+      const result = await proxyApi.hasProxyEndpoint('missing-cr');
+
+      expect(result).toBe(false);
+    });
+
+    it('should re-throw errors that are not 404', async() => {
+      const serverError = { status: 500, message: 'Internal Server Error' };
+
+      mockDispatch.mockRejectedValue(serverError);
+
+      await expect(proxyApi.hasProxyEndpoint('my-cr')).rejects.toStrictEqual(serverError);
+    });
+  });
+});

package/apis/shell/index.ts

@@ -1,23 +1,26 @@
 import { Store } from 'vuex';
 import {
-  ModalApi, ShellApi, SlideInApi, NotificationApi, SystemApi
+  ModalApi, ShellApi, SlideInApi, NotificationApi, SystemApi, ProxyApi
 } from '@shell/apis/intf/shell';
 import { ModalApiImpl } from './modal';
 import { SlideInApiImpl } from './slide-in';
 import { NotificationApiImpl } from './notifications';
 import { SystemApiImpl } from './system';
+import { ProxyApiImpl } from './proxy';
 
 export class ShellApiImpl implements ShellApi {
   private modalApi: ModalApi;
   private slideInApi: SlideInApi;
   private notificationApi: NotificationApi;
   private systemApi: SystemApi;
+  private proxyApi: ProxyApi;
 
   constructor(store: Store<any>) {
     this.modalApi = new ModalApiImpl(store);
     this.slideInApi = new SlideInApiImpl(store);
     this.notificationApi = new NotificationApiImpl(store);
     this.systemApi = new SystemApiImpl(store);
+    this.proxyApi = new ProxyApiImpl(store);
   }
 
   get modal(): ModalApi {
@@ -35,4 +38,8 @@ export class ShellApiImpl implements ShellApi {
   get system(): SystemApi {
     return this.systemApi;
   }
+
+  get proxy(): ProxyApi {
+    return this.proxyApi;
+  }
 }

package/apis/shell/modal.ts

@@ -14,9 +14,12 @@ export class ModalApiImpl implements ModalApi {
    *
    * Example:
    * ```ts
+   * import { useShell } from '@shell/apis';
    * import MyCustomModal from '@/components/MyCustomModal.vue';
    *
-   * this.$shell.modal.open(MyCustomModal, {
+   * const shell = useShell();
+   *
+   * shell.modal.open(MyCustomModal, {
    *   props: { title: 'Hello Modal' }
    * });
    * ```

package/apis/shell/notifications.ts

@@ -14,12 +14,13 @@ export class NotificationApiImpl implements NotificationApi {
    *
    * Example:
    * ```ts
+   * import { useShell } from '@shell/apis';
    * import { NotificationLevel } from '@shell/types/notifications';
    *
-   * this.$shell.notification.send(NotificationLevel.Success, 'Some notification title', 'Hello world! Success!', {})
-   * ```
+   * const shell = useShell();
    *
-   * For usage with the Composition API check usage guide [here](../../shell-api#using-composition-api-in-vue).
+   * shell.notification.send(NotificationLevel.Success, 'Some notification title', 'Hello world! Success!', {})
+   * ```
    *
    * @param level The `level` specifies the importance of the notification and determines the icon that is shown in the notification
    * @param title The notification title
@@ -45,10 +46,12 @@ export class NotificationApiImpl implements NotificationApi {
    *
    * Example:
    * ```ts
-   * this.$shell.notification.updateProgress('some-notification-id', 80)
-   * ```
+   * import { useShell } from '@shell/apis';
    *
-   * For usage with the Composition API check usage guide [here](../../shell-api#using-composition-api-in-vue).
+   * const shell = useShell();
+   *
+   * shell.notification.updateProgress('some-notification-id', 80)
+   * ```
    *
    * @param notificationId Unique ID for the notification
    * @param progress Progress (0-100) for notifications of type `Task`