feat: add connector factory method

[ruyadorno]

This changeset adds a new connector config option that may be used to define a custom socket factory method. Providing a much more flexible control of the socket connection creation.

Defining a custom connector config value allows Tedious to support a larger variety of environments/setups such as proxy servers using secure socket connections that are used by cloud providers such as GCP.

Linked below, the pg driver for PostgreSQL and the mysql2 driver for MySQL are prior art example of this pattern. Also linked below is the Cloud SQL Node.js Connector, which demonstrates how third-party libraries can leverage the custom socket factory method.

Refs: https://github.com/sidorares/node-mysql2/blob/ba15fe25703665e516ab0a23af8d828d1473b8c3/lib/connection.js#L63-L65
Refs: https://github.com/brianc/node-postgres/blob/b357e1884ad25b23a4ab034b443ddfc8c8261951/packages/pg/lib/connection.js#L20
Refs: https://github.com/GoogleCloudPlatform/cloud-sql-nodejs-connector
Signed-off-by: Ruy Adorno ruyadorno@google.com

[codecov]

Codecov Report

Merging #1540 (0924240) into master (d075b9c) will increase coverage by 0.01%.
The diff coverage is 42.85%.

@@            Coverage Diff             @@
##           master    #1540      +/-   ##
==========================================
+ Coverage   79.67%   79.69%   +0.01%     
==========================================
  Files          91       91              
  Lines        4655     4659       +4     
  Branches      854      856       +2     
==========================================
+ Hits         3709     3713       +4     
+ Misses        680      678       -2     
- Partials      266      268       +2     

Impacted Files	Coverage Δ
src/connection.ts	61.74% <42.85%> (+0.05%)	⬆️

... and 1 file with indirect coverage changes

[arthurschreiber]

The changes look great, just a tiny nitpick. ❤️

How does this interact with encrypted connections? I assume the "Cloud SQL Node.js Connector" proxies via a TLS connection, and then tedious would open another TLS connection over that proxy connection?

Do you know what the perf impact of that setup would be? This doesn't sound great, but as it's only specific to GCP cloud connections, it's definitely no blocker. Just trying to understand if that's something we should document to make people aware of.

Thanks!

[ruyadorno]

How does this interact with encrypted connections? I assume the "Cloud SQL Node.js Connector" proxies via a TLS connection, and then tedious would open another TLS connection over that proxy connection?

For GCP users using the Cloud SQL Node.js Connector the idea is to also set options.ecrypt=false (along with the connection factory method) by default in order to skip the driver encryption, so at the end of the day GCP users are not going to be running a doubly-encrypted communication system.

Every connection open by the factory method provided by the Cloud SQL Node.js Connector will use a TLS socket that uses an ephemeral certificate and keys that are rotated continuously (every hour or so). Essentially moving the encryption layer up a level so that our custom proxy handles the rotating certs logic.

[arthurschreiber]

Oh, I just thought of one more thing. The custom connector should eventually be able to take an AbortSignal so that we can properly forward hitting the connection timeout.

I think the PR can properly be changed as-is for now, but eventually that should be added. What do you think?

[ruyadorno]

I think the PR can properly be changed as-is for now, but eventually that should be added. What do you think?

Sounds good to me!

I guess for a follow up PR then the only changes we'd need to land directly in Tedious would be an usage example of the AbortSignal param in examples/custom-connector.js and maybe also a unit test that uses a custom implementation that supports an AbortSignal? Am I missing any other changes that would need to follow up?

[arthurschreiber]

Thanks for your contribution! ❤️

[github-actions]

🎉 This PR is included in version 16.1.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀