Skip to content

Commit fd25355

Browse files
kgrytekgryte
committed
feat: add net/http2-secure-server
--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: passed - task: lint_editorconfig status: passed - task: lint_markdown status: passed - task: lint_package_json status: passed - task: lint_repl_help status: passed - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: passed - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: na - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed ---
1 parent 7d24076 commit fd25355

File tree

18 files changed

+1995
-0
lines changed

18 files changed

+1995
-0
lines changed

‎lib/node_modules/@stdlib/net/http2-secure-server/README.md

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
<!--
2+
3+
@license Apache-2.0
4+
5+
Copyright (c) 2025 The Stdlib Authors.
6+
7+
Licensed under the Apache License, Version 2.0 (the "License");
8+
you may not use this file except in compliance with the License.
9+
You may obtain a copy of the License at
10+
11+
http://www.apache.org/licenses/LICENSE-2.0
12+
13+
Unless required by applicable law or agreed to in writing, software
14+
distributed under the License is distributed on an "AS IS" BASIS,
15+
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16+
See the License for the specific language governing permissions and
17+
limitations under the License.
18+
19+
-->
20+
21+
# HTTP/2 Server
22+
23+
> [HTTP/2][nodejs-http2] server.
24+
25+
<section class="usage">
26+
27+
## Usage
28+
29+
```javascript
30+
var http2ServerFactory = require( '@stdlib/net/http2-secure-server' );
31+
```
32+
33+
#### http2ServerFactory( options\[, requestListener] )
34+
35+
Returns a function to create an [HTTP/2][nodejs-http2] server.
36+
37+
```javascript
38+
var opts = {
39+
'cert': readFileSync( resolve( __dirname, 'examples', 'localhost-cert.pem' ) ),
40+
'key': readFileSync( resolve( __dirname, 'examples', 'localhost-privkey.pem' ) )
41+
};
42+
var http2Server = http2ServerFactory( opts );
43+
```
44+
45+
The function supports the following parameters:
46+
47+
- **options**: options.
48+
- **requestListener**: callback to invoke upon receiving an HTTP request (_optional_).
49+
50+
To bind a request callback to a server, provide a `requestListener`.
51+
52+
```javascript
53+
function requestListener( request, response ) {
54+
console.log( request.url );
55+
response.end( 'OK' );
56+
}
57+
58+
var opts = {
59+
'cert': readFileSync( resolve( __dirname, 'examples', 'localhost-cert.pem' ) ),
60+
'key': readFileSync( resolve( __dirname, 'examples', 'localhost-privkey.pem' ) )
61+
};
62+
var http2Server = http2ServerFactory( opts, requestListener );
63+
```
64+
65+
In addition to the options supported by [`http2.createSecureServer`][nodejs-http2-create-secure-server], the function accepts the following options:
66+
67+
- **port**: server port. Default: `0` (i.e., randomly assigned).
68+
- **maxport**: max server port when port hunting. Default: `maxport=port`.
69+
- **hostname**: server hostname.
70+
- **address**: server address. Default: `127.0.0.1`.
71+
72+
To specify server options, provide an options object.
73+
74+
```javascript
75+
var opts = {
76+
'port': 7331,
77+
'address': '0.0.0.0',
78+
'cert': readFileSync( resolve( __dirname, 'examples', 'localhost-cert.pem' ) ),
79+
'key': readFileSync( resolve( __dirname, 'examples', 'localhost-privkey.pem' ) )
80+
};
81+
82+
var http2Server = http2ServerFactory( opts );
83+
```
84+
85+
To specify a range of permissible ports, set the `maxport` option.
86+
87+
```javascript
88+
var opts = {
89+
'maxport': 9999,
90+
'cert': readFileSync( resolve( __dirname, 'examples', 'localhost-cert.pem' ) ),
91+
'key': readFileSync( resolve( __dirname, 'examples', 'localhost-privkey.pem' ) )
92+
};
93+
94+
var http2Server = http2ServerFactory( opts );
95+
```
96+
97+
When provided a `maxport` option, a created server will search for the first available `port` on which to listen, starting from `port`.
98+
99+
#### http2Server( done )
100+
101+
Creates an [HTTP/2][nodejs-http2] server.
102+
103+
```javascript
104+
function done( error, server ) {
105+
if ( error ) {
106+
throw error;
107+
}
108+
console.log( 'Success!' );
109+
server.close();
110+
}
111+
112+
var opts = {
113+
'cert': readFileSync( resolve( __dirname, 'examples', 'localhost-cert.pem' ) ),
114+
'key': readFileSync( resolve( __dirname, 'examples', 'localhost-privkey.pem' ) )
115+
};
116+
var http2Server = http2ServerFactory( opts );
117+
118+
http2Server( done );
119+
```
120+
121+
The function supports the following parameters:
122+
123+
- **done**: callback to invoke once a server is listening and ready to handle requests.
124+
125+
</section>
126+
127+
<!-- /.usage -->
128+
129+
<section class="notes">
130+
131+
## Notes
132+
133+
- Which server options are supported depends on the Node.js version.
134+
- Port hunting can be useful in a microservice deployment. When a `port` is randomly assigned (`options.port=0`), if a server fails and is restarted, the server is unlikely to bind to its previous `port`. By allowing a constrained search, assuming no lower `ports` within a specified range have freed up in the meantime, the likelihood of listening on the same `port` is increased. A server can typically restart and bind to the same `port` faster than binding to a new `port` and re-registering with a microservice registry, thus minimizing possible service interruption and downtime.
135+
136+
</section>
137+
138+
<!-- /.notes -->
139+
140+
<section class="examples">
141+
142+
## Examples
143+
144+
<!-- eslint-disable node/no-process-exit, node/no-unsupported-features/node-builtins -->
145+
146+
<!-- eslint no-undef: "error" -->
147+
148+
```javascript
149+
var proc = require( 'process' );
150+
var http2 = require( 'http2' );
151+
var resolve = require( 'path' ).resolve;
152+
var readFileSync = require( '@stdlib/fs/read-file' ).sync;
153+
var http2ServerFactory = require( '@stdlib/net/http2-secure-server' );
154+
155+
function done( error ) {
156+
var client;
157+
var req;
158+
if ( error ) {
159+
throw error;
160+
}
161+
client = http2.connect( 'https://localhost:7331', {
162+
'ca': readFileSync( resolve( __dirname, 'examples', 'localhost-cert.pem' ) )
163+
});
164+
req = client.request({
165+
':path': '/beep/boop'
166+
});
167+
req.on( 'response', onResponse );
168+
req.end();
169+
170+
function onResponse() {
171+
console.log( 'Success!' );
172+
client.close();
173+
proc.exit( 0 );
174+
}
175+
}
176+
177+
function onRequest( request, response ) {
178+
console.log( request.url );
179+
response.end( 'OK' );
180+
}
181+
182+
// Specify server options...
183+
var opts = {
184+
'port': 7331,
185+
'maxport': 9999,
186+
'hostname': 'localhost',
187+
'allowHTTP1': true,
188+
'cert': readFileSync( resolve( __dirname, 'examples', 'localhost-cert.pem' ) ),
189+
'key': readFileSync( resolve( __dirname, 'examples', 'localhost-privkey.pem' ) )
190+
};
191+
192+
// Create a function for creating an HTTP/2 server...
193+
var http2Server = http2ServerFactory( opts, onRequest );
194+
195+
// Create a server:
196+
http2Server( done );
197+
```
198+
199+
</section>
200+
201+
<!-- /.examples -->
202+
203+
<!-- Section for related `stdlib` packages. Do not manually edit this section, as it is automatically populated. -->
204+
205+
<section class="related">
206+
207+
</section>
208+
209+
<!-- /.related -->
210+
211+
<!-- Section for all links. Make sure to keep an empty line after the `section` element and another before the `/section` close. -->
212+
213+
<section class="links">
214+
215+
[nodejs-http2]: https://nodejs.org/api/http2.html
216+
217+
[nodejs-http2-create-secure-server]: https://nodejs.org/api/http2.html#http2createsecureserveroptions-onrequesthandler
218+
219+
</section>
220+
221+
<!-- /.links -->

‎lib/node_modules/@stdlib/net/http2-secure-server/docs/repl.txt

Lines changed: 79 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,79 @@
1+
2+
{{alias}}( options, [requestListener] )
3+
Returns a function to create an HTTP/2 server.
4+
5+
In addition to options documented below, the function supports any options
6+
supported by `http2.createSecureServer`. Which server options are supported
7+
depends on the Node.js version.
8+
9+
Either the `pfx` option or the `key`/`cert` options must be provided.
10+
11+
Parameters
12+
----------
13+
options: Object
14+
Options.
15+
16+
options.pfx: string|Buffer|Array<string|Buffer|Object> (optional)
17+
PFX or PKCS12 encode private key and certificate chain.
18+
19+
options.cert: string|Buffer|Array<string|Buffer> (optional)
20+
Cert chains in PEM format.
21+
22+
options.key: string|Buffer|Array<string|Buffer|Object> (optional)
23+
Private keys in PEM format.
24+
25+
options.port: integer (optional)
26+
Server port. Default: `0` (i.e., randomly assigned).
27+
28+
options.maxport: integer (optional)
29+
Max server port when port hunting. Default: `maxport = port`.
30+
31+
options.hostname: string (optional)
32+
Server hostname.
33+
34+
options.address: string (optional)
35+
Server address. Default: `'127.0.0.1'`.
36+
37+
requestListener: Function (optional)
38+
Request callback.
39+
40+
Returns
41+
-------
42+
http2Server: Function
43+
Function to create an HTTP/2 server.
44+
45+
Examples
46+
--------
47+
> function onRequest( request, response ) {
48+
... console.log( request.url );
49+
... response.end( 'OK' );
50+
... };
51+
> var opts = { 'port': 7331, 'cert': '...', 'key': '...' };
52+
> var boot = {{alias}}( opts, onRequest )
53+
<Function>
54+
55+
56+
boot( done )
57+
Creates an HTTP/2 server.
58+
59+
Parameters
60+
----------
61+
done: Function
62+
Callback to invoke after creating a server.
63+
64+
Examples
65+
--------
66+
> function done( error, server ) {
67+
... if ( error ) {
68+
... throw error;
69+
... }
70+
... console.log( 'Success!' );
71+
... server.close();
72+
... };
73+
> var opts = { 'cert': '...', 'key': '...' };
74+
> var boot = {{alias}}();
75+
> boot( done );
76+
77+
See Also
78+
--------
79+

0 commit comments

Comments
 (0)