@fluidframework/azure-client 0.59.3000 → 1.0.0

package/src/AzureClient.ts

@@ -23,7 +23,18 @@ import {
     RootDataObject,
 } from "@fluidframework/fluid-static";
 
-import { AzureClientProps, AzureContainerServices } from "./interfaces";
+import {
+    SummaryType,
+} from "@fluidframework/protocol-definitions";
+
+import {
+    AzureClientProps,
+    AzureConnectionConfig,
+    AzureContainerServices,
+    AzureContainerVersion,
+    AzureGetVersionsOptions,
+} from "./interfaces";
+import { isAzureRemoteConnectionConfig } from "./utils";
 import { AzureAudience } from "./AzureAudience";
 import {
     AzureUrlResolver,
@@ -33,7 +44,12 @@ import {
 /**
  * Strongly typed id for connecting to a local Azure Fluid Relay.
  */
-export const LOCAL_MODE_TENANT_ID = "local";
+const LOCAL_MODE_TENANT_ID = "local";
+const getTenantId = (connectionProps: AzureConnectionConfig): string => {
+    return isAzureRemoteConnectionConfig(connectionProps) ? connectionProps.tenantId : LOCAL_MODE_TENANT_ID;
+};
+
+const MAX_VERSION_COUNT = 5;
 
 /**
  * AzureClient provides the ability to have a Fluid object backed by the Azure Fluid Relay or,
@@ -48,14 +64,15 @@ export class AzureClient {
      * @param props - Properties for initializing a new AzureClient instance
      */
     constructor(private readonly props: AzureClientProps) {
+        // remove trailing slash from URL if any
+        props.connection.endpoint = props.connection.endpoint.replace(/\/$/, "");
         this.urlResolver = new AzureUrlResolver();
         // The local service implementation differs from the Azure Fluid Relay in blob
         // storage format. Azure Fluid Relay supports whole summary upload. Local currently does not.
-        const enableWholeSummaryUpload =
-            this.props.connection.tenantId !== LOCAL_MODE_TENANT_ID;
+        const enableWholeSummaryUpload = isAzureRemoteConnectionConfig(this.props.connection);
         this.documentServiceFactory = new RouterliciousDocumentServiceFactory(
             this.props.connection.tokenProvider,
-            { enableWholeSummaryUpload },
+            { enableWholeSummaryUpload, enableDiscovery: true },
         );
     }
 
@@ -77,29 +94,60 @@ export class AzureClient {
             config: {},
         });
 
-        const rootDataObject = await requestFluidObject<RootDataObject>(
+        const fluidContainer = await this.createFluidContainer(
             container,
-            "/",
+            this.props.connection,
         );
-        const createNewRequest = createAzureCreateNewRequest(
-            this.props.connection.orderer,
-            this.props.connection.storage,
-            this.props.connection.tenantId,
+        const services = this.getContainerServices(container);
+        return { container: fluidContainer, services };
+    }
+
+    /**
+     * Creates new detached container out of specific version of another container.
+     * @param id - Unique ID of the source container in Azure Fluid Relay.
+     * @param containerSchema - Container schema used to access data objects in the container.
+     * @param version - Unique version of the source container in Azure Fluid Relay.
+     * It defaults to latest version if parameter not provided.
+     * @returns New detached container instance along with associated services.
+     */
+    public async copyContainer(
+        id: string,
+        containerSchema: ContainerSchema,
+        version?: AzureContainerVersion,
+    ): Promise<{
+        container: IFluidContainer;
+        services: AzureContainerServices;
+    }> {
+        const loader = this.createLoader(containerSchema);
+        const url = new URL(this.props.connection.endpoint);
+        url.searchParams.append("storage", encodeURIComponent(this.props.connection.endpoint));
+        url.searchParams.append("tenantId", encodeURIComponent(getTenantId(this.props.connection)));
+        url.searchParams.append("containerId", encodeURIComponent(id));
+        const sourceContainer = await loader.resolve({ url: url.href });
+
+        if (sourceContainer.resolvedUrl === undefined) {
+            throw new Error(
+                "Source container cannot resolve URL.",
+            );
+        }
+
+        const documentService = await this.documentServiceFactory.createDocumentService(sourceContainer.resolvedUrl);
+        const storage = await documentService.connectToStorage();
+        const handle = {
+            type: SummaryType.Handle,
+            handleType: SummaryType.Tree,
+            handle: version?.id ?? "latest",
+        };
+        const tree = await storage.downloadSummary(handle);
+
+        const container = await loader.rehydrateDetachedContainerFromSnapshot(
+            JSON.stringify(tree),
         );
-        const fluidContainer = new (class extends FluidContainer {
-            async attach() {
-                if (this.attachState !== AttachState.Detached) {
-                    throw new Error(
-                        "Cannot attach container. Container is not in detached state",
-                    );
-                }
-                await container.attach(createNewRequest);
-                const resolved = container.resolvedUrl;
-                ensureFluidResolvedUrl(resolved);
-                return resolved.id;
-            }
-        })(container, rootDataObject);
 
+        const fluidContainer = await this.createFluidContainer(
+            container,
+            this.props.connection,
+        );
         const services = this.getContainerServices(container);
         return { container: fluidContainer, services };
     }
@@ -118,9 +166,9 @@ export class AzureClient {
         services: AzureContainerServices;
     }> {
         const loader = this.createLoader(containerSchema);
-        const url = new URL(this.props.connection.orderer);
-        url.searchParams.append("storage", encodeURIComponent(this.props.connection.storage));
-        url.searchParams.append("tenantId", encodeURIComponent(this.props.connection.tenantId));
+        const url = new URL(this.props.connection.endpoint);
+        url.searchParams.append("storage", encodeURIComponent(this.props.connection.endpoint));
+        url.searchParams.append("tenantId", encodeURIComponent(getTenantId(this.props.connection)));
         url.searchParams.append("containerId", encodeURIComponent(id));
         const container = await loader.resolve({ url: url.href });
         const rootDataObject = await requestFluidObject<RootDataObject>(
@@ -132,6 +180,44 @@ export class AzureClient {
         return { container: fluidContainer, services };
     }
 
+    /**
+     * Get the list of versions for specific container.
+     * @param id - Unique ID of the source container in Azure Fluid Relay.
+     * @param options - "Get" options. If options are not provided, API
+     * will assume maxCount of versions to retreive to be 5.
+     * @returns Array of available container versions.
+     */
+    public async getContainerVersions(
+        id: string,
+        options?: AzureGetVersionsOptions,
+    ): Promise<AzureContainerVersion[]> {
+        const url = new URL(this.props.connection.endpoint);
+        url.searchParams.append(
+            "storage",
+            encodeURIComponent(this.props.connection.endpoint),
+        );
+        url.searchParams.append(
+            "tenantId",
+            encodeURIComponent(getTenantId(this.props.connection)),
+        );
+        url.searchParams.append("containerId", encodeURIComponent(id));
+
+        const resolvedUrl = await this.urlResolver.resolve({ url: url.href });
+        if (!resolvedUrl) {
+            throw new Error("Unable to resolved URL");
+        }
+        const documentService =
+            await this.documentServiceFactory.createDocumentService(
+                resolvedUrl,
+            );
+        const storage = await documentService.connectToStorage();
+        const versions = await storage.getVersions(null, options?.maxCount ?? MAX_VERSION_COUNT);
+
+        return versions.map((item) => {
+            return { id: item.id, date: item.date };
+        });
+    }
+
     private getContainerServices(container: IContainer): AzureContainerServices {
         return {
             audience: new AzureAudience(container),
@@ -157,4 +243,33 @@ export class AzureClient {
             logger: this.props.logger,
         });
     }
+
+    private async createFluidContainer(
+        container: IContainer,
+        connection: AzureConnectionConfig,
+    ): Promise<FluidContainer> {
+        const createNewRequest = createAzureCreateNewRequest(
+            connection.endpoint,
+            getTenantId(connection),
+        );
+
+        const rootDataObject = await requestFluidObject<RootDataObject>(
+            container,
+            "/",
+        );
+        return new (class extends FluidContainer {
+            async attach() {
+                if (this.attachState !== AttachState.Detached) {
+                    throw new Error(
+                        "Cannot attach container. Container is not in detached state",
+                    );
+                }
+                await container.attach(createNewRequest);
+                const resolved = container.resolvedUrl;
+                ensureFluidResolvedUrl(resolved);
+                return resolved.id;
+            }
+        })(container, rootDataObject);
+    }
+    // #endregion
 }

package/src/AzureUrlResolver.ts

@@ -16,7 +16,7 @@ import {
 // InsecureTokenProvider for basic scenarios or more robust, secure providers that fulfill the
 // ITokenProvider interface
 export class AzureUrlResolver implements IUrlResolver {
-    constructor() {}
+    constructor() { }
 
     public async resolve(request: IRequest): Promise<IFluidResolvedUrl> {
         const { ordererUrl, storageUrl, tenantId, containerId } = decodeAzureUrl(
@@ -100,12 +100,11 @@ function decodeAzureUrl(urlString: string): {
 }
 
 export const createAzureCreateNewRequest = (
-    ordererUrl: string,
-    storageUrl: string,
+    endpointUrl: string,
     tenantId: string,
 ): IRequest => {
-    const url = new URL(ordererUrl);
-    url.searchParams.append("storage", encodeURIComponent(storageUrl));
+    const url = new URL(endpointUrl);
+    url.searchParams.append("storage", encodeURIComponent(endpointUrl));
     url.searchParams.append("tenantId", encodeURIComponent(tenantId));
     return {
         url: url.href,

package/src/interfaces.ts

@@ -30,28 +30,81 @@ export interface AzureClientProps {
     readonly logger?: ITelemetryBaseLogger;
 }
 
+/**
+ * Container version metadata.
+ */
+export interface AzureContainerVersion {
+    /**
+     * Version ID
+     */
+    id: string;
+
+    /**
+     * Time when version was generated.
+     * ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ
+     */
+    date?: string;
+}
+
+/**
+ * Options for "Get Container Versions" API.
+ */
+export interface AzureGetVersionsOptions {
+    /**
+     * Max number of versions
+     */
+    maxCount: number;
+}
+
+/**
+ * The type of connection.
+ * - "local" for local connections to a Fluid relay instance running on the localhost
+ * - "remote" for client connections to the Azure Fluid Relay service
+ */
+export type AzureConnectionConfigType = "local" | "remote";
+
 /**
  * Parameters for establishing a connection with the Azure Fluid Relay.
  */
 export interface AzureConnectionConfig {
     /**
-     * URI to the Azure Fluid Relay orderer endpoint
+     * The type of connection. Whether we're connecting to a remote Fluid relay server or a local instance.
      */
-    orderer: string;
+    type: AzureConnectionConfigType;
     /**
-     * URI to the Azure Fluid Relay storage endpoint
+     * URI to the Azure Fluid Relay service discovery endpoint.
      */
-    storage: string;
-    /**
-     * Unique tenant identifier
-    */
-    tenantId: "local" | string;
+    endpoint: string;
     /**
-     * Instance that provides Azure Fluid Relay endpoint tokens
+     * Instance that provides Azure Fluid Relay endpoint tokens.
      */
     tokenProvider: ITokenProvider;
 }
 
+/**
+ * Parameters for establishing a remote connection with the Azure Fluid Relay.
+ */
+export interface AzureRemoteConnectionConfig extends AzureConnectionConfig {
+    /**
+     * The type of connection. Set to a remote connection.
+     */
+    type: "remote";
+    /**
+     * Unique tenant identifier.
+     */
+    tenantId: string;
+}
+
+/**
+ * Parameters for establishing a local connection with a local instance of the Azure Fluid Relay.
+ */
+export interface AzureLocalConnectionConfig extends AzureConnectionConfig {
+    /**
+     * The type of connection. Set to a remote connection.
+     */
+    type: "local";
+}
+
 /**
  * AzureContainerServices is returned by the AzureClient alongside a FluidContainer.
  * It holds the functionality specifically tied to the Azure Fluid Relay, and how the data stored in

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/azure-client";
-export const pkgVersion = "0.59.3000";
+export const pkgVersion = "1.0.0";

package/src/utils.ts

@@ -0,0 +1,21 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+import { AzureRemoteConnectionConfig, AzureLocalConnectionConfig, AzureConnectionConfig } from "./interfaces";
+
+/**
+ * Type guard for validating a given AzureConnectionConfig is a remote connection type (AzureRemoteConnectionConfig)
+ */
+export function isAzureRemoteConnectionConfig(
+    connectionConfig: AzureConnectionConfig): connectionConfig is AzureRemoteConnectionConfig {
+    return connectionConfig.type === "remote";
+}
+
+/**
+ * Type guard for validating a given AzureConnectionConfig is a local connection type (AzureLocalConnectionConfig)
+ */
+export function isAzureLocalConnectionConfig(
+    connectionConfig: AzureConnectionConfig): connectionConfig is AzureLocalConnectionConfig {
+    return connectionConfig.type === "local";
+}