Better HTTP(S) Request options documentation

[Giotino]

What would you like to discuss?

Since we made some modification to the options, this statement

options
Type: object

Any of the https.request options.

from the documentation is no more valid.

Maybe the individual https.Request options should be documented on the got page.

---

Node.JS options (checked ones are those already documented by Got)

From http.request

• agent
• auth
• createConnection (not present in README.md)
• defaultPort
• family
• headers
• host
• hostname
• insecureHTTPParser
• localAddress
• lookup (not present in README.md)
• maxHeaderSize
• method
• path (might be reviewed)
• port (not present in README.md)
• protocol (not present in README.md)
• setHost
• socketPath
• timeout

From tls.createSecureContext (documented https.request)

• ca
• cert
• ciphers (WIP General improvements to HTTPS API (Second Edition) #1435)
• clientCertEngine
• crl
• dhparam
• ecdhCurve
• honorCipherOrder (WIP General improvements to HTTPS API (Second Edition) #1435)
• key
• passphrase
• pfx (Add pfx HTTPS option #1364)
• rejectUnauthorized
• secureOptions
• secureProtocol
• servername
• sessionIdContext
• highWaterMark
• checkServerIdentity (unducumented by Node.JS)

From tls.createSecureContext (but undocumented in https.request)

• minVersion (WIP General improvements to HTTPS API (Second Edition) #1435)
• maxVersion (WIP General improvements to HTTPS API (Second Edition) #1435)

[sindresorhus]

Yes. It's time to do that. We should take the opportunity to see if any of the https.request options could be improved, like we did with your previous PRs.

[Giotino]

I think this should be done in 2 steps.
The first is renaming/remapping current https.Request options, giving deprecation errors for the old ones (as we did in the previous PRs).
The second, to be implemented in got 12, is to not use got options with the request function, but crafting a dedicated options object to be used for the request

[sindresorhus]

That sounds like a good plan.

[Giotino]

I updated the first message with a list of all the options taken by http.request and https.request

[yovanoc]

We can't pass ciphers anymore? ;( I really don't find how to do this now

[Giotino]

We broke the definition of the https.request options, but they're still there.

So, in got 11, you can do something like this

got('https://example.org', {
  ciphers: '...'
} as any);

The ciphers option is going to be included in the https options, when this happen you'll receive deprecation warnings on ciphers.

[markdboyd]

Issued #1364 to add support for the TLS option pfx to the supported HTTPS options

[Giotino]

For all the ciphers fans (@yovanoc @zedd3v): I'm going to add the option in this PR #1435

[szmarczak]

Enabled more HTTPS options here: 83575d5

@Giotino We just need to do the tests and add docs.

[Giotino]

Enabled more HTTPS options here: 83575d5

@Giotino We just need to do the tests and add docs.

https://github.com/Giotino/got/tree/https-tests

I adapted the tests from #1435.
The tests cover:

• ciphers
• honorCipherOrder
• minVersion

Other options are a little bit tricky to test.

[szmarczak]

Great! Can you submit a PR?

[szmarczak]

https://github.com/sindresorhus/got/blob/main/documentation/5-https.md#other-https-options