Mention h2c usage

Fixes #1751

documentation/2-options.md

@@ -744,6 +744,9 @@ If `true`, the `request` option will default to `http2wrapper.auto` and the enti
 **Note:**
 > - Setting the `request` option to `https.request` will disable HTTP/2 usage, even if the `http2` option is `true`. It is required to use `http2wrapper.auto`.
 
+**Note:**
+> - There is no direct [`h2c`](https://datatracker.ietf.org/doc/html/rfc7540#section-3.1) support. However, you can provide a `h2session` option in a `beforeRequest` hook. See [an example](examples/h2c.js).
+
 ```js
 import got from 'got';
 

documentation/examples/gh-got.js

@@ -14,7 +14,8 @@ const getRateLimit = (headers) => ({
 const instance = got.extend({
 	prefixUrl: 'https://api.github.com',
 	headers: {
-		accept: 'application/vnd.github.v3+json'
+		accept: 'application/vnd.github.v3+json',
+		'user-agent': `${packageJson.name}/${packageJson.version}`
 	},
 	responseType: 'json',
 	context: {

documentation/examples/h2c.js

@@ -0,0 +1,51 @@
+import http2 from 'http2-wrapper';
+import got from 'got';
+
+let sessions = {};
+const getSession = ({origin}) => {
+	if (sessions[origin] && !sessions[origin].destroyed) {
+		return sessions[origin];
+	}
+
+	const session = http2.connect(origin);
+	session.once('error', () => {
+		delete sessions[origin];
+	});
+
+	sessions[origin] = session;
+
+	return session;
+};
+
+const closeSessions = () => {
+	for (const key in sessions) {
+		sessions[key].close();
+	}
+
+	sessions = {};
+};
+
+const instance = got.extend({
+	hooks: {
+		beforeRequest: [
+			options => {
+				options.h2session = getSession(options.url);
+				options.http2 = true;
+				options.request = http2.request;
+			}
+		]
+	}
+});
+
+const server = http2.createServer((request, response) => {
+	response.end('{}');
+});
+
+server.listen(async () => {
+	const url = `http://localhost:${server.address().port}`;
+	const {body, headers} = await instance(url, {context: {h2c: true}});
+	console.log(headers, body);
+
+	closeSessions();
+	server.close();
+});

documentation/tips.md

@@ -236,6 +236,12 @@ const fn = retryCount => {
 fn(0);
 ```
 
+### `h2c`
+
+There is no direct [`h2c`](https://datatracker.ietf.org/doc/html/rfc7540#section-3.1) support.
+
+However, you can provide a `h2session` option in a `beforeRequest` hook. See [an example](examples/h2c.js).
+
 ### Electron `net` module is not supported
 
 Got doesn't support the `electron.net` module. It's missing crucial APIs that are available in Node.js.\

source/core/index.ts

@@ -1052,7 +1052,7 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 		// Reset `prefixUrl`
 		options.prefixUrl = '';
 
-		let request = options.getRequestFunction();
+		let request: ReturnType<Options['getRequestFunction']> | undefined;
 
 		for (const hook of options.hooks.beforeRequest) {
 			// eslint-disable-next-line no-await-in-loop
@@ -1065,6 +1065,10 @@ export default class Request extends Duplex implements RequestEvents<Request> {
 			}
 		}
 
+		if (!request) {
+			request = options.getRequestFunction();
+		}
+
 		const url = options.url as URL;
 
 		this._requestOptions = options.createNativeRequestOptions() as NativeRequestOptions;

source/core/options.ts

@@ -18,7 +18,7 @@ import type {InspectOptions} from 'util';
 import is, {assert} from '@sindresorhus/is';
 import lowercaseKeys from 'lowercase-keys';
 import CacheableLookup from 'cacheable-lookup';
-import http2wrapper from 'http2-wrapper';
+import http2wrapper, {ClientHttp2Session} from 'http2-wrapper';
 import type CacheableRequest from 'cacheable-request';
 import type ResponseLike from 'responselike';
 import type {IncomingMessageWithTimings} from '@szmarczak/http-timer';
@@ -551,6 +551,7 @@ const defaultInternals: Options['_internals'] = {
 		https: undefined,
 		http2: undefined,
 	},
+	h2session: undefined,
 	decompress: true,
 	timeout: {
 		connect: undefined,
@@ -937,6 +938,14 @@ export default class Options {
 		}
 	}
 
+	get h2session(): ClientHttp2Session | undefined {
+		return this._internals.h2session;
+	}
+
+	set h2session(value: ClientHttp2Session | undefined) {
+		this._internals.h2session = value;
+	}
+
 	/**
 	Decompress the response automatically.
 
@@ -2165,6 +2174,9 @@ export default class Options {
 			headers: internals.headers,
 			createConnection: internals.createConnection,
 			timeout: internals.http2 ? getHttp2TimeoutOption(internals) : undefined,
+
+			// HTTP/2 options
+			h2session: internals.h2session,
 		};
 	}