@ckeditor/ckeditor-cloud-services-collaboration 54.2.12 → 54.3.0

package/dist/servicesconnector/servicesconnector.d.ts

@@ -0,0 +1,34 @@
+/*
+ Copyright (c), CKSource Holding sp. z o.o. All rights reserved.
+ */
+import { type IServiceRequest, type IWebSocketGateway } from '../websocketgateway/websocketgateway';
+export interface IConnectableService<TResult = unknown> {
+    /**
+     * Prepares the service for connecting and returns its connect request, or `undefined` when it is already connected.
+     */
+    beforeConnect(wsGateway: IWebSocketGateway): IServiceRequest | undefined;
+    /**
+     * Applies the response of the connect request and returns the service's data.
+     */
+    afterConnect(wsGateway: IWebSocketGateway, response: Buffer): TResult;
+}
+export type ServicesConnectResults<T extends ReadonlyArray<IConnectableService>> = {
+    [K in keyof T]: PromiseSettledResult<ReturnType<T[K]['afterConnect']> | void>;
+};
+/**
+ * Connects multiple services to CKEditor Cloud Services at once, instead of one after another.
+ */
+export default class ServicesConnector {
+    private readonly _wsGateway;
+    constructor(_wsGateway: IWebSocketGateway);
+    /**
+     * Sends the connect requests of all given services as one batch request, and waits until all of them settle.
+     *
+     * A failed connect does not affect the others. The results are returned in the order of the given services.
+     * A service that is already connected sends no request and resolves with `undefined`.
+     *
+     * @throws {@link CKEditorCloudServicesError}
+     * Thrown when the WebSocket Gateway is not connected. No connect request is sent in that case.
+     */
+    connect<T extends ReadonlyArray<IConnectableService>>(services: [...T]): Promise<ServicesConnectResults<T>>;
+}

package/dist/track-changes/trackchangesservice.d.ts

@@ -3,7 +3,7 @@
  */
 import AddSuggestionResponse from './responses/addsuggestionresponse';
 import GetSuggestionResponse from './responses/getsuggestionresponse';
-import { type IWebSocketGateway } from '../websocketgateway/websocketgateway';
+import { type IServiceRequest, type IWebSocketGateway } from '../websocketgateway/websocketgateway';
 import type { ISuggestion } from './descriptors/suggestiondescriptor';
 export declare const _SERVICE: number;
 interface ISuggestionUpdateProps {
@@ -31,6 +31,17 @@ declare class TrackChangesService extends /* #__PURE__ -- @preserve */ TrackChan
      * Connects to WebSocketGateway and starts listening on channel.
      */
     connect(wsGateway: IWebSocketGateway): Promise<ISuggestion[] | void>;
+    /**
+     * Prepares the service for connecting and returns its connect request, or `undefined` when it is already connected.
+     *
+     * @throws {@link CKEditorCloudServicesError}
+     * Thrown when the WebSocket Gateway is not connected.
+     */
+    beforeConnect(wsGateway: IWebSocketGateway): IServiceRequest | undefined;
+    /**
+     * Applies the response of the connect request: starts listening on the channel and on the gateway state.
+     */
+    afterConnect(wsGateway: IWebSocketGateway, response: Buffer): ISuggestion[];
     /**
      * Disconnects TrackChangesService from CKEditor Cloud Services.
      */

package/dist/version.d.ts

@@ -1,5 +1,5 @@
 /*
  Copyright (c), CKSource Holding sp. z o.o. All rights reserved.
  */
-declare const _default: "54.2.12";
+declare const _default: "54.3.0";
 export default _default;

package/dist/websocketgateway/descriptors/batchrequestpartdescriptor.d.ts

@@ -0,0 +1,23 @@
+/*
+ Copyright (c), CKSource Holding sp. z o.o. All rights reserved.
+ */
+import Descriptor, { type IDescriptorBody } from './../../descriptor';
+export interface IBatchRequestPart {
+    /**
+     * Numeric service id, the same as byte 0 of a single request envelope.
+     */
+    service: number;
+    /**
+     * Numeric method id, the same as byte 1 of a single request envelope.
+     */
+    method: number;
+    /**
+     * The encoded request, the same as the rest of a single request envelope.
+     */
+    message: Uint8Array;
+}
+export default class BatchRequestPartDescriptor extends Descriptor {
+    static readonly DESCRIPTOR_NAME: string;
+    static readonly DESCRIPTOR: IDescriptorBody;
+    static fromJSON(json: IBatchRequestPart): IBatchRequestPart;
+}

package/dist/websocketgateway/descriptors/batchresponsepartdescriptor.d.ts

@@ -0,0 +1,25 @@
+/*
+ Copyright (c), CKSource Holding sp. z o.o. All rights reserved.
+ */
+import Descriptor, { type IDescriptorBody } from './../../descriptor';
+import type { IPublicError } from '../../ckeditorcloudservicesservererror';
+export interface IBatchResponsePart {
+    /**
+     * The error of a failed request, the same as the error of a single request.
+     */
+    error?: IPublicError;
+    /**
+     * The response of a successful request, the same as the response of a single request.
+     */
+    data?: Uint8Array;
+}
+export interface IBatchResponsePartJSON {
+    error?: string;
+    data?: Uint8Array;
+}
+export default class BatchResponsePartDescriptor extends Descriptor {
+    static readonly DESCRIPTOR_NAME: string;
+    static readonly DESCRIPTOR: IDescriptorBody;
+    static toJSON(part: IBatchResponsePart): IBatchResponsePartJSON;
+    static fromJSON(json: IBatchResponsePartJSON): IBatchResponsePart;
+}

package/dist/websocketgateway/messages/batchrequestmessage.d.ts

@@ -0,0 +1,20 @@
+/*
+ Copyright (c), CKSource Holding sp. z o.o. All rights reserved.
+ */
+import Message, { type IMessage } from './../../message';
+import type { IDescriptorBody } from '../../descriptor';
+import { type IBatchRequestPart } from '../descriptors/batchrequestpartdescriptor';
+export interface IBatchRequestMessage extends IMessage {
+    requests: IBatchRequestPart[];
+}
+/**
+ * Several requests sent to the WebSocket Gateway at once. The gateway processes each part as a single request.
+ */
+export default class BatchRequestMessage extends Message {
+    readonly requests: IBatchRequestPart[];
+    static readonly DESCRIPTOR_NAME: string;
+    static readonly DESCRIPTOR: IDescriptorBody;
+    constructor(requests: IBatchRequestPart[]);
+    toJSON(): IBatchRequestMessage;
+    static fromJSON(json: IBatchRequestMessage): BatchRequestMessage;
+}

package/dist/websocketgateway/messages/batchresponsemessage.d.ts

@@ -0,0 +1,20 @@
+/*
+ Copyright (c), CKSource Holding sp. z o.o. All rights reserved.
+ */
+import Message, { type IMessage } from './../../message';
+import type { IDescriptorBody } from '../../descriptor';
+import { type IBatchResponsePart, type IBatchResponsePartJSON } from '../descriptors/batchresponsepartdescriptor';
+export interface IBatchResponseMessageJSON extends IMessage {
+    responses: IBatchResponsePartJSON[];
+}
+/**
+ * The responses to a {@link BatchRequestMessage}, in the order of its requests.
+ */
+export default class BatchResponseMessage extends Message {
+    readonly responses: IBatchResponsePart[];
+    static readonly DESCRIPTOR_NAME: string;
+    static readonly DESCRIPTOR: IDescriptorBody;
+    constructor(responses: IBatchResponsePart[]);
+    toJSON(): IBatchResponseMessageJSON;
+    static fromJSON(json: IBatchResponseMessageJSON): BatchResponseMessage;
+}

package/dist/websocketgateway/websocketgateway.d.ts

@@ -32,8 +32,14 @@ export interface IWebSocketGatewayConnectionOptions extends ManagerOptions {
         Encoder: (new (...args: unknown[]) => IOEncoder);
     };
 }
+export interface IServiceRequest {
+    serviceName: number;
+    method: string;
+    buffer: Uint8Array;
+}
 export interface IWebSocketGateway extends Emitter {
     _sendRequest<T extends IMessage>(serviceName: number, method: string, buffer: Uint8Array): Promise<T>;
+    _sendBatchRequest(requests: IServiceRequest[]): Promise<PromiseSettledResult<Buffer>[]>;
     _getChannel(serviceName: string | number, channelId: string): Channel;
     disconnect(): void;
     reconnect(): Promise<void>;
@@ -63,6 +69,13 @@ declare class WebSocketGateway extends /* #__PURE__ -- @preserve */ WebSocketGat
     private readonly _options;
     private readonly _connectionProvider;
     private readonly _userFactory;
+    /**
+     * Cleared when the gateway rejected a batch request. It is an older gateway, so later requests are sent one by one.
+     *
+     * It covers the only batch type, {@link BATCH_REQUEST_TYPE}. A second type needs a flag per type, so that a gateway
+     * which does not know one type keeps getting batches of the other.
+     */
+    private _isBatchSupported;
     /**
      * Represents currently logged user as taken from CMS (Token). Undefined value represents anonymous user.
      */
@@ -126,6 +139,21 @@ declare class WebSocketGateway extends /* #__PURE__ -- @preserve */ WebSocketGat
      * Sends request to CKEditor Cloud Services.
      */
     _sendRequest<TResponse extends IMessage>(serviceName: number, method: string, buffer: Uint8Array): Promise<TResponse>;
+    /**
+     * Sends the given requests as one batch request and resolves with one result per request, in the same order.
+     * Sends them one by one when there is only one, when there are more than {@link BATCH_MAX_PARTS}, or when the gateway
+     * does not support batch requests.
+     *
+     * The batch request has one timeout, and the gateway replies when all requests are processed. So when the slowest
+     * request times out, the whole call is rejected, including the requests the gateway has already processed.
+     *
+     * @throws {@link CKEditorCloudServicesError}
+     * Thrown when the WebSocket Gateway is not connected, or when the batch request times out.
+     *
+     * @throws {@link CKEditorCloudServicesServerError}
+     * Thrown when the gateway rejects the batch request with an error other than the `500` of older gateways.
+     */
+    _sendBatchRequest(requests: IServiceRequest[]): Promise<PromiseSettledResult<Buffer>[]>;
     /**
      * Returns {@link Channel} associated with given service.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ckeditor/ckeditor-cloud-services-collaboration",
-  "version": "54.2.12",
+  "version": "54.3.0",
   "description": "CKEditor Cloud Services Collaboration low-level API is required by CKEditor 5 Collaboration features to enable real-time collaborative editing in CKEditor 5.",
   "main": "dist/services.js",
   "license": "SEE LICENSE IN LICENSE.md",