diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index c329b04e3..01672d3cc 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -89,6 +89,7 @@ import auth from './auth' import BookmarkManager, { BookmarkManagerConfig, bookmarkManager } from './bookmark-manager' import AuthTokenManager, { expirationBasedAuthTokenManager, staticAuthTokenManager, isStaticAuthTokenManger, AuthTokenAndExpiration } from './auth-token-manager' import { SessionConfig, QueryConfig, RoutingControl, routing } from './driver' +import { Config } from './types' import * as types from './types' import * as json from './json' import resultTransformers, { ResultTransformer } from './result-transformers' @@ -254,6 +255,7 @@ export type { BookmarkManagerConfig, AuthTokenManager, AuthTokenAndExpiration, + Config, SessionConfig, QueryConfig, RoutingControl, diff --git a/packages/core/src/types.ts b/packages/core/src/types.ts index b54125572..3714396c1 100644 --- a/packages/core/src/types.ts +++ b/packages/core/src/types.ts @@ -17,6 +17,8 @@ * limitations under the License. */ +import NotificationFilter from './notification-filter' + /** * @private */ @@ -56,7 +58,12 @@ export interface BoltAgent { languageDetails?: string } -export interface Config { +/** + * The Neo4j Driver configuration. + * + * @interface + */ +export class Config { encrypted?: boolean | EncryptionLevel trust?: TrustStrategy trustedCertificates?: string[] @@ -68,13 +75,220 @@ export interface Config { connectionAcquisitionTimeout?: number connectionTimeout?: number disableLosslessIntegers?: boolean + notificationFilter?: NotificationFilter useBigInt?: boolean logging?: LoggingConfig resolver?: (address: string) => string[] | Promise userAgent?: string + + /** + * @constructor + * @private + */ + protected constructor () { + /** + * Encryption level + * + * @type {'ENCRYPTION_ON'|'ENCRYPTION_OFF'|undefined} + */ + this.encrypted = undefined + + /** + * Trust strategy to use if encryption is enabled. + * + * There is no mode to disable trust other than disabling encryption altogether. The reason for + * this is that if you don't know who you are talking to, it is easy for an + * attacker to hijack your encrypted connection, rendering encryption pointless. + * + * TRUST_SYSTEM_CA_SIGNED_CERTIFICATES is the default choice. For NodeJS environments, this + * means that you trust whatever certificates are in the default trusted certificate + * store of the underlying system. For Browser environments, the trusted certificate + * store is usually managed by the browser. Refer to your system or browser documentation + * if you want to explicitly add a certificate as trusted. + * + * TRUST_CUSTOM_CA_SIGNED_CERTIFICATES is another option for trust verification - + * whenever we establish an encrypted connection, we ensure the host is using + * an encryption certificate that is in, or is signed by, a certificate given + * as trusted through configuration. This option is only available for NodeJS environments. + * + * TRUST_ALL_CERTIFICATES means that you trust everything without any verifications + * steps carried out. This option is only available for NodeJS environments and should not + * be used on production systems. + * + * @type {'TRUST_SYSTEM_CA_SIGNED_CERTIFICATES'|'TRUST_CUSTOM_CA_SIGNED_CERTIFICATES'|'TRUST_ALL_CERTIFICATES'|undefined} + */ + this.trust = undefined + + /** + * List of one or more paths to trusted encryption certificates. + * + * This only works in the NodeJS bundle, + * and only matters if you use "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES". + * + * The certificate files should be in regular X.509 PEM format. + * + * For instance, ['./trusted.pem'] + * + * @type {?string[]} + * @see {@link Config#trust} + */ + this.trustedCertificates = [] + + /** + * The maximum total number of connections allowed to be managed by the connection pool, per host. + * + * This includes both in-use and idle connections. + * + * **Default**: ```100``` + * + * @type {number|undefined} + */ + this.maxConnectionPoolSize = 100 + + /** + * The maximum allowed lifetime for a pooled connection in milliseconds. + * + * Pooled connections older than this + * threshold will be closed and removed from the pool. Such discarding happens during connection acquisition + * so that new session is never backed by an old connection. Setting this option to a low value will cause + * a high connection churn and might result in a performance hit. It is recommended to set maximum lifetime + * to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, + * etc. can also limit maximum connection lifetime). No maximum lifetime limit is imposed by default. Zero + * and negative values result in lifetime not being checked. + * + * **Default**: ```60 * 60 * 1000``` (1 hour) + * + * @type {number|undefined} + */ + this.maxConnectionLifetime = 60 * 60 * 1000 // 1 hour + + /** + * The maximum amount of time to wait to acquire a connection from the pool (to either create a new + * connection or borrow an existing one). + * + * **Default**: ```60000``` (1 minute) + * + * @type {number|undefined} + */ + this.connectionAcquisitionTimeout = 60000 // 1 minute + + /** + * Specify the maximum time in milliseconds transactions are allowed to retry via + * {@link Session#executeRead} and {@link Session#executeWrite} functions. + * + * These functions will retry the given unit of work on `ServiceUnavailable`, `SessionExpired` and transient + * errors with exponential backoff using an initial delay of 1 second. + * + * **Default**: ```30000``` (30 seconds) + * + * @type {number|undefined} + */ + this.maxTransactionRetryTime = 30000 // 30 seconds + + /** + * Specify socket connection timeout in milliseconds. + * + * Negative and zero values result in no timeout being applied. + * Connection establishment will be then bound by the timeout configured + * on the operating system level. + * + * **Default**: ```30000``` (30 seconds) + * + * @type {number|undefined} + */ + this.connectionTimeout = 30000 // 30 seconds + + /** + * Make this driver always return native JavaScript numbers for integer values, instead of the + * dedicated {@link Integer} class. + * + * Values that do not fit in native number bit range will be represented as `Number.NEGATIVE_INFINITY` or `Number.POSITIVE_INFINITY`. + * + * **Warning:** {@link ResultSummary} It is not always safe to enable this setting when JavaScript applications are not the only ones + * interacting with the database. Stored numbers might in such case be not representable by native + * `Number` type and thus the driver will return lossy values. This might also happen when data was + * initially imported using neo4j import tool and contained numbers larger than + * `Number.MAX_SAFE_INTEGER`. Driver will then return positive infinity, which is lossy. + * + * **Default**: ```false``` + * + * Default value for this option is `false` because native JavaScript numbers might result + * in loss of precision in the general case. + * + * @type {boolean|undefined} + */ + this.disableLosslessIntegers = false + + /** + * Make this driver always return native Javascript `BigInt` for integer values, + * instead of the dedicated {@link Integer} class or `Number`. + * + * **Warning:** `BigInt` doesn't implement the method `toJSON`. To serialize it as `json`, + * it's needed to add a custom implementation of the `toJSON` on the + * `BigInt.prototype`. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json. + * + * **Default**: ```false``` (for backwards compatibility) + * + * @type {boolean|undefined} + */ + this.useBigInt = false + + /** + * Specify the logging configuration for the driver. Object should have two properties `level` and `logger`. + * + * Property `level` represents the logging level which should be one of: 'error', 'warn', 'info' or 'debug'. This property is optional and + * its default value is 'info'. Levels have priorities: 'error': 0, 'warn': 1, 'info': 2, 'debug': 3. Enabling a certain level also enables all + * levels with lower priority. For example: 'error', 'warn' and 'info' will be logged when 'info' level is configured. + * + * Property `logger` represents the logging function which will be invoked for every log call with an acceptable level. The function should + * take two string arguments `level` and `message`. The function should not execute any blocking or long-running operations + * because it is often executed on a hot path. + * + * No logging is done by default. See `neo4j.logging` object that contains predefined logging implementations. + * + * @type {LoggingConfig|undefined} + * @see {@link logging} + */ + this.logging = undefined + + /** + * Specify a custom server address resolver function used by the routing driver to resolve the initial address used to create the driver. + * + * Such resolution happens: + * * during the very first rediscovery when driver is created + * * when all the known routers from the current routing table have failed and driver needs to fallback to the initial address + * + * In NodeJS environment driver defaults to performing a DNS resolution of the initial address using 'dns' module. + * In browser environment driver uses the initial address as-is. + * Value should be a function that takes a single string argument - the initial address. It should return an array of new addresses. + * Address is a string of shape ':'. Provided function can return either a Promise resolved with an array of addresses + * or array of addresses directly. + * + * @type {function(address: string) {} |undefined} + */ + this.resolver = undefined + + /** + * Configure filter for Notification objects returned in {@Link ResultSummary#notifications}. + * + * See {@link SessionConfig#notificationFilter} for usage instructions. + * + * @type {NotificationFilter|undefined} + */ + this.notificationFilter = undefined + + /** + * Optionally override the default user agent name. + * + * **Default**: ```'neo4j-javascript/'``` + * + * @type {string|undefined} + */ + this.userAgent = undefined + } } -export interface InternalConfig extends Config { +export class InternalConfig extends Config { boltAgent?: BoltAgent } diff --git a/packages/neo4j-driver-deno/lib/core/index.ts b/packages/neo4j-driver-deno/lib/core/index.ts index d9a1ab2f6..fb924bb29 100644 --- a/packages/neo4j-driver-deno/lib/core/index.ts +++ b/packages/neo4j-driver-deno/lib/core/index.ts @@ -89,6 +89,7 @@ import auth from './auth.ts' import BookmarkManager, { BookmarkManagerConfig, bookmarkManager } from './bookmark-manager.ts' import AuthTokenManager, { expirationBasedAuthTokenManager, staticAuthTokenManager, isStaticAuthTokenManger, AuthTokenAndExpiration } from './auth-token-manager.ts' import { SessionConfig, QueryConfig, RoutingControl, routing } from './driver.ts' +import { Config } from './types.ts' import * as types from './types.ts' import * as json from './json.ts' import resultTransformers, { ResultTransformer } from './result-transformers.ts' @@ -254,6 +255,7 @@ export type { BookmarkManagerConfig, AuthTokenManager, AuthTokenAndExpiration, + Config, SessionConfig, QueryConfig, RoutingControl, diff --git a/packages/neo4j-driver-deno/lib/core/types.ts b/packages/neo4j-driver-deno/lib/core/types.ts index b54125572..d595841b4 100644 --- a/packages/neo4j-driver-deno/lib/core/types.ts +++ b/packages/neo4j-driver-deno/lib/core/types.ts @@ -17,6 +17,8 @@ * limitations under the License. */ +import NotificationFilter from './notification-filter.ts' + /** * @private */ @@ -56,7 +58,12 @@ export interface BoltAgent { languageDetails?: string } -export interface Config { +/** + * The Neo4j Driver configuration. + * + * @interface + */ +export class Config { encrypted?: boolean | EncryptionLevel trust?: TrustStrategy trustedCertificates?: string[] @@ -68,13 +75,220 @@ export interface Config { connectionAcquisitionTimeout?: number connectionTimeout?: number disableLosslessIntegers?: boolean + notificationFilter?: NotificationFilter useBigInt?: boolean logging?: LoggingConfig resolver?: (address: string) => string[] | Promise userAgent?: string + + /** + * @constructor + * @private + */ + protected constructor () { + /** + * Encryption level + * + * @type {'ENCRYPTION_ON'|'ENCRYPTION_OFF'|undefined} + */ + this.encrypted = undefined + + /** + * Trust strategy to use if encryption is enabled. + * + * There is no mode to disable trust other than disabling encryption altogether. The reason for + * this is that if you don't know who you are talking to, it is easy for an + * attacker to hijack your encrypted connection, rendering encryption pointless. + * + * TRUST_SYSTEM_CA_SIGNED_CERTIFICATES is the default choice. For NodeJS environments, this + * means that you trust whatever certificates are in the default trusted certificate + * store of the underlying system. For Browser environments, the trusted certificate + * store is usually managed by the browser. Refer to your system or browser documentation + * if you want to explicitly add a certificate as trusted. + * + * TRUST_CUSTOM_CA_SIGNED_CERTIFICATES is another option for trust verification - + * whenever we establish an encrypted connection, we ensure the host is using + * an encryption certificate that is in, or is signed by, a certificate given + * as trusted through configuration. This option is only available for NodeJS environments. + * + * TRUST_ALL_CERTIFICATES means that you trust everything without any verifications + * steps carried out. This option is only available for NodeJS environments and should not + * be used on production systems. + * + * @type {'TRUST_SYSTEM_CA_SIGNED_CERTIFICATES'|'TRUST_CUSTOM_CA_SIGNED_CERTIFICATES'|'TRUST_ALL_CERTIFICATES'|undefined} + */ + this.trust = undefined + + /** + * List of one or more paths to trusted encryption certificates. + * + * This only works in the NodeJS bundle, + * and only matters if you use "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES". + * + * The certificate files should be in regular X.509 PEM format. + * + * For instance, ['./trusted.pem'] + * + * @type {?string[]} + * @see {@link Config#trust} + */ + this.trustedCertificates = [] + + /** + * The maximum total number of connections allowed to be managed by the connection pool, per host. + * + * This includes both in-use and idle connections. + * + * **Default**: ```100``` + * + * @type {number|undefined} + */ + this.maxConnectionPoolSize = 100 + + /** + * The maximum allowed lifetime for a pooled connection in milliseconds. + * + * Pooled connections older than this + * threshold will be closed and removed from the pool. Such discarding happens during connection acquisition + * so that new session is never backed by an old connection. Setting this option to a low value will cause + * a high connection churn and might result in a performance hit. It is recommended to set maximum lifetime + * to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, + * etc. can also limit maximum connection lifetime). No maximum lifetime limit is imposed by default. Zero + * and negative values result in lifetime not being checked. + * + * **Default**: ```60 * 60 * 1000``` (1 hour) + * + * @type {number|undefined} + */ + this.maxConnectionLifetime = 60 * 60 * 1000 // 1 hour + + /** + * The maximum amount of time to wait to acquire a connection from the pool (to either create a new + * connection or borrow an existing one). + * + * **Default**: ```60000``` (1 minute) + * + * @type {number|undefined} + */ + this.connectionAcquisitionTimeout = 60000 // 1 minute + + /** + * Specify the maximum time in milliseconds transactions are allowed to retry via + * {@link Session#executeRead} and {@link Session#executeWrite} functions. + * + * These functions will retry the given unit of work on `ServiceUnavailable`, `SessionExpired` and transient + * errors with exponential backoff using an initial delay of 1 second. + * + * **Default**: ```30000``` (30 seconds) + * + * @type {number|undefined} + */ + this.maxTransactionRetryTime = 30000 // 30 seconds + + /** + * Specify socket connection timeout in milliseconds. + * + * Negative and zero values result in no timeout being applied. + * Connection establishment will be then bound by the timeout configured + * on the operating system level. + * + * **Default**: ```30000``` (30 seconds) + * + * @type {number|undefined} + */ + this.connectionTimeout = 30000 // 30 seconds + + /** + * Make this driver always return native JavaScript numbers for integer values, instead of the + * dedicated {@link Integer} class. + * + * Values that do not fit in native number bit range will be represented as `Number.NEGATIVE_INFINITY` or `Number.POSITIVE_INFINITY`. + * + * **Warning:** {@link ResultSummary} It is not always safe to enable this setting when JavaScript applications are not the only ones + * interacting with the database. Stored numbers might in such case be not representable by native + * `Number` type and thus the driver will return lossy values. This might also happen when data was + * initially imported using neo4j import tool and contained numbers larger than + * `Number.MAX_SAFE_INTEGER`. Driver will then return positive infinity, which is lossy. + * + * **Default**: ```false``` + * + * Default value for this option is `false` because native JavaScript numbers might result + * in loss of precision in the general case. + * + * @type {boolean|undefined} + */ + this.disableLosslessIntegers = false + + /** + * Make this driver always return native Javascript `BigInt` for integer values, + * instead of the dedicated {@link Integer} class or `Number`. + * + * **Warning:** `BigInt` doesn't implement the method `toJSON`. To serialize it as `json`, + * it's needed to add a custom implementation of the `toJSON` on the + * `BigInt.prototype`. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json. + * + * **Default**: ```false``` (for backwards compatibility) + * + * @type {boolean|undefined} + */ + this.useBigInt = false + + /** + * Specify the logging configuration for the driver. Object should have two properties `level` and `logger`. + * + * Property `level` represents the logging level which should be one of: 'error', 'warn', 'info' or 'debug'. This property is optional and + * its default value is 'info'. Levels have priorities: 'error': 0, 'warn': 1, 'info': 2, 'debug': 3. Enabling a certain level also enables all + * levels with lower priority. For example: 'error', 'warn' and 'info' will be logged when 'info' level is configured. + * + * Property `logger` represents the logging function which will be invoked for every log call with an acceptable level. The function should + * take two string arguments `level` and `message`. The function should not execute any blocking or long-running operations + * because it is often executed on a hot path. + * + * No logging is done by default. See `neo4j.logging` object that contains predefined logging implementations. + * + * @type {LoggingConfig|undefined} + * @see {@link logging} + */ + this.logging = undefined + + /** + * Specify a custom server address resolver function used by the routing driver to resolve the initial address used to create the driver. + * + * Such resolution happens: + * * during the very first rediscovery when driver is created + * * when all the known routers from the current routing table have failed and driver needs to fallback to the initial address + * + * In NodeJS environment driver defaults to performing a DNS resolution of the initial address using 'dns' module. + * In browser environment driver uses the initial address as-is. + * Value should be a function that takes a single string argument - the initial address. It should return an array of new addresses. + * Address is a string of shape ':'. Provided function can return either a Promise resolved with an array of addresses + * or array of addresses directly. + * + * @type {function(address: string) {} |undefined} + */ + this.resolver = undefined + + /** + * Configure filter for Notification objects returned in {@Link ResultSummary#notifications}. + * + * See {@link SessionConfig#notificationFilter} for usage instructions. + * + * @type {NotificationFilter|undefined} + */ + this.notificationFilter = undefined + + /** + * Optionally override the default user agent name. + * + * **Default**: ```'neo4j-javascript/'``` + * + * @type {string|undefined} + */ + this.userAgent = undefined + } } -export interface InternalConfig extends Config { +export class InternalConfig extends Config { boltAgent?: BoltAgent } diff --git a/packages/neo4j-driver-deno/lib/mod.ts b/packages/neo4j-driver-deno/lib/mod.ts index 767b40631..e0495cac0 100644 --- a/packages/neo4j-driver-deno/lib/mod.ts +++ b/packages/neo4j-driver-deno/lib/mod.ts @@ -151,134 +151,9 @@ function createAuthManager (authTokenOrProvider: AuthToken | AuthTokenManager): * Construct a new Neo4j Driver. This is your main entry point for this * library. * - * ## Configuration - * - * This function optionally takes a configuration argument. Available configuration - * options are as follows: - * - * { - * // Encryption level: ENCRYPTION_ON or ENCRYPTION_OFF. - * encrypted: ENCRYPTION_ON|ENCRYPTION_OFF - * - * // Trust strategy to use if encryption is enabled. There is no mode to disable - * // trust other than disabling encryption altogether. The reason for - * // this is that if you don't know who you are talking to, it is easy for an - * // attacker to hijack your encrypted connection, rendering encryption pointless. - * // - * // TRUST_SYSTEM_CA_SIGNED_CERTIFICATES is the default choice. For NodeJS environments, this - * // means that you trust whatever certificates are in the default trusted certificate - * // store of the underlying system. For Browser environments, the trusted certificate - * // store is usually managed by the browser. Refer to your system or browser documentation - * // if you want to explicitly add a certificate as trusted. - * // - * // TRUST_CUSTOM_CA_SIGNED_CERTIFICATES is another option for trust verification - - * // whenever we establish an encrypted connection, we ensure the host is using - * // an encryption certificate that is in, or is signed by, a certificate given - * // as trusted through configuration. This option is only available for NodeJS environments. - * // - * // TRUST_ALL_CERTIFICATES means that you trust everything without any verifications - * // steps carried out. This option is only available for NodeJS environments and should not - * // be used on production systems. - * trust: "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES" | "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES" | - * "TRUST_ALL_CERTIFICATES", - * - * // List of one or more paths to trusted encryption certificates. This only - * // works in the NodeJS bundle, and only matters if you use "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES". - * // The certificate files should be in regular X.509 PEM format. - * // For instance, ['./trusted.pem'] - * trustedCertificates: [], - * - * // The maximum total number of connections allowed to be managed by the connection pool, per host. - * // This includes both in-use and idle connections. No maximum connection pool size is imposed - * // by default. - * maxConnectionPoolSize: 100, - * - * // The maximum allowed lifetime for a pooled connection in milliseconds. Pooled connections older than this - * // threshold will be closed and removed from the pool. Such discarding happens during connection acquisition - * // so that new session is never backed by an old connection. Setting this option to a low value will cause - * // a high connection churn and might result in a performance hit. It is recommended to set maximum lifetime - * // to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, - * // etc. can also limit maximum connection lifetime). No maximum lifetime limit is imposed by default. Zero - * // and negative values result in lifetime not being checked. - * maxConnectionLifetime: 60 * 60 * 1000, // 1 hour - * - * // The maximum amount of time to wait to acquire a connection from the pool (to either create a new - * // connection or borrow an existing one. - * connectionAcquisitionTimeout: 60000, // 1 minute - * - * // Specify the maximum time in milliseconds transactions are allowed to retry via - * // `Session#executeRead()` and `Session#executeWrite()` functions. - * // These functions will retry the given unit of work on `ServiceUnavailable`, `SessionExpired` and transient - * // errors with exponential backoff using initial delay of 1 second. - * // Default value is 30000 which is 30 seconds. - * maxTransactionRetryTime: 30000, // 30 seconds - * - * // Specify socket connection timeout in milliseconds. Numeric values are expected. Negative and zero values - * // result in no timeout being applied. Connection establishment will be then bound by the timeout configured - * // on the operating system level. Default value is 30000, which is 30 seconds. - * connectionTimeout: 30000, // 30 seconds - * - * // Make this driver always return native JavaScript numbers for integer values, instead of the - * // dedicated {@link Integer} class. Values that do not fit in native number bit range will be represented as - * // `Number.NEGATIVE_INFINITY` or `Number.POSITIVE_INFINITY`. - * // **Warning:** ResultSummary It is not always safe to enable this setting when JavaScript applications are not the only ones - * // interacting with the database. Stored numbers might in such case be not representable by native - * // {@link Number} type and thus driver will return lossy values. This might also happen when data was - * // initially imported using neo4j import tool and contained numbers larger than - * // `Number.MAX_SAFE_INTEGER`. Driver will then return positive infinity, which is lossy. - * // Default value for this option is `false` because native JavaScript numbers might result - * // in loss of precision in the general case. - * disableLosslessIntegers: false, - * - * // Make this driver always return native Javascript {@link BigInt} for integer values, instead of the dedicated {@link Integer} class or {@link Number}. - * // - * // Default value for this option is `false` for backwards compatibility. - * // - * // **Warning:** `BigInt` doesn't implement the method `toJSON`. In maner of serialize it as `json`, It's needed to add a custom implementation of the `toJSON` on the - * // `BigInt.prototype` {@see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json} - * useBigInt: false, - * - * // Specify the logging configuration for the driver. Object should have two properties `level` and `logger`. - * // - * // Property `level` represents the logging level which should be one of: 'error', 'warn', 'info' or 'debug'. This property is optional and - * // its default value is 'info'. Levels have priorities: 'error': 0, 'warn': 1, 'info': 2, 'debug': 3. Enabling a certain level also enables all - * // levels with lower priority. For example: 'error', 'warn' and 'info' will be logged when 'info' level is configured. - * // - * // Property `logger` represents the logging function which will be invoked for every log call with an acceptable level. The function should - * // take two string arguments `level` and `message`. The function should not execute any blocking or long-running operations - * // because it is often executed on a hot path. - * // - * // No logging is done by default. See `neo4j.logging` object that contains predefined logging implementations. - * logging: { - * level: 'info', - * logger: (level, message) => console.log(level + ' ' + message) - * }, - * - * // Specify a custom server address resolver function used by the routing driver to resolve the initial address used to create the driver. - * // Such resolution happens: - * // * during the very first rediscovery when driver is created - * // * when all the known routers from the current routing table have failed and driver needs to fallback to the initial address - * // - * // In NodeJS environment driver defaults to performing a DNS resolution of the initial address using 'dns' module. - * // In browser environment driver uses the initial address as-is. - * // Value should be a function that takes a single string argument - the initial address. It should return an array of new addresses. - * // Address is a string of shape ':'. Provided function can return either a Promise resolved with an array of addresses - * // or array of addresses directly. - * resolver: function(address) { - * return ['127.0.0.1:8888', 'fallback.db.com:7687']; - * }, - * - * // Configure filter for Notification objects returned in ResultSummary#notifications. - * // See SessionConfig#notificationFilter for usage instructions. - * notificationFilter: undefined, - * - * // Optionally override the default user agent name. - * userAgent: USER_AGENT - * } - * * @param {string} url The URL for the Neo4j database, for instance "neo4j://localhost" and/or "bolt://localhost" * @param {Map| function()} authToken Authentication credentials. See {@link auth} for helpers. - * @param {Object} config Configuration object. See the configuration section above for details. + * @param {Config} config Configuration object. See the configuration section above for details. * @returns {Driver} */ function driver ( diff --git a/packages/neo4j-driver-lite/src/index.ts b/packages/neo4j-driver-lite/src/index.ts index c168827d1..f3ec6ad10 100644 --- a/packages/neo4j-driver-lite/src/index.ts +++ b/packages/neo4j-driver-lite/src/index.ts @@ -150,134 +150,9 @@ function createAuthManager (authTokenOrProvider: AuthToken | AuthTokenManager): * Construct a new Neo4j Driver. This is your main entry point for this * library. * - * ## Configuration - * - * This function optionally takes a configuration argument. Available configuration - * options are as follows: - * - * { - * // Encryption level: ENCRYPTION_ON or ENCRYPTION_OFF. - * encrypted: ENCRYPTION_ON|ENCRYPTION_OFF - * - * // Trust strategy to use if encryption is enabled. There is no mode to disable - * // trust other than disabling encryption altogether. The reason for - * // this is that if you don't know who you are talking to, it is easy for an - * // attacker to hijack your encrypted connection, rendering encryption pointless. - * // - * // TRUST_SYSTEM_CA_SIGNED_CERTIFICATES is the default choice. For NodeJS environments, this - * // means that you trust whatever certificates are in the default trusted certificate - * // store of the underlying system. For Browser environments, the trusted certificate - * // store is usually managed by the browser. Refer to your system or browser documentation - * // if you want to explicitly add a certificate as trusted. - * // - * // TRUST_CUSTOM_CA_SIGNED_CERTIFICATES is another option for trust verification - - * // whenever we establish an encrypted connection, we ensure the host is using - * // an encryption certificate that is in, or is signed by, a certificate given - * // as trusted through configuration. This option is only available for NodeJS environments. - * // - * // TRUST_ALL_CERTIFICATES means that you trust everything without any verifications - * // steps carried out. This option is only available for NodeJS environments and should not - * // be used on production systems. - * trust: "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES" | "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES" | - * "TRUST_ALL_CERTIFICATES", - * - * // List of one or more paths to trusted encryption certificates. This only - * // works in the NodeJS bundle, and only matters if you use "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES". - * // The certificate files should be in regular X.509 PEM format. - * // For instance, ['./trusted.pem'] - * trustedCertificates: [], - * - * // The maximum total number of connections allowed to be managed by the connection pool, per host. - * // This includes both in-use and idle connections. No maximum connection pool size is imposed - * // by default. - * maxConnectionPoolSize: 100, - * - * // The maximum allowed lifetime for a pooled connection in milliseconds. Pooled connections older than this - * // threshold will be closed and removed from the pool. Such discarding happens during connection acquisition - * // so that new session is never backed by an old connection. Setting this option to a low value will cause - * // a high connection churn and might result in a performance hit. It is recommended to set maximum lifetime - * // to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, - * // etc. can also limit maximum connection lifetime). No maximum lifetime limit is imposed by default. Zero - * // and negative values result in lifetime not being checked. - * maxConnectionLifetime: 60 * 60 * 1000, // 1 hour - * - * // The maximum amount of time to wait to acquire a connection from the pool (to either create a new - * // connection or borrow an existing one. - * connectionAcquisitionTimeout: 60000, // 1 minute - * - * // Specify the maximum time in milliseconds transactions are allowed to retry via - * // `Session#executeRead()` and `Session#executeWrite()` functions. - * // These functions will retry the given unit of work on `ServiceUnavailable`, `SessionExpired` and transient - * // errors with exponential backoff using initial delay of 1 second. - * // Default value is 30000 which is 30 seconds. - * maxTransactionRetryTime: 30000, // 30 seconds - * - * // Specify socket connection timeout in milliseconds. Numeric values are expected. Negative and zero values - * // result in no timeout being applied. Connection establishment will be then bound by the timeout configured - * // on the operating system level. Default value is 30000, which is 30 seconds. - * connectionTimeout: 30000, // 30 seconds - * - * // Make this driver always return native JavaScript numbers for integer values, instead of the - * // dedicated {@link Integer} class. Values that do not fit in native number bit range will be represented as - * // `Number.NEGATIVE_INFINITY` or `Number.POSITIVE_INFINITY`. - * // **Warning:** ResultSummary It is not always safe to enable this setting when JavaScript applications are not the only ones - * // interacting with the database. Stored numbers might in such case be not representable by native - * // {@link Number} type and thus driver will return lossy values. This might also happen when data was - * // initially imported using neo4j import tool and contained numbers larger than - * // `Number.MAX_SAFE_INTEGER`. Driver will then return positive infinity, which is lossy. - * // Default value for this option is `false` because native JavaScript numbers might result - * // in loss of precision in the general case. - * disableLosslessIntegers: false, - * - * // Make this driver always return native Javascript {@link BigInt} for integer values, instead of the dedicated {@link Integer} class or {@link Number}. - * // - * // Default value for this option is `false` for backwards compatibility. - * // - * // **Warning:** `BigInt` doesn't implement the method `toJSON`. In maner of serialize it as `json`, It's needed to add a custom implementation of the `toJSON` on the - * // `BigInt.prototype` {@see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json} - * useBigInt: false, - * - * // Specify the logging configuration for the driver. Object should have two properties `level` and `logger`. - * // - * // Property `level` represents the logging level which should be one of: 'error', 'warn', 'info' or 'debug'. This property is optional and - * // its default value is 'info'. Levels have priorities: 'error': 0, 'warn': 1, 'info': 2, 'debug': 3. Enabling a certain level also enables all - * // levels with lower priority. For example: 'error', 'warn' and 'info' will be logged when 'info' level is configured. - * // - * // Property `logger` represents the logging function which will be invoked for every log call with an acceptable level. The function should - * // take two string arguments `level` and `message`. The function should not execute any blocking or long-running operations - * // because it is often executed on a hot path. - * // - * // No logging is done by default. See `neo4j.logging` object that contains predefined logging implementations. - * logging: { - * level: 'info', - * logger: (level, message) => console.log(level + ' ' + message) - * }, - * - * // Specify a custom server address resolver function used by the routing driver to resolve the initial address used to create the driver. - * // Such resolution happens: - * // * during the very first rediscovery when driver is created - * // * when all the known routers from the current routing table have failed and driver needs to fallback to the initial address - * // - * // In NodeJS environment driver defaults to performing a DNS resolution of the initial address using 'dns' module. - * // In browser environment driver uses the initial address as-is. - * // Value should be a function that takes a single string argument - the initial address. It should return an array of new addresses. - * // Address is a string of shape ':'. Provided function can return either a Promise resolved with an array of addresses - * // or array of addresses directly. - * resolver: function(address) { - * return ['127.0.0.1:8888', 'fallback.db.com:7687']; - * }, - * - * // Configure filter for Notification objects returned in ResultSummary#notifications. - * // See SessionConfig#notificationFilter for usage instructions. - * notificationFilter: undefined, - * - * // Optionally override the default user agent name. - * userAgent: USER_AGENT - * } - * * @param {string} url The URL for the Neo4j database, for instance "neo4j://localhost" and/or "bolt://localhost" * @param {Map| function()} authToken Authentication credentials. See {@link auth} for helpers. - * @param {Object} config Configuration object. See the configuration section above for details. + * @param {Config} config Configuration object. See the configuration section above for details. * @returns {Driver} */ function driver ( diff --git a/packages/neo4j-driver/src/index.js b/packages/neo4j-driver/src/index.js index 2cc318006..3dfce7777 100644 --- a/packages/neo4j-driver/src/index.js +++ b/packages/neo4j-driver/src/index.js @@ -120,141 +120,16 @@ function createAuthManager (authTokenOrManager) { * Construct a new Neo4j Driver. This is your main entry point for this * library. * - * ## Configuration - * - * This function optionally takes a configuration argument. Available configuration - * options are as follows: - * - * { - * // Encryption level: ENCRYPTION_ON or ENCRYPTION_OFF. - * encrypted: ENCRYPTION_ON|ENCRYPTION_OFF - * - * // Trust strategy to use if encryption is enabled. There is no mode to disable - * // trust other than disabling encryption altogether. The reason for - * // this is that if you don't know who you are talking to, it is easy for an - * // attacker to hijack your encrypted connection, rendering encryption pointless. - * // - * // TRUST_SYSTEM_CA_SIGNED_CERTIFICATES is the default choice. For NodeJS environments, this - * // means that you trust whatever certificates are in the default trusted certificate - * // store of the underlying system. For Browser environments, the trusted certificate - * // store is usually managed by the browser. Refer to your system or browser documentation - * // if you want to explicitly add a certificate as trusted. - * // - * // TRUST_CUSTOM_CA_SIGNED_CERTIFICATES is another option for trust verification - - * // whenever we establish an encrypted connection, we ensure the host is using - * // an encryption certificate that is in, or is signed by, a certificate given - * // as trusted through configuration. This option is only available for NodeJS environments. - * // - * // TRUST_ALL_CERTIFICATES means that you trust everything without any verifications - * // steps carried out. This option is only available for NodeJS environments and should not - * // be used on production systems. - * trust: "TRUST_SYSTEM_CA_SIGNED_CERTIFICATES" | "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES" | - * "TRUST_ALL_CERTIFICATES", - * - * // List of one or more paths to trusted encryption certificates. This only - * // works in the NodeJS bundle, and only matters if you use "TRUST_CUSTOM_CA_SIGNED_CERTIFICATES". - * // The certificate files should be in regular X.509 PEM format. - * // For instance, ['./trusted.pem'] - * trustedCertificates: [], - * - * // The maximum total number of connections allowed to be managed by the connection pool, per host. - * // This includes both in-use and idle connections. No maximum connection pool size is imposed - * // by default. - * maxConnectionPoolSize: 100, - * - * // The maximum allowed lifetime for a pooled connection in milliseconds. Pooled connections older than this - * // threshold will be closed and removed from the pool. Such discarding happens during connection acquisition - * // so that new session is never backed by an old connection. Setting this option to a low value will cause - * // a high connection churn and might result in a performance hit. It is recommended to set maximum lifetime - * // to a slightly smaller value than the one configured in network equipment (load balancer, proxy, firewall, - * // etc. can also limit maximum connection lifetime). No maximum lifetime limit is imposed by default. Zero - * // and negative values result in lifetime not being checked. - * maxConnectionLifetime: 60 * 60 * 1000, // 1 hour - * - * // The maximum amount of time to wait to acquire a connection from the pool (to either create a new - * // connection or borrow an existing one. - * connectionAcquisitionTimeout: 60000, // 1 minute - * - * // Specify the maximum time in milliseconds transactions are allowed to retry via - * // `Session#executeRead()` and `Session#executeWrite()` functions. - * // These functions will retry the given unit of work on `ServiceUnavailable`, `SessionExpired` and transient - * // errors with exponential backoff using initial delay of 1 second. - * // Default value is 30000 which is 30 seconds. - * maxTransactionRetryTime: 30000, // 30 seconds - * - * // Specify socket connection timeout in milliseconds. Numeric values are expected. Negative and zero values - * // result in no timeout being applied. Connection establishment will be then bound by the timeout configured - * // on the operating system level. Default value is 30000, which is 30 seconds. - * connectionTimeout: 30000, // 30 seconds - * - * // Make this driver always return native JavaScript numbers for integer values, instead of the - * // dedicated {@link Integer} class. Values that do not fit in native number bit range will be represented as - * // `Number.NEGATIVE_INFINITY` or `Number.POSITIVE_INFINITY`. - * // **Warning:** ResultSummary It is not always safe to enable this setting when JavaScript applications are not the only ones - * // interacting with the database. Stored numbers might in such case be not representable by native - * // {@link Number} type and thus driver will return lossy values. This might also happen when data was - * // initially imported using neo4j import tool and contained numbers larger than - * // `Number.MAX_SAFE_INTEGER`. Driver will then return positive infinity, which is lossy. - * // Default value for this option is `false` because native JavaScript numbers might result - * // in loss of precision in the general case. - * disableLosslessIntegers: false, - * - * // Make this driver always return native Javascript {@link BigInt} for integer values, instead of the dedicated {@link Integer} class or {@link Number}. - * // - * // Default value for this option is `false` for backwards compatibility. - * // - * // **Warning:** `BigInt` doesn't implement the method `toJSON`. In maner of serialize it as `json`, It's needed to add a custom implementation of the `toJSON` on the - * // `BigInt.prototype` {@see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/BigInt#use_within_json} - * useBigInt: false, - * - * // Specify the logging configuration for the driver. Object should have two properties `level` and `logger`. - * // - * // Property `level` represents the logging level which should be one of: 'error', 'warn', 'info' or 'debug'. This property is optional and - * // its default value is 'info'. Levels have priorities: 'error': 0, 'warn': 1, 'info': 2, 'debug': 3. Enabling a certain level also enables all - * // levels with lower priority. For example: 'error', 'warn' and 'info' will be logged when 'info' level is configured. - * // - * // Property `logger` represents the logging function which will be invoked for every log call with an acceptable level. The function should - * // take two string arguments `level` and `message`. The function should not execute any blocking or long-running operations - * // because it is often executed on a hot path. - * // - * // No logging is done by default. See `neo4j.logging` object that contains predefined logging implementations. - * logging: { - * level: 'info', - * logger: (level, message) => console.log(level + ' ' + message) - * }, - * - * // Specify a custom server address resolver function used by the routing driver to resolve the initial address used to create the driver. - * // Such resolution happens: - * // * during the very first rediscovery when driver is created - * // * when all the known routers from the current routing table have failed and driver needs to fallback to the initial address - * // - * // In NodeJS environment driver defaults to performing a DNS resolution of the initial address using 'dns' module. - * // In browser environment driver uses the initial address as-is. - * // Value should be a function that takes a single string argument - the initial address. It should return an array of new addresses. - * // Address is a string of shape ':'. Provided function can return either a Promise resolved with an array of addresses - * // or array of addresses directly. - * resolver: function(address) { - * return ['127.0.0.1:8888', 'fallback.db.com:7687']; - * }, - * - * // Configure filter for Notification objects returned in ResultSummary#notifications. - * // See SessionConfig#notificationFilter for usage instructions. - * notificationFilter: undefined, - * - * // Optionally override the default user agent name. - * userAgent: USER_AGENT - * } - * * @param {string} url The URL for the Neo4j database, for instance "neo4j://localhost" and/or "bolt://localhost" * @param {Map} authToken Authentication credentials. See {@link auth} for helpers. - * @param {Object} config Configuration object. See the configuration section above for details. + * @param {Config} config Configuration object. * @returns {Driver} */ function driver (url, authToken, config = {}) { assertString(url, 'Bolt URL') const parsedUrl = urlUtil.parseDatabaseUrl(url) - // Determine entryption/trust options from the URL. + // Determine encryption/trust options from the URL. let routing = false let encrypted = false let trust