From 1aacc193e4f9d692e76eaee57fed0cc0ac99f571 Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Fri, 5 Jul 2024 15:54:24 +0200 Subject: [PATCH 1/5] Add specification for query users --- .../query_users/SecurityQueryUserRequest.ts | 66 +++++++++++ .../query_users/SecurityQueryUserResponse.ts | 38 +++++++ specification/security/query_users/types.ts | 105 ++++++++++++++++++ 3 files changed, 209 insertions(+) create mode 100644 specification/security/query_users/SecurityQueryUserRequest.ts create mode 100644 specification/security/query_users/SecurityQueryUserResponse.ts create mode 100644 specification/security/query_users/types.ts diff --git a/specification/security/query_users/SecurityQueryUserRequest.ts b/specification/security/query_users/SecurityQueryUserRequest.ts new file mode 100644 index 0000000000..d4aa27d9c9 --- /dev/null +++ b/specification/security/query_users/SecurityQueryUserRequest.ts @@ -0,0 +1,66 @@ +/* + * 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 { UserQueryContainer } from './types' +import { RequestBase } from '@_types/Base' +import { integer } from '@_types/Numeric' +import { Sort, SortResults } from '@_types/sort' + +/** + * Retrieves information for Users in a paginated manner. You can optionally filter the results with a query. + * @rest_spec_name security.query_api_keys + * @availability stack since=8.14.0 stability=stable + * @availability serverless stability=stable visibility=private + * @cluster_privileges read_security + */ +export interface Request extends RequestBase { + body: { + /** + * A query to filter which users to return. + * If the query parameter is missing, it is equivalent to a `match_all` query. + * The query supports a subset of query types, including `match_all`, `bool`, `term`, `terms`, `match`, + * `ids`, `prefix`, `wildcard`, `exists`, `range`, and `simple_query_string`. + * You can query the following information associated with user: `username`, `roles`, `enabled` + */ + query?: UserQueryContainer + /** + * Starting document offset. + * By default, you cannot page through more than 10,000 hits using the from and size parameters. + * To page through more hits, use the `search_after` parameter. + * @server_default 0 + */ + from?: integer + /** + * Fields eligible for sorting are: username, roles, enabled + * In addition, sort can also be applied to the `_doc` field to sort by index order. + * @doc_id sort-search-results */ + sort?: Sort + /** + * The number of hits to return. + * By default, you cannot page through more than 10,000 hits using the `from` and `size` parameters. + * To page through more hits, use the `search_after` parameter. + * @server_default 10 + */ + size?: integer + /** + * Search after definition + */ + search_after?: SortResults + } +} diff --git a/specification/security/query_users/SecurityQueryUserResponse.ts b/specification/security/query_users/SecurityQueryUserResponse.ts new file mode 100644 index 0000000000..e269d776f1 --- /dev/null +++ b/specification/security/query_users/SecurityQueryUserResponse.ts @@ -0,0 +1,38 @@ +/* + * 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 { integer } from '@_types/Numeric' +import {QueryUser} from "@security/query_users/types"; + +export class Response { + body: { + /** + * The total number of users found. + */ + total: integer + /** + * The number of users returned in the response. + */ + count: integer + /** + * A list of user information. + */ + users: QueryUser[] + } +} diff --git a/specification/security/query_users/types.ts b/specification/security/query_users/types.ts new file mode 100644 index 0000000000..ff1c151c3c --- /dev/null +++ b/specification/security/query_users/types.ts @@ -0,0 +1,105 @@ +/* + * 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 { SingleKeyDictionary } from '@spec_utils/Dictionary' +import { Field } from '@_types/common' +import { BoolQuery } from '@_types/query_dsl/compound' +import { SortResults } from '@_types/sort' +import { + ExistsQuery, + IdsQuery, + PrefixQuery, + RangeQuery, + TermQuery, + TermsQuery, + WildcardQuery +} from '@_types/query_dsl/term' +import { MatchQuery, SimpleQueryStringQuery } from '@_types/query_dsl/fulltext' +import { MatchAllQuery } from '@_types/query_dsl/MatchAllQuery' +import {User} from "@security/_types/User"; + +/** + * @variants container + * @non_exhaustive + */ +export class UserQueryContainer { + /** + * Returns users based on their IDs. + * This query uses the user document IDs stored in the `_id` field. + * @doc_id query-dsl-ids-query + */ + ids?: IdsQuery + /** + * matches users matching boolean combinations of other queries. + * @doc_id query-dsl-bool-query + */ + bool?: BoolQuery + /** + * Returns users that contain an indexed value for a field. + * @doc_id query-dsl-exists-query + */ + exists?: ExistsQuery + /** + * Returns users that match a provided text, number, date or boolean value. + * The provided text is analyzed before matching. + * @doc_id query-dsl-match-query + */ + match?: SingleKeyDictionary + /** + * Matches all users, giving them all a `_score` of 1.0. + * @doc_id query-dsl-match-all-query + */ + match_all?: MatchAllQuery + /** + * Returns users that contain a specific prefix in a provided field. + * @doc_id query-dsl-prefix-query + */ + prefix?: SingleKeyDictionary + /** + * Returns users that contain terms within a provided range. + * @doc_id query-dsl-range-query + */ + range?: SingleKeyDictionary + /** + * Returns users based on a provided query string, using a parser with a limited but fault-tolerant syntax. + * @doc_id query-dsl-simple-query-string-query + */ + simple_query_string?: SimpleQueryStringQuery + /** + * Returns users that contain an exact term in a provided field. + * To return a document, the query term must exactly match the queried field's value, including whitespace and capitalization. + * @doc_id query-dsl-term-query + */ + term?: SingleKeyDictionary + /** + * Returns users that contain one or more exact terms in a provided field. + * To return a document, one or more terms must exactly match a field value, including whitespace and capitalization. + * @doc_id query-dsl-terms-query + */ + terms?: TermsQuery + /** + * Returns users that contain terms matching a wildcard pattern. + * @doc_id query-dsl-wildcard-query + */ + wildcard?: SingleKeyDictionary +} + +export class QueryUser extends User { + _sort?: SortResults +} From cde16659c6d8b35ee52f804241825f6bf96725b1 Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Fri, 5 Jul 2024 16:29:17 +0200 Subject: [PATCH 2/5] fixup! Formatting --- specification/security/query_users/SecurityQueryUserResponse.ts | 2 +- specification/security/query_users/types.ts | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/security/query_users/SecurityQueryUserResponse.ts b/specification/security/query_users/SecurityQueryUserResponse.ts index e269d776f1..10a4106550 100644 --- a/specification/security/query_users/SecurityQueryUserResponse.ts +++ b/specification/security/query_users/SecurityQueryUserResponse.ts @@ -18,7 +18,7 @@ */ import { integer } from '@_types/Numeric' -import {QueryUser} from "@security/query_users/types"; +import { QueryUser } from '@security/query_users/types' export class Response { body: { diff --git a/specification/security/query_users/types.ts b/specification/security/query_users/types.ts index ff1c151c3c..e3c19f621a 100644 --- a/specification/security/query_users/types.ts +++ b/specification/security/query_users/types.ts @@ -32,7 +32,7 @@ import { } from '@_types/query_dsl/term' import { MatchQuery, SimpleQueryStringQuery } from '@_types/query_dsl/fulltext' import { MatchAllQuery } from '@_types/query_dsl/MatchAllQuery' -import {User} from "@security/_types/User"; +import { User } from '@security/_types/User' /** * @variants container From 7b8d86d898d84e8599e36a0a4c2f4d13d88a8670 Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Wed, 10 Jul 2024 09:47:36 +0200 Subject: [PATCH 3/5] fixup! Naming --- .../{query_users => query_user}/SecurityQueryUserRequest.ts | 0 .../{query_users => query_user}/SecurityQueryUserResponse.ts | 2 +- specification/security/{query_users => query_user}/types.ts | 0 3 files changed, 1 insertion(+), 1 deletion(-) rename specification/security/{query_users => query_user}/SecurityQueryUserRequest.ts (100%) rename specification/security/{query_users => query_user}/SecurityQueryUserResponse.ts (95%) rename specification/security/{query_users => query_user}/types.ts (100%) diff --git a/specification/security/query_users/SecurityQueryUserRequest.ts b/specification/security/query_user/SecurityQueryUserRequest.ts similarity index 100% rename from specification/security/query_users/SecurityQueryUserRequest.ts rename to specification/security/query_user/SecurityQueryUserRequest.ts diff --git a/specification/security/query_users/SecurityQueryUserResponse.ts b/specification/security/query_user/SecurityQueryUserResponse.ts similarity index 95% rename from specification/security/query_users/SecurityQueryUserResponse.ts rename to specification/security/query_user/SecurityQueryUserResponse.ts index 10a4106550..c37d6344c5 100644 --- a/specification/security/query_users/SecurityQueryUserResponse.ts +++ b/specification/security/query_user/SecurityQueryUserResponse.ts @@ -18,7 +18,7 @@ */ import { integer } from '@_types/Numeric' -import { QueryUser } from '@security/query_users/types' +import { QueryUser } from '@security/query_user/types' export class Response { body: { diff --git a/specification/security/query_users/types.ts b/specification/security/query_user/types.ts similarity index 100% rename from specification/security/query_users/types.ts rename to specification/security/query_user/types.ts From 5c656f29521c956299e9f44ea51260a1df0a6a12 Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Wed, 10 Jul 2024 11:12:41 +0200 Subject: [PATCH 4/5] fixup! spec name --- specification/security/query_user/SecurityQueryUserRequest.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/security/query_user/SecurityQueryUserRequest.ts b/specification/security/query_user/SecurityQueryUserRequest.ts index d4aa27d9c9..e0cdc49aa5 100644 --- a/specification/security/query_user/SecurityQueryUserRequest.ts +++ b/specification/security/query_user/SecurityQueryUserRequest.ts @@ -24,7 +24,7 @@ import { Sort, SortResults } from '@_types/sort' /** * Retrieves information for Users in a paginated manner. You can optionally filter the results with a query. - * @rest_spec_name security.query_api_keys + * @rest_spec_name security.query_user * @availability stack since=8.14.0 stability=stable * @availability serverless stability=stable visibility=private * @cluster_privileges read_security From 606ee1ab0a6929dd2933514dc2b0e047a1b83543 Mon Sep 17 00:00:00 2001 From: Johannes Freden Jansson Date: Wed, 10 Jul 2024 11:33:46 +0200 Subject: [PATCH 5/5] fixup! Add with_profile_uid query param --- .../security/query_user/SecurityQueryUserRequest.ts | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/security/query_user/SecurityQueryUserRequest.ts b/specification/security/query_user/SecurityQueryUserRequest.ts index e0cdc49aa5..977c7bdba2 100644 --- a/specification/security/query_user/SecurityQueryUserRequest.ts +++ b/specification/security/query_user/SecurityQueryUserRequest.ts @@ -63,4 +63,10 @@ export interface Request extends RequestBase { */ search_after?: SortResults } + query_parameters: { + /** + * If true will return the User Profile ID for the users in the query result, if any. + */ + with_profile_uid?: boolean + } }