Add spec and docs for new logs streams endpoints

docs/add-new-api.md

@@ -38,8 +38,7 @@ interface Request {}
 class Response {}
 ```
 
-Try to use less files as possible, for example there is no need to create a custom file for an enum,
-you can define it in the same file where it's used, unless is a commonly used type.
+Try to use the least number of files possible, for example there is no need to create a custom file for an enum as you can define it in the same file where it's used, unless is a commonly used type.
 
 ### Add the endpoint request definition
 

specification/_doc_ids/table.csv

@@ -900,6 +900,9 @@ stop-dfanalytics,https://www.elastic.co/docs/api/doc/elasticsearch/operation/ope
 stop-trained-model-deployment,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-ml-stop-trained-model-deployment,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-trained-model-deployment.html,
 stop-transform,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-transform-stop-transform,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/stop-transform.html,
 stored-fields,https://www.elastic.co/docs/reference/elasticsearch/rest-apis/retrieve-selected-fields#stored-fields,,
+streams-status,https://www.elastic.co/docs/reference/elasticsearch/rest-apis,,
+streams-logs-enable,https://www.elastic.co/docs/reference/elasticsearch/rest-apis,,
+streams-logs-disable,https://www.elastic.co/docs/reference/elasticsearch/rest-apis,,
 synonym-api-examples,https://www.elastic.co/docs/solutions/search/full-text/create-update-synonyms-api-example,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonyms-set.html,
 synonym-rule-create,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-put-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/put-synonym-rule.html,
 synonym-rule-delete,https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-synonyms-delete-synonym-rule,https://www.elastic.co/guide/en/elasticsearch/reference/8.18/delete-synonym-rule.html,

specification/streams/logs_disable/StreamsLogsDisableRequest.ts

@@ -0,0 +1,51 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { RequestBase } from '@_types/Base'
+import { Duration } from '@_types/Time'
+
+/**
+ * Disable logs stream
+ *
+ * This disables the logs stream feature for this cluster.
+ * @rest_spec_name streams.logs_disable
+ * @availability stack since=9.1.0 stability=experimental visibility=feature_flag feature_flag=logs_stream
+ * @cluster_privileges manage
+ * @doc_id streams-logs-disable
+ */
+export interface Request extends RequestBase {
+  urls: [
+    {
+      path: '/_streams/logs/_disable'
+      methods: ['POST']
+    }
+  ]
+  query_parameters: {
+    /**
+     * The period to wait for a connection to the master node.
+     * If no response is received before the timeout expires, the request fails and returns an error.
+     */
+    master_timeout?: Duration
+    /**
+     * The period to wait for a response.
+     * If no response is received before the timeout expires, the request fails and returns an error.
+     */
+    timeout?: Duration
+  }
+}

specification/streams/logs_disable/StreamsLogsDisableResponse.ts

@@ -0,0 +1,25 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { AcknowledgedResponseBase } from '@_types/Base'
+
+export class Response {
+  /** @codegen_name result */
+  body: AcknowledgedResponseBase
+}

specification/streams/logs_disable/examples/200_response/PostStreamsLogsDisableResponseExample1.yaml

@@ -0,0 +1,6 @@
+summary: Disable logs streams
+description: >
+  A successful response from `POST _streams/logs/_disable` endpoint
+# type: response
+value:
+  acknowledged: true

specification/streams/logs_disable/examples/request/PostStreamsDisableRequestExample1.yaml

@@ -0,0 +1,3 @@
+summary: 'Disable the logs streams on this cluster'
+method_request: POST _streams/logs/_disable
+# type: request

specification/streams/logs_enable/StreamsLogsEnableRequest.ts

@@ -0,0 +1,55 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { RequestBase } from '@_types/Base'
+import { Duration } from '@_types/Time'
+
+/**
+ * Enable logs stream
+ *
+ * This enables the logs stream feature for this cluster.
+ *
+ * Note: To protect existing data, this feature can only be enabled on a cluster if
+ * it does not have existing indices or data streams matching the pattern `logs|logs.*`.
+ * If this is the case, a `409 - Conflict` response and error will be returned.
+ * @rest_spec_name streams.logs_enable
+ * @availability stack since=9.1.0 stability=experimental visibility=feature_flag feature_flag=logs_stream
+ * @cluster_privileges manage
+ * @doc_id streams-logs-enable
+ */
+export interface Request extends RequestBase {
+  urls: [
+    {
+      path: '/_streams/logs/_enable'
+      methods: ['POST']
+    }
+  ]
+  query_parameters: {
+    /**
+     * The period to wait for a connection to the master node.
+     * If no response is received before the timeout expires, the request fails and returns an error.
+     */
+    master_timeout?: Duration
+    /**
+     * The period to wait for a response.
+     * If no response is received before the timeout expires, the request fails and returns an error.
+     */
+    timeout?: Duration
+  }
+}

specification/streams/logs_enable/StreamsLogsEnableResponse.ts

@@ -0,0 +1,25 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { AcknowledgedResponseBase } from '@_types/Base'
+
+export class Response {
+  /** @codegen_name result */
+  body: AcknowledgedResponseBase
+}

specification/streams/logs_enable/examples/200_response/PostStreamsLogsEnableResponseExample1.yaml

@@ -0,0 +1,6 @@
+summary: Enable logs streams
+description: >
+  A successful response from `POST _streams/logs/_enable` endpoint
+# type: response
+value:
+  acknowledged: true

specification/streams/logs_enable/examples/409_response/PostStreamsLogsEnableResponseExample2.yaml

@@ -0,0 +1,19 @@
+summary: Enable logs streams - Failure due to conflicting index
+description: >
+  An error response from the `POST _streams/logs/_enable` endpoint caused by attempting to enable logs streams 
+  when an existing index with the name `logs` already exists
+# type: response
+value: |-
+  {
+    "error": {
+      "root_cause": [
+        {
+          "type": "status_exception",
+          "reason": "Cannot enable logs streams: indices named 'logs' or starting with 'logs.' already exist."
+        }
+      ],
+      "type": "status_exception",
+      "reason": "Cannot enable logs streams: indices named 'logs' or starting with 'logs.' already exist."
+    },
+    "status": 409
+  }

specification/streams/logs_enable/examples/request/PostStreamsEnableRequestExample1.yaml

@@ -0,0 +1,3 @@
+summary: 'Enable the logs streams on this cluster'
+method_request: POST _streams/logs/_enable
+# type: request

specification/streams/status/StreamsStatusRequest.ts

@@ -0,0 +1,46 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import { RequestBase } from '@_types/Base'
+import { TimeUnit } from '@_types/Time'
+
+/**
+ * Get the status of streams
+ *
+ * Gets the current status of all stream types
+ * @rest_spec_name streams.status
+ * @availability stack since=9.1.0 stability=experimental visibility=feature_flag feature_flag=logs_stream
+ * @cluster_privileges monitor
+ * @doc_id streams-status
+ */
+export interface Request extends RequestBase {
+  urls: [
+    {
+      path: '/_streams/status'
+      methods: ['GET']
+    }
+  ]
+  query_parameters: {
+    /**
+     * Period to wait for a connection to the master node. If no response is received before the timeout expires, the request fails and returns an error.
+     * @server_default 30s
+     */
+    master_timeout?: TimeUnit
+  }
+}

specification/streams/status/StreamsStatusResponse.ts

@@ -0,0 +1,28 @@
+/*
+ * Licensed to Elasticsearch B.V. under one or more contributor
+ * license agreements. See the NOTICE file distributed with
+ * this work for additional information regarding copyright
+ * ownership. Elasticsearch B.V. licenses this file to you under
+ * the Apache License, Version 2.0 (the "License"); you may
+ * not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *    http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+export class Response {
+  body: {
+    logs: LogsStatus
+  }
+}
+
+export class LogsStatus {
+  enabled: boolean
+}

specification/streams/status/examples/200_response/GetStreamsStatusResponseExample1.yaml

@@ -0,0 +1,9 @@
+summary: Get Streams Status
+  A successful response from `GET _streams/status` that outlines the current state of all wired streams in the cluster.
+# type: response
+value: |-
+  {
+    "logs": {
+      "enabled": true
+    }
+  }

specification/streams/status/examples/request/GetStreamsStatusRequestExample1.yaml

@@ -0,0 +1,3 @@
+summary: 'Get the current status of streams'
+method_request: GET _streams/status
+# type: request

specification/tsconfig.json

@@ -50,6 +50,7 @@
       "@shutdown/*": ["shutdown/*"],
       "@slm/*": ["slm/*"],
       "@snapshot/*": ["snapshot/*"],
+      "@streams/*": ["streams/*"],
       "@sql/*": ["sql/*"],
       "@ssl/*": ["ssl/*"],
       "@synonyms/*": ["synonyms/*"],