Move internal implementation of the odsp driver cache to the Fluid Fr…

…amework Repository (#9418)

* initial commit

* Update tsconfigs

* Compile fixes

* Make tests pass

* Add readme

* Update formatting

* Some eslint suppressions and fixes

* Fix formatting lint issues

* Disable some lint rules

* More disables

* Fix last of eslint issues

* Policy check fixes

* Policy update

* Pin url-parse types

* Add comments

* Undo lerna package changes

* Update lockfile

* Undo content changes

* Undo content changes

* Undo content

* Remove deprecated API

* Rename folder

* Autogenerated files

* Remove more internal references

* Update packages/drivers/driver-web-cache/package.json

Co-authored-by: Helio Liu <[email protected]>

* Update packages/drivers/driver-web-cache/package.json

Co-authored-by: Helio Liu <[email protected]>

* Minor cleanups

Co-authored-by: Helio Liu <[email protected]>

api-report/driver-web-cache.api.md

@@ -0,0 +1,36 @@
+## API Report File for "@fluidframework/driver-web-cache"
+
+> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+
+```ts
+
+import { ICacheEntry } from '@fluidframework/odsp-driver-definitions';
+import { IFileEntry } from '@fluidframework/odsp-driver-definitions';
+import { IPersistedCache } from '@fluidframework/odsp-driver-definitions';
+import { ITelemetryBaseLogger } from '@fluidframework/common-definitions';
+
+// @public (undocumented)
+export function deleteFluidCacheIndexDbInstance(): Promise<void>;
+
+// @public
+export class FluidCache implements IPersistedCache {
+    constructor(config: FluidCacheConfig);
+    // (undocumented)
+    get(cacheEntry: ICacheEntry): Promise<any>;
+    // (undocumented)
+    put(entry: ICacheEntry, value: any): Promise<void>;
+    // (undocumented)
+    removeEntries(file: IFileEntry): Promise<void>;
+}
+
+// @public (undocumented)
+export interface FluidCacheConfig {
+    logger?: ITelemetryBaseLogger;
+    maxCacheItemAge: number;
+    partitionKey: string | null;
+}
+
+
+// (No @packageDocumentation comment for this package)
+
+```

packages/drivers/driver-web-cache/.eslintrc.js

@@ -0,0 +1,19 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+    extends: ["@fluidframework/eslint-config-fluid"],
+    parserOptions: {
+        project: ["./tsconfig.json", "./src/test/tsconfig.json"],
+    },
+    rules: {
+        "@typescript-eslint/no-non-null-assertion": "off",
+        "@typescript-eslint/no-use-before-define": "off",
+        "@typescript-eslint/strict-boolean-expressions": "off",
+        "no-null/no-null": "off",
+        "@typescript-eslint/promise-function-async": "off",
+        "@typescript-eslint/no-misused-promises": "off",
+    },
+};

packages/drivers/driver-web-cache/.gitignore

@@ -0,0 +1,52 @@
+# Compiled TypeScript and CSS
+dist
+lib
+
+# Babel
+public/scripts/es5
+
+# Logs
+logs
+*.log
+
+# Runtime data
+pids
+*.pid
+*.seed
+
+# Directory for instrumented libs generated by jscoverage/JSCover
+lib-cov
+
+# Coverage directory used by tools like istanbul
+coverage
+
+# Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
+.grunt
+.cache-loader
+
+# node-waf configuration
+.lock-wscript
+
+# Compiled binary addons (http://nodejs.org/api/addons.html)
+build/Release
+
+# Dependency directory
+# https://www.npmjs.org/doc/misc/npm-faq.html#should-i-check-my-node_modules-folder-into-git-
+node_modules
+
+# Typings
+typings
+
+# Debug log from npm
+npm-debug.log
+
+# Code coverage
+nyc
+.nyc_output/
+
+# Chart dependencies
+**/charts/*.tgz
+
+# Generated modules
+intel_modules/
+temp_modules/

packages/drivers/driver-web-cache/.npmignore

@@ -0,0 +1,6 @@
+nyc
+*.log
+**/*.tsbuildinfo
+src/test
+dist/test
+**/_api-extractor-temp/**

packages/drivers/driver-web-cache/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/drivers/driver-web-cache/README.md

@@ -0,0 +1,56 @@
+# @fluidframework/driver-web-cache
+
+This package provides an implementation of the `IPersistedCache` interface in the odsp-driver package. This cache enables
+storing of user content on the user's machine in order to provide faster boot experiences when opening the same Fluid
+containers more than once. This implementation has a dependency on indexeddb, so it is intended to only be used in a browser
+context.
+
+## Usage
+
+```typescript
+import { FluidCache } from '@fluidframework/driver-web-cache';
+
+new FluidCache({
+          partitionKey: userId,
+          logger,
+          maxCacheItemAge
+        })
+```
+
+### Parameters
+
+- `partitionKey` - Used to determine what partition of the cache is being used, and can prevent multiple users on the
+   same machine from sharing a snapshot cache. If you absolutely know that users will not share the cache,
+   can also be set to `null`. Currently optional, but is proposed to be required in the next major bump.
+   The recommendation is to use this key to differentiate users for the cache data.
+- `logger` - An optional implementation of the logger contract where diagnostic data  can be logged.
+- `maxCacheItemAge` - The cache tracks a timestamp with each entry. This flag specifies the maximum age (in milliseconds)
+   for a cache entry to be used. This flag does not control when cached content is deleted since different scenarios and
+   applications may have different staleness thresholds for the same data.
+
+## Clearing cache entries
+
+Whenever any Fluid content is loaded with the web cache enabled, a task is scheduled to clear out all "stale" cache
+entries. This task is scheduled with the `setIdleCallback` browser API. We define stale cache entries as any cache
+entries that have not been used (read or written to) within the last 4 weeks. The cache is cleared of all stale cache
+entries corresponding to all documents, not just the ones corresponding to the Fluid document being loaded.
+
+The `deleteFluidCacheIndexDbInstance` API that an application can use to clear out the entire contents of the snapshot
+cache at any time. We recommend calling this API when the user explicitly signs out. Hosting applications
+are on point for ensuring responsible usage of the snapshot caching capability to still meet any relevant
+customer promises, such as clearing out storage when appropriate or disabling snapshot caching under certain circumstances,
+such as when it is known the user is logged in to a public computer.
+
+
+```typescript
+import { deleteFluidCacheIndexDbInstance } from '@fluidframework/driver-web-cache';
+
+  // We put a catch here because Firefox Incognito will throw an error here. This is why we claim this method is a "best effort", since sometimes the browser won't let us access storage
+deleteFluidCacheIndexDbInstance().catch(() => {});
+```
+
+## Trademark
+
+This project may contain Microsoft trademarks or logos for Microsoft projects, products, or services. Use of these trademarks
+or logos must follow Microsoft's [Trademark & Brand Guidelines](https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general).
+Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship.

packages/drivers/driver-web-cache/api-extractor.json

@@ -0,0 +1,4 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "extends": "@fluidframework/build-common/api-extractor-common-report.json"
+}

packages/drivers/driver-web-cache/jest.config.js

@@ -0,0 +1,12 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+module.exports = {
+    roots: ["<rootDir>/dist"],
+    testEnvironment: "jsdom",
+    testMatch: ["**/?(*.)+(spec|test).[j]s"],
+    testPathIgnorePatterns: ["/node_modules/"],
+    verbose: true,
+};

packages/drivers/driver-web-cache/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "@fluidframework/driver-web-cache",
+  "version": "0.58.2000",
+  "description": "Implementation of the driver caching API for a web browser",
+  "homepage": "https://fluidframework.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/FluidFramework.git",
+    "directory": "packages/drivers/driver-web-cache"
+  },
+  "license": "MIT",
+  "author": "Microsoft and contributors",
+  "sideEffects": false,
+  "main": "dist/index.js",
+  "module": "lib/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "npm run build:genver && concurrently npm:build:compile npm:lint && npm run build:docs",
+    "build:commonjs": "npm run tsc && npm run build:test",
+    "build:compile": "concurrently npm:build:commonjs npm:build:esnext",
+    "build:docs": "api-extractor run --local --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/doc-models/* ../../../_api-extractor-temp/",
+    "build:esnext": "tsc --project ./tsconfig.esnext.json",
+    "build:full": "npm run build",
+    "build:full:compile": "npm run build:compile",
+    "build:genver": "gen-version",
+    "build:test": "tsc --project ./src/test/tsconfig.json",
+    "ci:build:docs": "api-extractor run --typescript-compiler-folder ../../../node_modules/typescript && copyfiles -u 1 ./_api-extractor-temp/* ../../../_api-extractor-temp/",
+    "clean": "rimraf dist lib *.tsbuildinfo *.build.log",
+    "eslint": "eslint --format stylish src",
+    "eslint:fix": "eslint --format stylish src --fix --fix-type problem,suggestion,layout",
+    "lint": "npm run eslint",
+    "lint:fix": "npm run eslint:fix",
+    "test": "jest",
+    "tsc": "tsc",
+    "tsfmt": "tsfmt --verify",
+    "tsfmt:fix": "tsfmt --replace"
+  },
+  "dependencies": {
+    "@fluidframework/common-definitions": "^0.20.1",
+    "@fluidframework/odsp-driver-definitions": "^0.58.2000",
+    "@fluidframework/telemetry-utils": "^0.58.2000",
+    "idb": "^6.1.2"
+  },
+  "devDependencies": {
+    "@fluidframework/build-common": "^0.23.0",
+    "@fluidframework/eslint-config-fluid": "^0.27.0-0",
+    "@microsoft/api-extractor": "^7.16.1",
+    "@rushstack/eslint-config": "^2.5.1",
+    "@types/jest": "22.2.3",
+    "@types/node": "^14.18.0",
+    "@types/socket.io-client": "^1.4.32",
+    "@typescript-eslint/eslint-plugin": "~5.9.0",
+    "@typescript-eslint/parser": "~5.9.0",
+    "concurrently": "^6.2.0",
+    "copyfiles": "^2.1.0",
+    "eslint": "~8.6.0",
+    "eslint-plugin-editorconfig": "~3.2.0",
+    "eslint-plugin-eslint-comments": "~3.2.0",
+    "eslint-plugin-import": "~2.25.4",
+    "eslint-plugin-no-null": "~1.0.2",
+    "eslint-plugin-react": "~7.28.0",
+    "eslint-plugin-unicorn": "~40.0.0",
+    "fake-indexeddb": "3.1.4",
+    "jest": "^26.6.3",
+    "typescript": "~4.1.3",
+    "typescript-formatter": "7.1.0"
+  }
+}