Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add docstrings for Client class and related properties (#2484) #2486

Merged
merged 1 commit into from
Nov 21, 2024
Merged

Add docstrings for Client class and related properties (#2484) #2486

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
85 changes: 84 additions & 1 deletion src/client.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,11 +69,16 @@ if (transportVersion.includes('-')) {
const nodeVersion = process.versions.node

export interface NodeOptions {
/** @property url Elasticsearch node's location */
url: URL
id?: string
/** @property agent Custom HTTP agent options */
agent?: HttpAgentOptions | UndiciAgentOptions
/** @property ssl Overrides default TLS connection settings */
ssl?: TlsConnectionOptions
/** @property headers Custom HTTP headers that should be sent with each request */
headers?: Record<string, any>
/** @property roles Common Elasticsearch roles that can be assigned to this node. Can be helpful when writing custom nodeFilter or nodeSelector functions. */
roles?: {
master: boolean
data: boolean
Expand All @@ -83,40 +88,110 @@ export interface NodeOptions {
}

export interface ClientOptions {
/** @property node Elasticsearch node settings, if there is only one node. Required if `nodes` or `cloud` is not set. */
node?: string | string[] | NodeOptions | NodeOptions[]
/** @property nodes Elasticsearch node settings, if there are multiple nodes. Required if `node` or `cloud` is not set. */
nodes?: string | string[] | NodeOptions | NodeOptions[]
/** @property Connection HTTP connection class to use
* @defaultValue `UndiciConnection` */
Connection?: typeof BaseConnection
/** @property ConnectionPool HTTP connection pool class to use
* @defaultValue `CloudConnectionPool`, if connecting to Elastic Cloud, otherwise `WeightedConnectionPool` */
ConnectionPool?: typeof BaseConnectionPool
/** @property Transport Elastic transport class to use
* @defaultValue `Transport` */
Transport?: typeof Transport
/** @property Serializer Serialization class to use
* @defaultValue `Serializer` */
Serializer?: typeof Serializer
/** @property maxRetries Max number of retries for each request
* @defaultValue 3 */
maxRetries?: number
/** @property requestTimeout Max request timeout in milliseconds for each request
* @defaultValue 30000 */
requestTimeout?: number
/** @property pingTimeout Max number of milliseconds a `ClusterConnectionPool` will wait when pinging nodes before marking them dead
* @defaultValue 3000 */
pingTimeout?: number
/** @property sniffInterval Perform a sniff operation every `n` milliseconds
* @remarks Sniffing might not be the best solution for you. Read https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how to learn more.
* @defaultValue */
sniffInterval?: number | boolean
/** @property sniffOnStart Perform a sniff once the client is started
* @remarks Sniffing might not be the best solution for you. Read https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how to learn more.
* @defaultValue false */
sniffOnStart?: boolean
/** @property sniffEndpoint Endpoint to ping during a sniff
* @remarks Sniffing might not be the best solution for you. Read https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how to learn more.
* @defaultValue "_nodes/_all/http" */
sniffEndpoint?: string
/** @property sniffOnConnectionFault Perform a sniff on connection fault
* @remarks Sniffing might not be the best solution for you. Read https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how to learn more.
* @defaultValue false */
sniffOnConnectionFault?: boolean
/** @property resurrectStrategy Strategy for resurrecting dead nodes when using `ClusterConnectionPool`. 'ping' will issue a test request to a node and resurrect it if it responds. 'optimistic' marks a node as alive without testing it. 'none` will never attempt to revive a dead connection.
* @defaultValue 'ping' */
resurrectStrategy?: 'ping' | 'optimistic' | 'none'
/** @property compression Enables gzip request body compression
* @defaultValue `true` if connecting to Elastic Cloud, otherwise `false`. */
compression?: boolean
/** @property tls [TLS configuraton](https://nodejs.org/api/tls.html)
* @defaultValue null */
tls?: TlsConnectionOptions
/** @property agent Custom HTTP agent options
* @defaultValue null */
agent?: HttpAgentOptions | UndiciAgentOptions | agentFn | false
/** @property nodeFilter A custom function used by the connection pool to determine which nodes are qualified to receive a request
* @defaultValue () => true */
nodeFilter?: nodeFilterFn
/** @property nodeSelector A custom function used by the connection pool to determine which node should receive the next request
* @defaultValue A "round robin" function that loops sequentially through each node in the pool. */
nodeSelector?: nodeSelectorFn
/** @property headers Custom HTTP headers that should be sent with each request
* @defaultValue An object with a custom `user-agent` header */
headers?: Record<string, any>
/** @property opaqueIdPrefix A string prefix to apply to every generated X-Opaque-Id header
* @defaultValue null */
opaqueIdPrefix?: string
/** @property generateRequestId A custom function for generating unique IDs for each request, to make it easier to associate each API request to a single response
* @defaultValue A function that increments a number counter starting from 1 */
generateRequestId?: generateRequestIdFn
/** @property name A name for this client
* @defaultValue 'elasticsearch-js' */
name?: string | symbol
/** @property auth Authentication options for this Elasticsearch cluster
* @defaultValue null */
auth?: BasicAuth | ApiKeyAuth | BearerAuth
/** @property context A custom object attached to each request that can be used to pass data to client events
* @defaultValue null */
context?: Context
/** @property proxy A proxy URL that, when provided, the client will automatically send all requests through
* @defaultValue null */
proxy?: string | URL
/** @property enableMetaHeader If true, adds an header named `x-elastic-client-meta`, containing a small amount of high-level telemetry data, such as the client and platform version
* @defaultValue true */
enableMetaHeader?: boolean
/** @property cloud Custom configuration for connecting to Elastic Cloud, in lieu of a `node` or `nodes` configuration
* @remarks Read https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/client-connecting.html#client-usage for more details
* @defaultValue null */
cloud?: {
id: string
}
/** @property disablePrototypePoisoningProtection Disables safe JSON parsing that protects execution of prototype poisoning attacks; disabled by default, as it can introduce a performance penalty
* @defaultValue true */
disablePrototypePoisoningProtection?: boolean | 'proto' | 'constructor'
/** @property caFingerprint If configured, verifies that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied fingerprint; only accepts SHA256 digest fingerprints
* @defaultValue null */
caFingerprint?: string
/** @property maxResponseSize When configured, verifies that the uncompressed response size is lower than the configured number. If it's higher, it will abort the request. It cannot be higher than `buffer.constants.MAX_STRING_LENGTH`
* @defaultValue null */
maxResponseSize?: number
/** @property maxCompressedResponseSize When configured, verifies that the compressed response size is lower than the configured number. If it's higher, it will abort the request. It cannot be higher than `buffer.constants.MAX_LENGTH`
* @defaultValue null */
maxCompressedResponseSize?: number
/** @property redaction Options for how to redact potentially sensitive data from metadata attached to `Error` objects
* @remarks Read https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/advanced-config.html#redaction for more details
* @defaultValue Configuration that will replace known sources of sensitive data */
redaction?: RedactionOptions
}

Expand All @@ -127,6 +202,7 @@ export default class Client extends API {
transport: SniffingTransport
serializer: Serializer
helpers: Helpers

constructor (opts: ClientOptions) {
super()
// @ts-expect-error kChild symbol is for internal use only
Expand All @@ -139,7 +215,7 @@ export default class Client extends API {

opts.node = `https://${cloudUrls[1]}.${cloudUrls[0]}`

// Cloud has better performances with compression enabled
// Cloud has better performance with compression enabled
// see https://github.com/elastic/elasticsearch-py/pull/704.
// So unless the user specifies otherwise, we enable compression.
if (opts.compression == null) opts.compression = true
Expand Down Expand Up @@ -323,6 +399,10 @@ export default class Client extends API {
})
}

/**
* Creates a child client instance that shared its connection pool with the parent client
* @see {@link https://www.elastic.co/guide/en/elasticsearch/client/javascript-api/current/child.html}
*/
child (opts: ClientOptions): Client {
// Merge the new options with the initial ones
// @ts-expect-error kChild symbol is for internal use only
Expand All @@ -344,6 +424,9 @@ export default class Client extends API {
return new Client(options)
}

/**
* Closes all connections in the connection pool. Connections shared with any parent or child instances will also be closed.
*/
async close (): Promise<void> {
return await this.connectionPool.empty()
}
Expand Down
Loading