diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md index 70179091dd..66927b8b9c 100644 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/00-overview.md @@ -10,4 +10,12 @@ tags: # Remote Strapi Providers -**TODO** +Remote Strapi providers connect to an instance of Strapi over a network using a websocket. + +Internally, the remote Strapi providers map websocket requests to a local Strapi provider of the instance it is running in. + +## Websocket Server + +When the data transfer feature is enabled for a Strapi server (a transfer token salt has been set on the server and STRAPI_DISABLE_REMOTE_DATA_TRANSFER is not set to true), Strapi will create websocket servers available on the routes `/admin/transfer/runner/pull` and `/admin/transfer/runner/push`. + +Opening a websocket connection on those routes requires a valid transfer token as a bearer token in the Authorization header. diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md index 91900819e2..88b2ae94e5 100644 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/02-source.md @@ -8,4 +8,23 @@ tags: # Strapi Remote Source Provider -**TODO** +The Strapi remote source provider connects to a remote Strapi websocket server and sends messages to move between stages and pull data. + +## Provider Options + +The remote source provider accepts a `url` and `auth` options described below. + +```typescript +interface ITransferTokenAuth { + type: 'token'; + token: string; +} + +export interface IRemoteStrapiDestinationProviderOptions + extends Pick { + url: URL; + auth?: ITransferTokenAuth; +} +``` + +Note: `url` must include the protocol `https` or `http` which will then be converted to `wss` or `ws` to make the connection. A secure connection is strongly recommended, especially given the high access level that the transfer token provides. diff --git a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md index 8e12576612..5fe7758981 100644 --- a/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md +++ b/docs/docs/docs/01-core/data-transfer/04-remote-strapi-providers/03-destination.md @@ -8,4 +8,23 @@ tags: # Strapi Remote Destination Provider -**TODO** +The Strapi remote destination provider connects to a remote Strapi websocket server and sends messages to move between stages and push data. + +## Provider Options + +The remote destination provider accepts the same `restore` and `strategy` options from local Strapi destination provider, plus `url` and `auth` options described below. + +```typescript +interface ITransferTokenAuth { + type: 'token'; // the name of the auth strategy + token: string; // the transfer token +} + +export interface IRemoteStrapiDestinationProviderOptions + extends Pick { + url: URL; // the url of the remote Strapi admin + auth?: ITransferTokenAuth; +} +``` + +Note: `url` must include the protocol `https` or `http` which will then be converted to `wss` or `ws` to make the connection. A secure connection is strongly recommended, especially given the high access level that the transfer token provides. diff --git a/packages/core/data-transfer/src/strapi/providers/remote-destination/index.ts b/packages/core/data-transfer/src/strapi/providers/remote-destination/index.ts index 13fef83cde..0ee10d7c02 100644 --- a/packages/core/data-transfer/src/strapi/providers/remote-destination/index.ts +++ b/packages/core/data-transfer/src/strapi/providers/remote-destination/index.ts @@ -6,20 +6,15 @@ import { once } from 'lodash/fp'; import { createDispatcher, connectToWebsocket, trimTrailingSlash } from '../utils'; import type { IDestinationProvider, IMetadata, ProviderType, IAsset } from '../../../../types'; -import type { client, server } from '../../../../types/remote/protocol'; +import type { client, server, auth } from '../../../../types/remote/protocol'; import type { ILocalStrapiDestinationProviderOptions } from '../local-destination'; import { TRANSFER_PATH } from '../../remote/constants'; import { ProviderTransferError, ProviderValidationError } from '../../../errors/providers'; -interface ITransferTokenAuth { - type: 'token'; - token: string; -} - export interface IRemoteStrapiDestinationProviderOptions extends Pick { - url: URL; - auth?: ITransferTokenAuth; + url: URL; // the url of the remote Strapi admin + auth?: auth.ITransferTokenAuth; } const jsonLength = (obj: object) => Buffer.byteLength(JSON.stringify(obj)); diff --git a/packages/core/data-transfer/src/strapi/providers/remote-source/index.ts b/packages/core/data-transfer/src/strapi/providers/remote-source/index.ts index 96667aafdc..772c1a6832 100644 --- a/packages/core/data-transfer/src/strapi/providers/remote-source/index.ts +++ b/packages/core/data-transfer/src/strapi/providers/remote-source/index.ts @@ -10,20 +10,15 @@ import type { ProviderType, TransferStage, } from '../../../../types'; -import { client, server } from '../../../../types/remote/protocol'; +import { client, server, auth } from '../../../../types/remote/protocol'; import { ProviderTransferError, ProviderValidationError } from '../../../errors/providers'; import { TRANSFER_PATH } from '../../remote/constants'; import { ILocalStrapiSourceProviderOptions } from '../local-source'; import { createDispatcher, connectToWebsocket, trimTrailingSlash } from '../utils'; -interface ITransferTokenAuth { - type: 'token'; - token: string; -} - export interface IRemoteStrapiSourceProviderOptions extends ILocalStrapiSourceProviderOptions { - url: URL; - auth?: ITransferTokenAuth; + url: URL; // the url of the remote Strapi admin + auth?: auth.ITransferTokenAuth; } class RemoteStrapiSourceProvider implements ISourceProvider { diff --git a/packages/core/data-transfer/types/remote/protocol/auth.d.ts b/packages/core/data-transfer/types/remote/protocol/auth.d.ts new file mode 100644 index 0000000000..c26a137576 --- /dev/null +++ b/packages/core/data-transfer/types/remote/protocol/auth.d.ts @@ -0,0 +1,4 @@ +export interface ITransferTokenAuth { + type: 'token'; // the name of the auth strategy + token: string; // the transfer token +} diff --git a/packages/core/data-transfer/types/remote/protocol/index.d.ts b/packages/core/data-transfer/types/remote/protocol/index.d.ts index 4cbe5b42a3..5572b66971 100644 --- a/packages/core/data-transfer/types/remote/protocol/index.d.ts +++ b/packages/core/data-transfer/types/remote/protocol/index.d.ts @@ -1,2 +1,3 @@ export * as client from './client'; export * as server from './server'; +export * as auth from './auth';