local strapi docs

docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/00-overview.md

@@ -1,5 +1,5 @@
 ---
-title: File Providers
+title: Local Strapi Providers
 tags:
   - experimental
   - providers
@@ -8,6 +8,10 @@ tags:
   - data-transfer
 ---
 
-# Strapi Data File Providers
+# Local Strapi Providers
 
-**TODO**
+The local Strapi provider allows using the local Strapi instance (the same project that the data transfer engine is being run from) as a data source.
+
+Creating a local Strapi data provider requires passing in an initialized `strapi` server object to interact with that server's Entity Service and Query Engine to manage the data. Therefore if the local Strapi project cannot be started (due to errors), the providers cannot be used.
+
+**Important**: When a transfer completes, the `strapi` object passed in is shut down automatically based on the `autoDestroy` option. If you are running a transfer via an external script, it is recommended to use `autoDestroy: true` to ensure it is shut down properly, but if you are running a transfer within a currently running Strapi instance you should set `autoDestroy: false` or your Strapi instance will be shut down at the end of the transfer.

docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/01-source.md

@@ -0,0 +1,21 @@
+---
+title: Local Strapi Source
+tags:
+  - providers
+  - data-transfer
+  - experimental
+---
+
+# Local Strapi Source Provider
+
+This provider will retrieve data from an initialized `strapi` instance using its Entity Service and Query Engine.
+
+## Provider Options
+
+The accepted options are defined in `ILocalFileSourceProviderOptions`.
+
+```typescript
+  getStrapi(): Strapi.Strapi | Promise<Strapi.Strapi>; // return an initialized instance of Strapi
+
+  autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer
+```

docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-destination.md

@@ -0,0 +1,56 @@
+---
+title: Local Strapi Destination
+tags:
+  - providers
+  - data-transfer
+  - experimental
+---
+
+# Local Strapi Destination Provider
+
+This provider will insert data into an initialized `strapi` instance using its Entity Service and Query Engine.
+
+## Provider Options
+
+The accepted options are defined in `ILocalFileSourceProviderOptions`.
+
+```typescript
+  getStrapi(): Strapi.Strapi | Promise<Strapi.Strapi>; // return an initialized instance of Strapi
+  autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer
+  restore?: restore.IRestoreOptions; // the options to use when strategy is 'restore'
+  strategy: 'restore'; // conflict management strategy; only the restore strategy is available at this time
+```
+
+`strategy` defines the conflict management strategy used. Currently, only `"restore"` is available as an option.
+
+### Restore
+
+A conflict management strategy of "restore" deletes all existing Strapi data before a transfer to avoid any conflicts.
+
+The following restore options are available:
+
+```typecript
+export interface IRestoreOptions {
+  assets?: boolean; // delete media library files before transfer
+  configuration?: {
+    webhook?: boolean; // delete webhooks before transfer
+    coreStore?: boolean; // delete core store before transfer
+  };
+  entities?: {
+    include?: string[]; // only delete these stage entities before transfer
+    exclude?: string[]; // exclude these stage entities from deletion
+    filters?: ((contentType: ContentTypeSchema) => boolean)[]; // custom filters to exclude a content type from deletion
+    params?: { [uid: string]: unknown }; // params object passed to deleteMany before transfer for custom deletions
+  };
+}
+```
+
+### Rollbacks
+
+This local Strapi destination provider automatically provides a rollback mechanism on error.
+
+For Strapi data, that is done with a database transaction wrapped around the restore and the insertion of data and committing on succes and rolling back on failure.
+
+For Strapi assets (ie, the media library files) this is done by attempting to temporarily move the existing assets to a backup directory to `uploads_backup_{timestamp}`, and then deleting it on success, or deleting the failed import files and putting the backup back into place on failure. In some cases of failure, it may be impossible to move the backup files back into place, so you will need to manually restore the backup assets files.
+
+Note: Because of the need for write access, environments without filesystem permissions to move the assets folder (common for virtual environments where /uploads is mounted as a read-only drive) will be unable to include assets in a transfer and the asset stage must be excluded in order to run the transfer.

docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/02-source.md

@@ -1,13 +0,0 @@
----
-title: Strapi File
-tags:
-  - providers
-  - data-transfer
-  - experimental
----
-
-# Strapi File Source Provider
-
-This provider will output a Strapi Data File
-
-**TODO**

docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/03-destination.md

@@ -1,15 +0,0 @@
----
-title: Strapi File
-tags:
-  - providers
-  - data-transfer
-  - experimental
----
-
-# Strapi File Destination Provider
-
-This provider will output a Strapi Data File
-
-Note: this destination provider does not provide a schema or metadata, and will therefore never report a schema match error or version validation error
-
-**TODO**

docs/docs/docs/01-core/data-transfer/03-local-strapi-providers/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "File Providers",
+  "label": "Local Strapi Providers",
   "collapsible": true,
   "collapsed": true
 }

docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md

@@ -1,5 +1,5 @@
 ---
-title: File Providers
+title: Remote Strapi Providers
 tags:
   - experimental
   - providers
@@ -8,6 +8,6 @@ tags:
   - data-transfer
 ---
 
-# Strapi Data File Providers
+# Remote Strapi Providers
 
 **TODO**

docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-file-structure.md

@@ -1,11 +0,0 @@
----
-title: Strapi File
-tags:
-  - providers
-  - data-transfer
-  - experimental
----
-
-# Strapi File Structure
-
-**TODO**

docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/01-websocket.md

@@ -1,11 +1,11 @@
 ---
-title: Strapi File
+title: Remote Provider Websocket
 tags:
   - providers
   - data-transfer
   - experimental
 ---
 
-# Strapi File Structure
+# Remote Provider Websocket
 
 **TODO**

docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md

@@ -1,13 +1,11 @@
 ---
-title: Strapi File
+title: Strapi Remote Source Provider
 tags:
   - providers
   - data-transfer
   - experimental
 ---
 
-# Strapi File Source Provider
-
-This provider will output a Strapi Data File
+# Strapi Remote Source Provider
 
 **TODO**

docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md

@@ -1,15 +1,11 @@
 ---
-title: Strapi File
+title: Remote Destination Provider
 tags:
   - providers
   - data-transfer
   - experimental
 ---
 
-# Strapi File Destination Provider
-
-This provider will output a Strapi Data File
-
-Note: this destination provider does not provide a schema or metadata, and will therefore never report a schema match error or version validation error
+# Strapi Remote Destination Provider
 
 **TODO**

docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/_category_.json

@@ -1,5 +1,5 @@
 {
-  "label": "File Providers",
+  "label": "Remote Strapi Providers",
   "collapsible": true,
   "collapsed": true
 }

packages/core/data-transfer/src/strapi/providers/local-destination/index.ts

@@ -18,10 +18,11 @@ export const VALID_CONFLICT_STRATEGIES = ['restore', 'merge'];
 export const DEFAULT_CONFLICT_STRATEGY = 'restore';
 
 export interface ILocalStrapiDestinationProviderOptions {
-  getStrapi(): Strapi.Strapi | Promise<Strapi.Strapi>;
-  autoDestroy?: boolean;
-  restore?: restore.IRestoreOptions;
-  strategy: 'restore' | 'merge';
+  getStrapi(): Strapi.Strapi | Promise<Strapi.Strapi>; // return an initialized instance of Strapi
+
+  autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer
+  restore?: restore.IRestoreOptions; // erase all data in strapi database before transfer
+  strategy: 'restore'; // conflict management strategy; only the restore strategy is available at this time
 }
 
 class LocalStrapiDestinationProvider implements IDestinationProvider {

packages/core/data-transfer/src/strapi/providers/local-destination/strategies/restore/index.ts

@@ -3,16 +3,16 @@ import { ProviderTransferError } from '../../../../../errors/providers';
 import * as queries from '../../../../queries';
 
 export interface IRestoreOptions {
-  assets?: boolean;
+  assets?: boolean; // delete media library files before transfer
   configuration?: {
-    webhook?: boolean;
-    coreStore?: boolean;
+    webhook?: boolean; // delete webhooks before transfer
+    coreStore?: boolean; // delete core store before transfer
   };
   entities?: {
-    include?: string[];
-    exclude?: string[];
-    filters?: ((contentType: ContentTypeSchema) => boolean)[];
-    params?: { [uid: string]: unknown };
+    include?: string[]; // only delete these stage entities before transfer
+    exclude?: string[]; // exclude these stage entities from deletion
+    filters?: ((contentType: ContentTypeSchema) => boolean)[]; // custom filters to exclude a content type from deletion
+    params?: { [uid: string]: unknown }; // params object passed to deleteMany before transfer for custom deletions
   };
 }
 

packages/core/data-transfer/src/strapi/providers/local-source/index.ts

@@ -10,9 +10,9 @@ import * as utils from '../../../utils';
 import { assertValidStrapi } from '../../../utils/providers';
 
 export interface ILocalStrapiSourceProviderOptions {
-  getStrapi(): Strapi.Strapi | Promise<Strapi.Strapi>;
+  getStrapi(): Strapi.Strapi | Promise<Strapi.Strapi>; // return an initialized instance of Strapi
 
-  autoDestroy?: boolean;
+  autoDestroy?: boolean; // shut down the instance returned by getStrapi() at the end of the transfer
 }
 
 export const createLocalStrapiSourceProvider = (options: ILocalStrapiSourceProviderOptions) => {