From d5b8c5c98215565747f18ae9783aff79a05bb355 Mon Sep 17 00:00:00 2001
From: Walter Rafelsberger <walter@elastic.co>
Date: Mon, 23 May 2022 11:20:57 +0200
Subject: [PATCH] [ML] Fix types for headers. Improves some docs.

---
 packages/kbn-aiops-utils/README.md            |  2 +-
 .../src/lib/accept_compression.ts             |  7 ++-----
 .../kbn-aiops-utils/src/lib/stream_factory.ts | 21 ++++++++++++-------
 .../src/lib/use_fetch_stream.ts               | 14 +++++++++++++
 4 files changed, 30 insertions(+), 14 deletions(-)

diff --git a/packages/kbn-aiops-utils/README.md b/packages/kbn-aiops-utils/README.md
index d0fabe43b38eb9..0dd5984d456ad5 100644
--- a/packages/kbn-aiops-utils/README.md
+++ b/packages/kbn-aiops-utils/README.md
@@ -1,3 +1,3 @@
 # @kbn/aiops-utils
 
-Empty package generated by @kbn/generate
+The `aiops-utils` package contains static utilities maintained by the ML team for AIOps related efforts.
diff --git a/packages/kbn-aiops-utils/src/lib/accept_compression.ts b/packages/kbn-aiops-utils/src/lib/accept_compression.ts
index afae170db9b3f7..4b8b9b04c8e031 100644
--- a/packages/kbn-aiops-utils/src/lib/accept_compression.ts
+++ b/packages/kbn-aiops-utils/src/lib/accept_compression.ts
@@ -6,10 +6,7 @@
  * Side Public License, v 1.
  */
 
-// TODO: Replace these with kbn packaged versions once we have those available to us
-// These originally came from this location below before moving them to this hacked "any" types:
-// import type { Headers } from '@kbn/core/server';
-type Headers = Record<string, unknown>;
+import { IncomingHttpHeaders } from 'http';
 
 /**
  * Returns whether request headers accept a response using gzip compression.
@@ -17,7 +14,7 @@ type Headers = Record<string, unknown>;
  * @param headers - Request headers.
  * @returns boolean
  */
-export function acceptCompression(headers: Headers) {
+export function acceptCompression(headers: IncomingHttpHeaders) {
   let compressed = false;
 
   Object.keys(headers).forEach((key) => {
diff --git a/packages/kbn-aiops-utils/src/lib/stream_factory.ts b/packages/kbn-aiops-utils/src/lib/stream_factory.ts
index 305a993ccad472..ac49d29d602f2c 100644
--- a/packages/kbn-aiops-utils/src/lib/stream_factory.ts
+++ b/packages/kbn-aiops-utils/src/lib/stream_factory.ts
@@ -8,11 +8,7 @@
 
 import { Stream } from 'stream';
 import zlib from 'zlib';
-
-// TODO: Replace these with kbn packaged versions once we have those available to us
-// These originally came from this location below before moving them to this hacked "any" types:
-// import type { Headers } from '@kbn/core/server';
-type Headers = Record<string, unknown>;
+import { IncomingHttpHeaders } from 'http';
 
 import { acceptCompression } from './accept_compression';
 
@@ -33,10 +29,18 @@ interface StreamFactoryReturnType<T = unknown> {
   push: (d: T) => void;
   responseWithHeaders: {
     body: zlib.Gzip | ResponseStream;
-    headers?: Headers;
+    headers?: IncomingHttpHeaders;
   };
 }
 
+/**
+ * Overload to set up a string based response stream with support
+ * for gzip compression depending on provided request headers.
+ *
+ * @param headers - Request headers.
+ * @returns An object with stream attributes and methods.
+ */
+export function streamFactory<T = string>(headers: IncomingHttpHeaders): StreamFactoryReturnType<T>;
 /**
  * Sets up a response stream with support for gzip compression depending on provided
  * request headers. Any non-string data pushed to the stream will be stream as NDJSON.
@@ -44,8 +48,9 @@ interface StreamFactoryReturnType<T = unknown> {
  * @param headers - Request headers.
  * @returns An object with stream attributes and methods.
  */
-export function streamFactory<T = string>(headers: Headers): StreamFactoryReturnType<T>;
-export function streamFactory<T = unknown>(headers: Headers): StreamFactoryReturnType<T> {
+export function streamFactory<T = unknown>(
+  headers: IncomingHttpHeaders
+): StreamFactoryReturnType<T> {
   let streamType: StreamType;
   const isCompressed = acceptCompression(headers);
 
diff --git a/packages/kbn-aiops-utils/src/lib/use_fetch_stream.ts b/packages/kbn-aiops-utils/src/lib/use_fetch_stream.ts
index f7c52a9ecdf09e..4c2801c984142c 100644
--- a/packages/kbn-aiops-utils/src/lib/use_fetch_stream.ts
+++ b/packages/kbn-aiops-utils/src/lib/use_fetch_stream.ts
@@ -20,12 +20,18 @@ import {
 import { fetchStream } from './fetch_stream';
 import { stringReducer, StringReducer } from './string_reducer';
 
+/**
+ * Custom hook type definition of the base params for an NDJSON stream with custom reducer.
+ */
 export interface UseFetchStreamCustomReducerParams {
   endpoint: string;
   body: object;
   reducer: Reducer<any, any>;
 }
 
+/**
+ * Custom hook type definition of the base params for a string base stream without a custom reducer.
+ */
 export interface UseFetchStreamParamsDefault {
   endpoint: string;
   body: object;
@@ -58,6 +64,14 @@ export function useFetchStream<
   options: { reducer: I['reducer']; initialState: ReducerState<I['reducer']> }
 ): UseFetchStreamReturnType<ReducerState<I['reducer']>, ReducerAction<I['reducer']>>;
 
+/**
+ * Custom hook to receive streaming data.
+ *
+ * @param endpoint - API endpoint including Kibana base path.
+ * @param body - API request body.
+ * @param options - Optional custom reducer and initial state.
+ * @returns An object with streaming data and methods act on the stream.
+ */
 export function useFetchStream<I extends UseFetchStreamParamsDefault, BasePath extends string>(
   endpoint: `${BasePath}${I['endpoint']}`,
   body: I['body'],