Deprecate core API instead of breaking it

Also update API docs

docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.md

@@ -19,5 +19,5 @@ export interface SessionStorageCookieOptions<T>
 |  [encryptionKey](./kibana-plugin-server.sessionstoragecookieoptions.encryptionkey.md) | <code>string</code> | A key used to encrypt a cookie value. Should be at least 32 characters long. |
 |  [isSecure](./kibana-plugin-server.sessionstoragecookieoptions.issecure.md) | <code>boolean</code> | Flag indicating whether the cookie should be sent only via a secure connection. |
 |  [name](./kibana-plugin-server.sessionstoragecookieoptions.name.md) | <code>string</code> | Name of the session cookie. |
-|  [validate](./kibana-plugin-server.sessionstoragecookieoptions.validate.md) | <code>(sessionValue: T) =&gt; boolean &#124; Promise&lt;boolean&gt;</code> | Function called to validate a cookie content. |
+|  [validate](./kibana-plugin-server.sessionstoragecookieoptions.validate.md) | <code>(sessionValue: T) =&gt; SessionCookieValidationResult &#124; boolean &#124; Promise&lt;boolean&gt;</code> | Function called to validate a cookie content.<!-- -->Return types <code>boolean</code> and <code>Promise&lt;boolean&gt;</code> are deprecated and should not be used. |
 

docs/development/core/server/kibana-plugin-server.sessionstoragecookieoptions.validate.md

@@ -6,8 +6,10 @@
 
 Function called to validate a cookie content.
 
+Return types `boolean` and `Promise<boolean>` are deprecated and should not be used.
+
 <b>Signature:</b>
 
 ```typescript
-validate: (sessionValue: T) => boolean | Promise<boolean>;
+validate: (sessionValue: T) => SessionCookieValidationResult | boolean | Promise<boolean>;
 ```

src/core/server/http/cookie_session_storage.ts

@@ -39,14 +39,27 @@ export interface SessionStorageCookieOptions<T> {
   encryptionKey: string;
   /**
    * Function called to validate a cookie content.
+   *
+   * Return types `boolean` and `Promise<boolean>` are deprecated and should not be used.
    */
-  validate: (sessionValue: T) => ValidationResult;
+  validate: (
+    sessionValue: T
+  ) =>
+    | SessionCookieValidationResult
+    | boolean /* @deprecated */
+    | Promise<boolean> /* @deprecated */;
   /**
    * Flag indicating whether the cookie should be sent only via a secure connection.
    */
   isSecure: boolean;
 }
 
+export interface SessionCookieValidationResult {
+  isValid: boolean;
+  path?: string;
+  isSecure?: boolean;
+}
+
 class ScopedCookieSessionStorage<T extends Record<string, any>> implements SessionStorage<T> {
   constructor(
     private readonly log: Logger,
@@ -85,12 +98,6 @@ class ScopedCookieSessionStorage<T extends Record<string, any>> implements Sessi
   }
 }
 
-interface ValidationResult {
-  isValid: boolean;
-  path?: string;
-  isSecure?: boolean;
-}
-
 /**
  * Creates SessionStorage factory, which abstract the way of
  * session storage implementation and scoping to the incoming requests.
@@ -124,7 +131,13 @@ export async function createCookieSessionStorageFactory<T>(
     cookie: cookieOptions.name,
     password: cookieOptions.encryptionKey,
     validateFunc: async (req, session: T) => {
-      const result = cookieOptions.validate(session);
+      let result = cookieOptions.validate(session);
+      // handle deprecated return types, change them into SessionCookieValidationResult
+      if (typeof result === 'boolean') {
+        result = { isValid: result };
+      } else if (result instanceof Promise) {
+        result = { isValid: await result };
+      }
       if (!result.isValid) {
         clearInvalidCookie(req, result.path, result.isSecure);
       }

src/core/server/http/index.ts

@@ -59,6 +59,9 @@ export {
 } from './lifecycle/auth';
 export { OnPostAuthHandler, OnPostAuthToolkit } from './lifecycle/on_post_auth';
 export { SessionStorageFactory, SessionStorage } from './session_storage';
-export { SessionStorageCookieOptions } from './cookie_session_storage';
+export {
+  SessionStorageCookieOptions,
+  SessionCookieValidationResult,
+} from './cookie_session_storage';
 export * from './types';
 export { BasePath, IBasePath } from './base_path_service';

src/core/server/server.api.md

@@ -1603,7 +1603,8 @@ export interface SessionStorageCookieOptions<T> {
     encryptionKey: string;
     isSecure: boolean;
     name: string;
-    validate: (sessionValue: T) => boolean | Promise<boolean>;
+    // Warning: (ae-forgotten-export) The symbol "SessionCookieValidationResult" needs to be exported by the entry point index.d.ts
+    validate: (sessionValue: T) => SessionCookieValidationResult | boolean | Promise<boolean>;
 }
 
 // @public