Loading...
Searching...
No Matches
HttpServer::AbstractHttpSocketHandlerInterface Class Reference

Abstract class for HTTP handlers for handling protocol switching. More...

Inheritance diagram for HttpServer::AbstractHttpSocketHandlerInterface:
[legend]

## Public Member Functions

code | setExternallyManaged (softstring lid, hash< auto > cx, Socket s)
| Returns a closure that can be used to confirm that the connection has been closed.
bool | start (softstring lid, hash< auto > cx, hash< auto > hdr, Socket s)
| called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established
| stop ()
| called from the HTTP server when the socket should be closed due to an external request
| stop (softstring lid)
| called from the HTTP server when the socket should be closed due to an HTTP listener being stopped

## Protected Member Functions

| handlerStopped (softstring lid)
| Called when the handler stops.
Mutex | m ()
| listener reference hash mutex
abstract bool | startImpl (softstring lid, hash< auto > cx, hash< auto > hdr, Socket s)
| called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established
| stopImpl ()
| called from the HTTP server when the socket should be closed due to an external request
| stopImpl (string lid)
| called from the HTTP server when the socket should be closed because the listener is stopping

## Protected Attributes

hash< string, int > | lh
| hash of listener references; this is to stop all connections associated with a particular listener
hash< string, bool > | lsh
| hash of listener stop flags
bool | stop = False
| stop listener flag

## Detailed Description

Abstract class for HTTP handlers for handling protocol switching.

To accept a new dedicated socket connection, make sure the return value of the `handleRequest()` method returns code `101` (ie `Switching Protocols`); after which this class's start() and then startImpl() methods are called.

To accept a dedicated socket connection, `handleRequest()` must return a hash (ideally an HttpServer::HttpResponseInfo hash) with the following keys:

- `"code"`: assign to 101 (ie `"Switching Protocols"`); if this is returned, then the start() method will be called with the Socket object for the new connection
- `"hdr"`: (optional) set this key to a hash of extra header information to be returned with the response
  or, to handle the request without a dedicated connection, return a hash with the following keys:
- `"code"`: the HTTP return code (see HttpServer::HttpCodes)
- `"body"`: the message body to return in the response
- `"close"`: (optional) set this key to True if the connection should be unconditionally closed when the handler returns
- `"hdr"`: (optional) set this key to a hash of extra header information to be returned with the response

## Member Function Documentation

## start()

bool HttpServer::AbstractHttpSocketHandlerInterface::start | ( | softstring | lid,
|  | hash< auto > | cx,
|  | hash< auto > | hdr,
|  | Socket | s )

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() method is called

Parameters

  lid | the listener ID

  cx

  call context hash; this hash will have the following keys:
  - `header-info`: a hash of information about the request header with the following keys:
    - `accept-charset`: this key will be set to an appropriate value from any `"Accept-Charset"` header; if any of `"*"`, `"utf8"`, or `"utf-8"` are present, then this will be set to `"utf8"`, otherwise it will be set to the first requested character encoding in the list
    - `accept-encoding`: a hash where keys are values from any `"Accept-Encoding"` header and the values are True
    - `body-content-type`: this is the `"Content-Type"` header without any charset declaration
    - `charset:` if there is a charset declaration in the `"Content-Type"` header, the value is returned in this key
    - `client-cert`: if the server is configured to capture remote client certificates, and the client supplied a certificate, this key will be populated with the SSLCertificate for the client
    - `close:` set to True if the connection should be closed after responding, False if not (as derived from the request header)
    - `headers-raw`: a hash of raw request headers without any case conversions or other processing
    - `request-uri`: gives the request URI in an HTTP request
  - `socket:` the bind address used to bind the listener (`"socket-info"` provides more detailed information)
  - `socket-info`: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo())
  - `peer-info`: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo())
  - `url:` a hash of broken-down URL information (as returned from Qore::parse_url())
  - `id:` the unique HTTP connection ID
  - `ssl:` True if the request was encrypted with HTTPS, False if not
  - `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo())
  - `user:` the current RBAC username (if any)
  - `root_path:` the root URL path matched if the request was matched by a URL prefix

  hdr | a hash of headers in the request
  s | the Socket object for the dedicated connection

Returns
  True if externally managed

## startImpl()

abstract bool HttpServer::AbstractHttpSocketHandlerInterface::startImpl | ( | softstring | lid,
|  | hash< auto > | cx,
|  | hash< auto > | hdr,
|  | Socket | s )

protected

called from the HTTP server after the handleRequest() method indicates that a dedicated connection should be established

This method should not return until the connection is closed or the stop() (and therefore stopImpl()) method is called

Parameters

  lid | the listener ID

  cx

  call context hash; this hash will have the following keys:
  - `socket:` the bind address used to bind the listener (`"socket-info"` provides more detailed information)
  - `socket-info`: a hash of socket information for the listening socket (as returned by Qore::Socket::getSocketInfo())
  - `peer-info`: a hash of socket information for the remote socket (as returned by Qore::Socket::getPeerInfo())
  - `url:` a hash of broken-down URL information (as returned from Qore::parse_url())
  - `id:` the unique HTTP connection ID
  - `ssl:` True if the request was encrypted with HTTPS, False if not
  - `listener-id`: the HTTP server listener ID (see HttpServer::getListenerInfo())
  - `user:` the current RBAC username (if any)
  - `root_path:` the root URL path matched if the request was matched by a URL prefix

  hdr | a hash of headers in the request
  s | the Socket object for the dedicated connection

Returns
  True if externally managed

## stop() [1/2]

HttpServer::AbstractHttpSocketHandlerInterface::stop | ( |  | ) |

called from the HTTP server when the socket should be closed due to an external request

The start() method should return as soon as possible after this method is called

Child classes should implement the stopImpl() method which is called from this method to implement custom stop actions.

## stop() [2/2]

HttpServer::AbstractHttpSocketHandlerInterface::stop | ( | softstring | lid | ) |

called from the HTTP server when the socket should be closed due to an HTTP listener being stopped

The start() method for all connections on the particular listener should return as soon as possible after this method is called.

Child classes should implement the stopImpl(string) method which is called from this method to implement custom stop actions for particular listeners.

Parameters

  lid | the listener ID

## stopImpl() [1/2]

HttpServer::AbstractHttpSocketHandlerInterface::stopImpl | ( |  | ) |

protected

called from the HTTP server when the socket should be closed due to an external request

The start() method should return as soon as possible after this method is called

## stopImpl() [2/2]

HttpServer::AbstractHttpSocketHandlerInterface::stopImpl | ( | string | lid | ) |

protected

called from the HTTP server when the socket should be closed because the listener is stopping

The start() method for all connections handled by the given listener should return as soon as possible after this method is called

Parameters

  lid | the listener ID