@hot-updater/azure 0.0.0-stage → 1.0.2

package/dist/index.d.cts

@@ -0,0 +1,71 @@
+import { TokenCredential } from "@azure/core-auth";
+import { StorageSharedKeyCredential } from "@azure/storage-blob";
+import { EngineDatabase, PluginTables, StorageAdapter, StorageAdapterWith } from "@hot-updater/plugin-core";
+import { CosmosClientOptions } from "@azure/cosmos";
+//#region src/azureBlobStorage.d.ts
+/** The account to connect to: its connection string, or its Blob endpoint and a credential. */
+type AzureBlobConnection = {
+  readonly connectionString: string;
+} | {
+  /** The Blob service endpoint, such as `https://<account>.blob.core.windows.net`. */
+  readonly accountUrl: string;
+  /** An account key, or a Microsoft Entra identity such as `DefaultAzureCredential`. */
+  readonly credential: StorageSharedKeyCredential | TokenCredential;
+};
+type AzureBlobStorageConfig = AzureBlobConnection & {
+  /** The Blob container that keeps the bundles. */
+  readonly containerName: string;
+  /** Base path where bundles will be stored in the container. */
+  readonly basePath?: string;
+  /**
+   * The URL devices download an object from, such as a CDN's. Without it, a
+   * read-only SAS URL that expires in an hour.
+   */
+  readonly getDownloadUrl?: StorageAdapter["getDownloadUrl"];
+};
+type AzureBlobStorageOperations = "put" | "get" | "getDownloadUrl" | "exists" | "delete" | "listObjects" | "deleteObjects";
+/**
+ * Bundles in an Azure Blob Storage container. Without `getDownloadUrl`,
+ * devices download through SAS URLs: signed with the account key when the
+ * connection has one, otherwise with a user delegation key, which needs the
+ * identity's Storage Blob Delegator role.
+ */
+declare function azureBlobStorage(config: AzureBlobStorageConfig): StorageAdapterWith<AzureBlobStorageOperations>;
+//#endregion
+//#region src/cosmosDatabase.d.ts
+/**
+ * The client's options: the account's `connectionString`, or its
+ * `endpoint` with a `key` or Microsoft Entra `aadCredentials`. Reads must
+ * be strongly consistent, so `consistencyLevel` takes only `"Strong"`.
+ */
+type CosmosDatabaseConfig = Omit<CosmosClientOptions, "consistencyLevel"> & {
+  readonly consistencyLevel?: "Strong";
+  /** The database the container lives in. @default "hot-updater" */
+  readonly databaseId?: string;
+  /** The one container the database keeps its items in. @default "hot_updater_v1" */
+  readonly containerId?: string;
+  /**
+   * Cosmos DB bills each item a write touches, so Insights' aggregates are
+   * batched: through log rows a compaction merges (the default), or
+   * `{ mode: "memory" }` on a long-lived server. `false` commits them with
+   * each event.
+   */
+  readonly aggregateBatching?: EngineDatabase["aggregateBatching"] | false;
+};
+/**
+ * Creates the database and the container when they are missing, refusing a
+ * container of another storage layout or another app's items, and writes
+ * the schema settings of core and `plugins`, the plugins the server runs,
+ * which the database checks before its first read. `hot-updater init` runs
+ * it with the managed server's plugins.
+ */
+declare const migrateCosmosDatabase: (config: CosmosDatabaseConfig, plugins?: readonly PluginTables[]) => Promise<void>;
+/**
+ * Hot Updater's database in one Azure Cosmos DB for NoSQL container,
+ * through the storage engine. Every item shares one logical partition, so a
+ * write commits as one transactional batch; that partition holds at most
+ * 20 GB.
+ */
+declare const cosmosDatabase: (config: CosmosDatabaseConfig) => EngineDatabase;
+//#endregion
+export { AzureBlobConnection, AzureBlobStorageConfig, CosmosDatabaseConfig, azureBlobStorage, cosmosDatabase, migrateCosmosDatabase };

package/dist/index.d.mts

@@ -0,0 +1,71 @@
+import { TokenCredential } from "@azure/core-auth";
+import { StorageSharedKeyCredential } from "@azure/storage-blob";
+import { EngineDatabase, PluginTables, StorageAdapter, StorageAdapterWith } from "@hot-updater/plugin-core";
+import { CosmosClientOptions } from "@azure/cosmos";
+//#region src/azureBlobStorage.d.ts
+/** The account to connect to: its connection string, or its Blob endpoint and a credential. */
+type AzureBlobConnection = {
+  readonly connectionString: string;
+} | {
+  /** The Blob service endpoint, such as `https://<account>.blob.core.windows.net`. */
+  readonly accountUrl: string;
+  /** An account key, or a Microsoft Entra identity such as `DefaultAzureCredential`. */
+  readonly credential: StorageSharedKeyCredential | TokenCredential;
+};
+type AzureBlobStorageConfig = AzureBlobConnection & {
+  /** The Blob container that keeps the bundles. */
+  readonly containerName: string;
+  /** Base path where bundles will be stored in the container. */
+  readonly basePath?: string;
+  /**
+   * The URL devices download an object from, such as a CDN's. Without it, a
+   * read-only SAS URL that expires in an hour.
+   */
+  readonly getDownloadUrl?: StorageAdapter["getDownloadUrl"];
+};
+type AzureBlobStorageOperations = "put" | "get" | "getDownloadUrl" | "exists" | "delete" | "listObjects" | "deleteObjects";
+/**
+ * Bundles in an Azure Blob Storage container. Without `getDownloadUrl`,
+ * devices download through SAS URLs: signed with the account key when the
+ * connection has one, otherwise with a user delegation key, which needs the
+ * identity's Storage Blob Delegator role.
+ */
+declare function azureBlobStorage(config: AzureBlobStorageConfig): StorageAdapterWith<AzureBlobStorageOperations>;
+//#endregion
+//#region src/cosmosDatabase.d.ts
+/**
+ * The client's options: the account's `connectionString`, or its
+ * `endpoint` with a `key` or Microsoft Entra `aadCredentials`. Reads must
+ * be strongly consistent, so `consistencyLevel` takes only `"Strong"`.
+ */
+type CosmosDatabaseConfig = Omit<CosmosClientOptions, "consistencyLevel"> & {
+  readonly consistencyLevel?: "Strong";
+  /** The database the container lives in. @default "hot-updater" */
+  readonly databaseId?: string;
+  /** The one container the database keeps its items in. @default "hot_updater_v1" */
+  readonly containerId?: string;
+  /**
+   * Cosmos DB bills each item a write touches, so Insights' aggregates are
+   * batched: through log rows a compaction merges (the default), or
+   * `{ mode: "memory" }` on a long-lived server. `false` commits them with
+   * each event.
+   */
+  readonly aggregateBatching?: EngineDatabase["aggregateBatching"] | false;
+};
+/**
+ * Creates the database and the container when they are missing, refusing a
+ * container of another storage layout or another app's items, and writes
+ * the schema settings of core and `plugins`, the plugins the server runs,
+ * which the database checks before its first read. `hot-updater init` runs
+ * it with the managed server's plugins.
+ */
+declare const migrateCosmosDatabase: (config: CosmosDatabaseConfig, plugins?: readonly PluginTables[]) => Promise<void>;
+/**
+ * Hot Updater's database in one Azure Cosmos DB for NoSQL container,
+ * through the storage engine. Every item shares one logical partition, so a
+ * write commits as one transactional batch; that partition holds at most
+ * 20 GB.
+ */
+declare const cosmosDatabase: (config: CosmosDatabaseConfig) => EngineDatabase;
+//#endregion
+export { AzureBlobConnection, AzureBlobStorageConfig, CosmosDatabaseConfig, azureBlobStorage, cosmosDatabase, migrateCosmosDatabase };