import { IContextProvider , IContextContainer } from '../context' ; import { ICspConfig } from '../csp' ; import { GetAuthState , IsAuthenticated } from './auth_state_storage' ; import { GetAuthHeaders } from './auth_headers_storage' ; import { IRouter } from './router' ; import { HttpServerSetup } from './http_server' ; import { SessionStorageCookieOptions } from './cookie_session_storage' ; import { SessionStorageFactory } from './session_storage' ; import { AuthenticationHandler } from './lifecycle/auth' ; import { OnPreRoutingHandler } from './lifecycle/on_pre_routing' ; import { OnPreAuthHandler } from './lifecycle/on_pre_auth' ; import { OnPostAuthHandler } from './lifecycle/on_post_auth' ; import { OnPreResponseHandler } from './lifecycle/on_pre_response' ; import { IBasePath } from './base_path_service' ; import { ExternalUrlConfig } from '../external_url' ; import type { PluginOpaqueId , RequestHandlerContext } from '..' ; public export type RequestHandlerContextContainer = IContextContainer ; public export type RequestHandlerContextProvider < Context extends RequestHandlerContext , ContextName extends keyof Context > = IContextProvider < Context , ContextName > ; public export interface HttpAuth { /**
     * Gets authentication state for a request. Returned by `auth` interceptor.
     *  GetAuthState get : GetAuthState ; /**
     * Returns authentication status for a request.
     *  IsAuthenticated isAuthenticated : IsAuthenticated ; } example To handle an incoming request in your preboot plugin you should:
 * - Use `@kbn/config-schema` package to create a schema to validate the request `params`, `query`, and `body`. Every incoming request will be validated against the created schema. If validation failed, the request is rejected with `400` status and `Bad request` error without calling the route's handler.
 * To opt out of validating the request, specify `false`.
 * ```ts
 * import { schema, TypeOf } from '@kbn/config-schema';
 * const validate = {
 *   params: schema.object({
 *     id: schema.string(),
 *   }),
 * };
 * ```
 *
 * - Declare a function to respond to incoming request.
 * The function will receive `request` object containing request details: url, headers, matched route, as well as validated `params`, `query`, `body`.
 * And `response` object instructing HTTP server to create HTTP response with information sent back to the client as the response body, headers, and HTTP status.
 * Any exception raised during the handler call will generate `500 Server error` response and log error details for further investigation. See below for returning custom error responses.
 * ```ts
 * const handler = async (context: RequestHandlerContext, request: KibanaRequest, response: ResponseFactory) => {
 *   const data = await findObject(request.params.id);
 *   // creates a command to respond with 'not found' error
 *   if (!data) {
 *     return response.notFound();
 *   }
 *   // creates a command to send found data to the client and set response headers
 *   return response.ok({
 *     body: data,
 *     headers: { 'content-type': 'application/json' }
 *   });
 * }
 * ```
 * * - Acquire `preboot`  IRouter instance and register route handler for GET request to 'path/{id}' path.
 * ```ts
 * import { schema, TypeOf } from '@kbn/config-schema';
 *
 * const validate = {
 *   params: schema.object({
 *     id: schema.string(),
 *   }),
 * };
 *
 * httpPreboot.registerRoutes('my-plugin', (router) => {
 *   router.get({ path: 'path/{id}', validate }, async (context, request, response) => {
 *     const data = await findObject(request.params.id);
 *     if (!data) {
 *       return response.notFound();
 *     }
 *     return response.ok({
 *       body: data,
 *       headers: { 'content-type': 'application/json' }
 *     });
 *   });
 * });
 * ```
 *  public export interface HttpServicePreboot { /**
     * Provides ability to acquire `preboot`  IRouter instance for a particular top-level path and register handler
     * functions for any number of nested routes.
     *
     *  remarks Each route can have only one handler function, which is executed when the route is matched.
     * See the  IRouter documentation for more information.
     *
     *  example public registerRoutes ( path , callback ) : void ; /**
     * Access or manipulate the Kibana base path
     * See  IBasePath .
      basePath : IBasePath ; /**
     * Provides common  HttpServerInfo about the running preboot http server.
      getServerInfo : ( ) => HttpServerInfo ; } internal export interface InternalHttpServicePreboot extends Pick < InternalHttpServiceSetup , 'auth' | 'csp' | 'basePath' | 'externalUrl' | 'registerStaticDir' | 'registerRouteHandlerContext' | 'server' | 'getServerInfo' > { registerRoutes ( path , callback ) : void ; } example public export interface HttpServiceSetup { /**
     * Creates cookie based session storage factory  SessionStorageFactory param cookieOptions SessionStorageCookieOptions - options to configure created cookie session storage.
      createCookieSessionStorageFactory : < T > ( cookieOptions : SessionStorageCookieOptions < T > ) => Promise < SessionStorageFactory < T > > ; remarks It's the only place when you can forward a request to another URL right on the server.
     * Can register any number of registerOnPreRouting, which are called in sequence
     * (from the first registered to the last). See  OnPreRoutingHandler .
     *
     *  param handler OnPreRoutingHandler - function to call.
      registerOnPreRouting : ( handler : OnPreRoutingHandler ) => void ; remarks Can register any number of registerOnPreAuth, which are called in sequence
     * (from the first registered to the last). See  OnPreAuthHandler .
     *
     *  param handler OnPreRoutingHandler - function to call.
      registerOnPreAuth : ( handler : OnPreAuthHandler ) => void ; remarks A handler should return a state to associate with the incoming request.
     * The state can be retrieved later via http.auth.get(..)
     * Only one AuthenticationHandler can be registered. See  AuthenticationHandler .
     *
     *  param handler AuthenticationHandler - function to perform authentication.
      registerAuth : ( handler : AuthenticationHandler ) => void ; remarks The auth state is available at stage via http.auth.get(..)
     * Can register any number of registerOnPostAuth, which are called in sequence
     * (from the first registered to the last). See  OnPostAuthHandler .
     *
     *  param handler OnPostAuthHandler - function to call.
      registerOnPostAuth : ( handler : OnPostAuthHandler ) => void ; remarks Doesn't provide the whole response object.
     * Supports extending response with custom headers.
     * See  OnPreResponseHandler .
     *
     *  param handler OnPreResponseHandler - function to call.
      registerOnPreResponse : ( handler : OnPreResponseHandler ) => void ; /**
     * Access or manipulate the Kibana base path
     * See  IBasePath .
      basePath : IBasePath ; /**
     * Auth status.
     * See  HttpAuth deprecated use  HttpServiceStart . auth instead.
      auth : HttpAuth ; /**
     * The CSP config used for Kibana.
     */ csp : ICspConfig ; remarks Each route can have only one handler function, which is executed when the route is matched.
     * See the  IRouter documentation for more information.
     *
     *  example public createRouter : < Context extends RequestHandlerContext = RequestHandlerContext > ( ) => IRouter < Context > ; example public registerRouteHandlerContext : < Context extends RequestHandlerContext , ContextName extends keyof Context > ( contextName : ContextName , provider : RequestHandlerContextProvider < Context , ContextName > ) => RequestHandlerContextContainer ; /**
     * Provides common  HttpServerInfo about the running http server.
      getServerInfo : ( ) => HttpServerInfo ; } internal export interface InternalHttpServiceSetup extends Omit < HttpServiceSetup , 'createRouter' | 'registerRouteHandlerContext' > { auth : HttpServerSetup [ 'auth' ] ; server : HttpServerSetup [ 'server' ] ; externalUrl : ExternalUrlConfig ; createRouter : < Context extends RequestHandlerContext = RequestHandlerContext > ( path : string , plugin ? : PluginOpaqueId ) => IRouter < Context > ; registerRouterAfterListening : ( router : IRouter ) => void ; registerStaticDir : ( path : string , dirPath : string ) => void ; getAuthHeaders : GetAuthHeaders ; registerRouteHandlerContext : < Context extends RequestHandlerContext , ContextName extends keyof Context > ( pluginOpaqueId : PluginOpaqueId , contextName : ContextName , provider : RequestHandlerContextProvider < Context , ContextName > ) => RequestHandlerContextContainer ; registerPrebootRoutes ( path , callback ) : void ; } public export interface HttpServiceStart { /**
     * Access or manipulate the Kibana base path
     * See  IBasePath .
      basePath : IBasePath ; /**
     * Auth status.
     * See  HttpAuth auth : HttpAuth ; /**
     * Provides common  HttpServerInfo about the running http server.
      getServerInfo : ( ) => HttpServerInfo ; } internal export interface InternalHttpServiceStart extends HttpServiceStart { /** Indicates if the http server is listening on the configured port */ isListening : ( ) => boolean ; } /**
 * Information about what hostname, port, and protocol the server process is
 * running on. Note that this may not match the URL that end-users access
 * Kibana at. For the public URL, see  BasePath . publicBaseUrl .
 *  public export interface HttpServerInfo { /** The name of the Kibana server */ name : string ; /** The hostname of the server */ hostname : string ; /** The port the server is listening on */ port : number ; /** The protocol used by the server */ protocol : 'http' | 'https' | 'socket' ; }