Summary

initial implementation of #39767
closes #33779

Extends ResponseFactory functionality to configure response payload, status and headers.

Checklist

Use strikethroughs to remove checklist items you don't feel are applicable to this PR.

• [ ] This was checked for cross-browser compatibility, including a check against IE11
• [ ] Any text added follows EUI's writing guidelines, uses sentence case text and includes i18n support
• [ ] Documentation was added for features that require explanation or tutorials
• Unit or functional tests were updated or added to match the most common scenarios
• [ ] This was checked for keyboard-only and screenreader accessibility

For maintainers

• This was checked for breaking API changes and was labeled appropriately
• This includes a feature addition or change that requires a release note and was labeled appropriately

Dev docs

Kibana HTTP Service in the New platform provides own abstraction for work with HTTP stack.
Plugins don't have direct access to hapi server and its primitives anymore. Moreover,
plugins shouldn't rely on the fact that HTTP Service uses one or another library under the hood.
This gives the platform flexibility to upgrade or changing our internal HTTP stack without breaking plugins.
If the HTTP Service lacks functionality you need, we are happy to discuss and support your needs.

To handle an incoming request in your plugin you should:

• Create a Router instance. Router is already configured to use plugin-id to prefix path segment for your routes.

const router = httpSetup.createRouter();

• 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.

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:
  1.context runtime context providing access to Kibana API, specific for a route handler.
  2.request object containing request details: url, headers, matched route, as well as validated params, query, body.
  3.response object instructing HTTP server to create HTTP response with information sent back to the client as the response body, headers, and HTTP status.
  Unlike, hapi route handler in the Legacy platform, 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.

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'
    }
  });
}

• Register route handler for GET request to 'my-app/path/{id}' path

import { schema, TypeOf } from '@kbn/config-schema';
const router = httpSetup.createRouter();

const validate = {
  params: schema.object({
    id: schema.string(),
  }),
};

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'
    }
  });
});