infinity.http2¶

Povides HTTP/2 server and session functionality.

Module: infinity.http2

server¶

Allows for your instance of INFINITY.JS to act as an HTTP/2-server. Lets you receive requests and send data. Can register handlers for static files, REST requests, the JSON-RPC protocol and API calls (require the simultaneous usage of registerHandler() and registerService()). JSON-RPC and REST handlers can be combined in one service.

Example:

infinity.loadModule('infinity.http2');
let myServer = new infinity.http2.server(true, false, false, false, false, false, 443, 1024, 64, 104857600, 5.0);

myServer.registerHandler(infinity.http2.server.handler.status, '/status');
myServer.registerHandler(infinity.http2.server.handler.staticFile, '/', '../web/', 60.0, 256144);
myServer.registerHandler(infinity.http2.server.handler.jsonRpc, '/v1/jsonrpc');
myServer.registerService('system', 'system', 'system.js', [
  {name: 'shutdown'},
  {name: 'getVersion', result: 'string'}
]);

myServer.start();

while (!infinity.terminated) {
  infinity.event.processQueue();
  infinity.sleep(25);
}

myServer.stop();

system.ts:

namespace system {

    export function shutdown(): void {
      infinity.terminate();
    }

    export function getVersion(): string {
      return '1.0.0 build 1234';
    }
  }

Folder structure:

+ example
  + ts
    - main.ts
    - system.ts

Example POST-request against /v1/jsonrpc:

{"jsonrpc": "2.0", "method": "system.getVersion"}

Properties

onBinary¶

Type: string

The filename (relative to the main script) of the script that will handle binary requests. Within that script, you can access the infinity.http2.session object, which will contain (among others) the following properties:

• message: the message data that has been sent by the client
• fileName: the absolute path to the file containing the binary data sent by the client

onMessage¶

Type: string

Script filename (relative to the main script) that will handle message requests. Within that script, you can access the infinity.http2.session object, which will contain (among others) the following property:

• message: the message data that has been sent by the client

Methods

constructor()¶

Lets you create an INFINITY.JS HTTP/2 server object instance. Takes the most important parameters for the server to function.

Signature:

constructor( ssl?: boolean, verifyCertificate?: boolean, allowCrossOrigin?: boolean, compress?: boolean, accessLog?: boolean, iocp?: boolean, port?: number, maxConnections?: number, poolSize?: number, maxContentLength?: number, slowRequestTime?: number, protocol?: infinity.http2.server.protocol, maxRateCounter?: number )

Parameters:

• ssl: boolean, optional

  For using SSL connections.

• verifyCertificate: boolean, optional

  Whether to verify the SSL-Certificate.

• allowCrossOrigin: boolean, optional

  For allowing cross-origin-requests.

• compress: boolean, optional

  For turning compression on or off.

• accessLog: boolean, optional

  For turning on or off the logging of all access events.

• iocp: boolean, optional

  Specifies the usage of the input/output completion port.

• port: number, optional

  Specifies the port to listen on.

• maxConnections: number, optional

  Specifies the number of simultaneous connections.

• poolSize: number, optional

  Specifies the number of worker threads to be held ready.

• maxContentLength: number, optional

  Specifies the maximum number of bytes (content-length header) that the server accepts in http requests.

• slowRequestTime: number, optional

  Specifies how many seconds the processing of a request is allowed to take without being logged as "slow". Accepts decimals with . as well.

• protocol: infinity.http2.server.protocol, optional

  Specifies the encryption protocol to be used.

• maxRateCounter: number, optional

  The maximum number of requests that a client can make in a specific time frame for rate limiting.

Example:

infinity.loadModule('infinity.http2');
let myServer = new infinity.http2.server(true, false, false, false, false, false, 443, 1024, 64, 104857600, 5.0);

broadcast(data)¶

Sends data to all clients that have subscribed to a specific channel. The channel name can be chosen arbitrarily and the data will be sent to all clients that are subscribed to the channel by this name.

Signature:

broadcast( data: any, channel?: string, exclude?: string, include?: string ): void

Parameters:

• data: any

  Data to be sent (can be any object, number, string, etc.).

• channel: string, optional

  Channel name.

• exclude: string, optional

  Comma-separated list of client ids to exclude from the broadcast.

• include: string, optional

  Comma-separated list of client ids to include from the broadcast (in addition to those subscribed to the given channel).

Example:

myServer.broadcast(data);

broadcast(stream)¶

Sends data from a stream to all clients that have subscribed a specific channel. The channel name can be chosen arbitrarily and the data will be sent to all clients that are subscribed to the channel by this name.

Signature:

broadcast( stream: infinity.stream, channel?: string, exclude?: string, include?: string ): void

Parameters:

• stream: infinity.stream

  A stream from which to read data and send it to the clients.

• channel: string, optional

  Channel name.

• exclude: string, optional

  Comma-separated list of client ids to exclude from the broadcast.

• include: string, optional

  Comma-separated list of client ids to include from the broadcast (in addition to those subscribed to the given channel).

Example:

myServer.broadcast(stream);

broadcast(message)¶

Sends a string message to all clients that have subscribed to a specific channel. The channel name can be chosen arbitrarily and the data will be sent to all clients that are subscribed to the channel by this name.

Signature:

broadcast( message: string, channel?: string, exclude?: string, include?: string ): void

Parameters:

• message: string

  Message to send to the clients.

• channel: string, optional

  Channel name.

• exclude: string, optional

  Comma-separated list of client ids to exclude from the broadcast.

• include: string, optional

  Comma-separated list of client ids to include from the broadcast (in addition to those subscribed to the given channel).

Example:

myServer.broadcast(message);

registerHandler()¶

Registers a handler for client requests, invoking additional resources, including caching functionality.

Signature:

registerHandler( handler: infinity.http2.server.handler, path: string, alias?: string, expire?: number, maxCacheSize?: number, headers?: infinity.http2.headerArray ): void

Parameters:

• handler: infinity.http2.server.handler

  The type of handler to register.

• path: string

  The request path for the client.

• alias: string

  The path to a local folder or file with contents or defined routines to be served corresponding to the client request.

• expire: number, optional

  The cache expiration time in seconds. After the specified period the file will have to be examined for changes at the next call.

• maxCacheSize: number, optional

  The cache threshold in bytes. Files with sizes exceeding the specified number will not be cached.

• headers: infinity.http2.headerArray, optional

  The headers to be sent with the response.

• limit: number, optional

  The maximum number of requests that can be made in the defined period. Used for rate limiting.

• period: number, optional

  The rate limit time period in seconds.

• delay: number, optional

  The "cool down" period in seconds that a client must wait after hitting the rate limit before making new requests.

Example:

myServer.registerHandler(infinity.http2.server.handler.status, '/status');
myServer.registerHandler(infinity.http2.server.handler.staticFile, '/', '../web/');
myServer.registerHandler(infinity.http2.server.handler.staticFile, '/', '../web/', 60.0, 256144);

registerService()¶

Registers a service, allowing requests for execution of custom defined methods.

Signature:

registerService( name: string, namespace: string, path: string, methods: infinity.http2.methodArray ): void

Parameters:

• name: string

  The name of the service.

• namespace: string

  The namespace for the service.

• path: string

  The path to the file with the custom defined methods.

• methods: infinity.http2.methodArray

  An array of the method names for the service. Parameters for return types, REST methods and HTTP environment can also be specified.

Example:

myServer.registerHandler(infinity.http2.server.handler.jsonRpc, '/v1/jsonrpc');
myServer.registerService('system', 'system', 'system.js', [
  {name: 'shutdown'},
  {name: 'getVersion', result: 'string'}
]);

system.ts:

namespace system {

  export function shutdown(): void {

    infinity.terminate();

  }

  export function getVersion(): string {

    return '1.0.0 build 1234';

  }

}

Folder structure:

+ example
  + ts
    - main.ts
    - system.ts

POST-request against /v1/jsonrpc:

{"jsonrpc": "2.0", "method": "system.getVersion"}

setCertificate()¶

Sets the SSL certificate for the current server instance using the corresponding files provided in the function parameters.

Signature:

setCertificate(certFile: string, keyFile: string, rootCertFile?: string, verify?: boolean): void;

Parameters:

• certFile: string

  The path to the certificate file to be used.

• keyFile: string

  The path to the the key file to be used.

• rootCertFile: string, optional

  The path to the the root certificate file to be used.

• verify: boolean, optional

  Whether to verify the validity of the certificate.

Example:

myServer.setCertificate('certFile.crt', 'keyFile.key', 'rootCertFile.crt', true);

start()¶

Starts the server instance with previously specified parameters.

Signature:

start(): void

Example:

myServer.start();

stop()¶

Shuts down the server instance.

Signature:

stop(): void

Example:

myServer.stop();

unregisterHandler()¶

Unregisters the specified registered handler, making the previously defined functionality unavailable.

Signature:

unregisterHandler( path: string ): void

Parameters:

• path: string

  The request path for the client, which the handler has previously been registered for.

Example:

myServer.unregisterHandler('/');

unregisterService()¶

Unregisters the specified registered service, making the previously defined functionality unavailable.

Signature:

unregisterService( name: string ): void

Parameters:

• name: string

  The name of the previously registered service.

Example:

myServer.unregisterService('system');

write()¶

Sends data to a specific client connection.

Signature:

write( id: string, data: any ): boolean

Parameters:

• id: string

  Session id of the client connection.

• data: any

  Data to be sent (can be any object, number, string, etc.).

Return type: boolean

Example:

myServer.write(id, data);

writeStream()¶

Sends data from a stream to a specific client connection.

Signature:

writeStream( id: string, stream: infinity.stream ): boolean

Parameters:

• id: string

  Session id of the client connection.

• stream: infinity.stream

  A stream from which to read data and send it to the client.

Return type: boolean

Example:

myServer.writeStream(id, stream);

writeString()¶

Sends a string message to a specific client connection.

Signature:

writeString( id: string, message: string ): boolean

Parameters:

• id: string

  Session id of the client connection.

• message: string

  Message to send to the client.

Return type: boolean

Example:

myServer.writeString(id, message);

infinity.http2.request¶

Read-only properties containing information from the incoming HTTP/2 request.

contentBoundary¶

Type: string

Gets the boundary delimiter string.

contentDisposition¶

Type: string

Gets the content-disposition HTTP/2-header value.

contentEncoding¶

Type: infinity.encoding

Gets the content-encoding HTTP-header value.

contentFilename¶

Type: string

Gets the filename parameter of the Content-Disposition HTTP-header value.

contentLength¶

Type: number

Gets the content-length HTTP-header value.

contentText¶

Type: string

Gets the contents of the body of the request.

contentTransferEncoding¶

Type: string

Gets the transfer-encoding HTTP-header value.

contentType¶

Type: string

Gets or sets the content-type HTTP-header value.

cookies¶

Type: infinity.http2.cookiesArray

Gets or sets cookie data.

destination¶

Type: string

Gets the destination of the HTTP request

files¶

Type: infinity.http2.filesArray

Gets information about the files sent with the HTTP request.

gatewayInterface¶

Type: string

Gets the name and version of the gateway interface (only during SCGI operations).

get¶

Type: infinity.http2.valuesArray

Gets the information out of the GET-part of the HTTP request.

httpAccept¶

Type: string

Gets the accept HTTP-header value.

httpAcceptCharSet¶

Type: string

Gets the accept-charset HTTP-header value.

httpAcceptEncoding¶

Type: string

Gets the accept-encoding HTTP-header value.

httpAcceptLanguage¶

Type: string

Gets the accept-language HTTP-header value.

httpAuthorization¶

Type: string

Gets the authorization HTTP-header value.

httpConnection¶

Type: string

Gets the connection HTTP-header value.

httpHost¶

Type: string

Gets the Host value of the HTTP request.

httpIfMatch¶

Type: string

Gets the if-match HTTP-header value.

httpIfModifiedSince¶

Type: number

Gets the if-modified-since HTTP-header value.

httpIfNonMatch¶

Type: string

Gets the if-none-match HTTP-header value.

httpReferer¶

Type: string

Gets the referer HTTP-header value.

httpUserAgent¶

Type: string

Gets the user-agent HTTP-header value.

method¶

Type: string

Gets the HTTP request method.

pathInfo¶

Type: string

Reports the value of the path information (if any) of the URL specified in the HTTP request message.

pathTranslated¶

Type: string

Represents a translation of the PathInfo property to a fully qualified path on the Web server.

post¶

Type: infinity.http2.valuesArray

Gets the information out of the POST-part of the HTTP request.

range¶

Type: infinity.http2.rangeArray

Gets the range HTTP-header value.

remoteAddr¶

Type: string

Gets the IP address of the remote machine making this request.

remoteHost¶

Type: string

Gets the hostname of the remote machine making this request (only during SCGI operations).

remoteIdent¶

Type: string

Gets the remote user name retrieved from the server (only during SCGI operations).

remotePort¶

Type: number

Gets the port over which the remote machine communicates.

remoteUser¶

Type: string

Gets the authenticated remote user name (only during SCGI operations).

scgi¶

Type: boolean

Indicates whether scgi is being used.

scheme¶

Type: string

Gets the :scheme: HTTP-header value.

scriptFilename¶

Type: string

Gets the filename of the script being executed (only during SCGI operations).

scriptName¶

Type: string

Gets the name of the script being executed.

serverAddr¶

Type: string

Gets the local server address.

serverAdmin¶

Type: string

Gets or sets server administrator information (only during SCGI operations).

serverName¶

Type: string

Gets the domain name of the local server.

serverPort¶

Type: number

Gets the port over which the local server communicates.

serverProtocol¶

Type: string

Gets the protocol over which the local server communicates.

serverSignature¶

Type: string

Gets the signature of the local server (only during SCGI operations).

serverSoftware¶

Type: string

Gets the name representing the local server software.

uri¶

Type: string

Gets the URI of the HTTP request.

infinity.http2.response¶

The properties of the outgoing response from the INFINITY.JS HTTP/2 server. Can be read and set. Undefined, unless used inside the file specified in the "alias" parameter of registerHandler().

acceptRanges¶

Type: string

Gets or sets the accept-ranges HTTP-header value.

cacheControl¶

Type: string

Gets or sets the cache-control HTTP-header value.

code¶

Type: number

Gets or sets the HTTP response code.

contentEncoding¶

Type: string

Gets or sets the content-encoding HTTP-header value.

contentFilename¶

Type: string

Gets or sets the filename parameter of the content-disposition HTTP-header value.

contentLanguage¶

Type: string

Gets or sets the content-language HTTP-header value.

contentRange¶

Type: string

Gets or sets the content-range HTTP-header value.

contentStream¶

Type: infinity.stream

Gets or sets the contents of the body of the response using a infinity.stream.

contentText¶

Type: string

Gets or sets the contents of the body of the response.

contentType¶

Type: string

Gets or sets the content-type HTTP-header value.

cookies¶

Type: infinity.http2.cookiesArray

Gets or sets cookie data.

date¶

Type: number

Gets or sets the date HTTP-header value.

encoding¶

Type: infinity.encoding

Gets or sets the encoding of the HTTP response.

etag¶

Type: string

Gets or sets the etag HTTP-header value.

expires¶

Type: number

Gets or sets the expires HTTP-header value.

headers¶

Type: infinity.http2.valuesArray

Gets or sets additional headers inside a valuesArray.

ignoreSlowRequest¶

Type: boolean

Gets or sets the setting for not logging the request if it takes longer than the slowRequestTime setting, set during the server instance creation.

lastModified¶

Type: number

Gets or sets the last-modified HTTP-header value.

location¶

Type: string

Gets or sets the location HTTP-header value.

pragma¶

Type: string

Gets or sets the pragma HTTP-header value.

proxyAuthenticate¶

Type: string

Gets or sets the proxy-authenticate HTTP-header value.

refresh¶

Type: string

Gets or sets the undocumented refresh HTTP-header value.

server¶

Type: string

Gets or sets the server HTTP-header value.

transferEncoding¶

Type: string

Gets or sets the transfer-encoding HTTP-header value.

wwwAuthenticate¶

Type: string

Gets or sets the WWW-Authenticate HTTP-header value.

infinity.http2.server¶

infinity.http2.server.handler¶

Values:

• custom: 0

  A custom handler to be defined in a file, specified in the third function parameter of registerHandler().

• staticFile: 1

  A handler for serving static file content. Prefers showing the index.html file.

• jsonRpc: 2

  A handler for requests according to the JSON-RPC protocol.

• rest: 3

  A handler for REST-requests.

• api: 4

  A handler for requests to an API.

• webDav: 5

  A handler for requests according to the WebDAV protocol (not implemented yet).

• cardDav: 6

  A handler for requests according to the CardDAV protocol (not implemented yet).

• calDav: 7

  A handler for requests according to the CalDAV protocol (not implemented yet).

• status: 8

  A handler for server-status requests, showing server and resource usage information.

Example:

infinity.loadModule('infinity.http2');
let handler = infinity.http2.server.handler.custom;

infinity.http2.server.protocol¶

Values:

• all: 0

  Allows the usage of all available protocols.

• tls1_0: 1

  Specifies the usage of TLS 1.0.

• tls1_1: 2

  Specifies the usage of TLS 1.1.

• tls1_2: 3

  Specifies the usage of TLS 1.2.

• tls1_3: 4

  Specifies the usage of TLS 1.3.

Example:

infinity.loadModule('infinity.http2');
let protocol = infinity.http2.server.protocol.tls1_2;

infinity.http2.session¶

The infinity.http2.session object will be available in the handler scripts run by the infinity.http2.server. The properties will be filled depending on the handler and some of the properties are used to provide results of the handler to be returned back to the client.

disconnect()¶

Disconnects the current connection.

Signature:

disconnect(): void

Example:

infinity.loadModule('infinity.http2');
infinity.http2.session.disconnect();

subscribe()¶

Subscribes this instance to a specific channel. The channel name can be chosen arbitrarily and the server can use the broadcast() methods to send data to all instances that are subscribed to a specific channel.

Signature:

subscribe( channel: string ): void

Parameters:

• channel: string

  Channel name.

Example:

infinity.loadModule('infinity.http2');
infinity.http2.session.subscribe(channel);

subscribed()¶

Checks whether this instance has been subscribed to a specific channel.

Signature:

subscribed( channel: string ): boolean

Parameters:

• channel: string

  Channel name.

Return type: boolean

Example:

infinity.loadModule('infinity.http2');
if ( infinity.http2.session.subscribed(channel) ) {}

unsubscribe()¶

Unsubscribes this instance from a specific channel.

Signature:

unsubscribe( channel: string ): void

Parameters:

• channel: string

  Channel name.

Example:

infinity.loadModule('infinity.http2');
infinity.http2.session.unsubscribe(channel);

write()¶

Sends data to a specific connection.

Signature:

write( data: any ): boolean

Parameters:

• data: any

  Data to be sent (can be any object, number, string, etc.).

Return type: boolean

Example:

infinity.loadModule('infinity.http2');
if ( infinity.http2.session.write(data) ) {
  //...
}

writeStream()¶

Sends data from a stream to a specific connection.

Signature:

writeStream( stream: infinity.stream ): boolean

Parameters:

• stream: infinity.stream

  A stream from which to read and send data.

Return type: boolean

Example:

infinity.loadModule('infinity.http2');
if ( infinity.http2.session.writeStream(stream) ) {
  //...
}

writeString()¶

Sends a string message to a specific connection.

Signature:

writeString( message: string ): boolean

Parameters:

• message: string

  Message to send.

Return type: boolean

Example:

infinity.loadModule('infinity.http2');
if ( infinity.http2.session.writeString(message) ) {
  //...
}

fileName¶

Type: string

In the onBinary request handler, this property will contain the absolute path to the file containing the binary data sent by the client.

id¶

Type: string

The session id. This will remain constant throughout a single session and will turn invalid on disconnect.

ip¶

Type: string

The IP address from which the client connected.

message¶

Type: string

In the onBinary and onMessage request handlers, this property will contain the data sent by the client.

port¶

Type: number

The port used by the connection with the client.

cookiesArray¶

Extends: Array<{name: string, value: string, expires: number, path: string, domain: string}>

An array containing objects with cookie data inside its properties.

Properties:¶

• name¶

  Type: string. The name of a cookie field.

• value¶

  Type: string. The value of a cookie field.

• expires¶

  Type: number. The expiration date for the cookie.

• path¶

  Type: string. The storage path for the cookie.

• domain¶

  Type: string. The domain the cookie is set from.

filesArray¶

Extends: Array<{controlName: string, fileName: string, tempFilename: string, size: number, contentType: string}>

An array containing objects with data inside its properties.

Properties:¶

• controlName¶

  Type: string. The name of the used HTML form control.

• fileName¶

  Type: string. The name of the file.

• tempFilename¶

  Type: string. The temporary filename, the file is available under. Is only set during the actual request.

• size¶

  Type: number. The size of the file.

• contentType¶

  Type: string. The MIME-Type of the file.

headerArray¶

Extends: Array<{name: string, value: string}>

An array containing objects with data inside its properties.

Properties:¶

• name¶

  Type: string. The field name.

• value¶

  Type: string. The field value.

methodArray¶

Extends: Array<{name: string, params?: Array<string>, result?: any, rest?: string, httpEnvironment?: boolean}>

An array containing objects with data inside its properties.

Properties:¶

• name¶

  Type: string. The name of the function.

• params¶

  Type: Array<string>, optional. The function parameters.

• result¶

  Type: any, optional. The return type of the function result.

• rest¶

  Type: string, optional. The implied REST method for the function call.

• httpEnvironment¶

  Type: boolean, optional. If set to true, the infinity.http2.request values will be provided.

rangeArray¶

Extends: Array<{firstOffset: number, lastOffset: number}>

An array containing objects with data inside its properties.

Properties:¶

• firstOffset¶

  Type: number. The start offset.

• lastOffset¶

  Type: number, optional. The end offset.

stringArray¶

Extends: Array<string>

An array of strings.

valuesArray¶

Extends: Array<{name: string, value: string}>

An array containing objects with data inside its properties.

Properties:¶

• name¶

  Type: string. The field name.

• value¶

  Type: string. The field value.