mirc http client mockup

mSL based HTTP client aimed at simplifying HTTP requests while being
more robust than $urlget

Planned supported features:
    Cookie store
    Convienanace logic for making URL-Encoded and Multipart requests
        Decides when to use one or the other without user defined logic
        Formats the request appropriately
        Sets default headers such as Content-Length
    Convienanace alias of deducing mime-types
    Streaming request data from file
    Base client can be extended via /HTTP Takeover
    Response Compression: gzip, deflate
    Chunked response data
    Following redirects with user-specified limits
    Streaming response body to file



Note about redirects:
    This script defaults to using HTTP Keep-Alive for purposes of following
    redirects to the same site without having to establish a new connection.

    Though this is an attempt to optimize the script its not always guaranteed to
    work
    - The server may not support Keep Alive
    - A redirect may not point to the same domain
    In such cases a new connection will be used

    If you perfer a new connection be used with each redirect use
    /HTTP Header @name Connection close



/HTTP Open -cimNrNsw @name [@method] @url [@file]
    Creates an HTTP Client instance

    -c
        Indicates the request should use a cookie store when following redirects


    -i
        Note: AFAIK this is not currently possible as mIRC does not allow ssl certificate errors to be ignored without user input
        Indicates SSL certificate errors should be ignored

    -m
        Indicates @method has been specified

    -rN
        Indicates the max number of redirects to follow
        If omitted all redirects will be followed
        if N is 0, no redirects will be followed

    -RN
        Indicates the max number of circular redirects to follow
        If omitted circular redirects will be followed once
        If N is 0, no circular redirects will be followed

    -s
        Secret; do not use until documented

    -w
        Wait for /HTTP Fetch to be called to begin the request

    @name
        Name used to reference the HTTP Client instance
        Must not be in use by another existing HTTP Client instance
        Must not contain spaces, a dash(-) or a colon(:)

    @method - Switch dependent(-m)
        The HTTP request method to use
        Defaults to GET

    @url
        The URL to request

    @file - Optional
        The output file to stream the response body in to
        If the server uses compression, the file will not be usable until the response has completed



/HTTP Header -a @name @header @value
    Stores a request header to be sent with the request

    -a
        Indicates the header should be appended to the list
        If not specified and the same header is set multiple times, the previous value will be overwrote

    @name
        HTTP client instance

    @header
        Request header name to set

    @value
        Value for the header

    Default Headers:
        Host: <host>
        Accept-Encoding: gzip, deflate
        Cache-Control: no-cache
        User-Agent: mIRCHttpClient/1.0 (Win NT $os)

    If /HTTP Form is used the following additional headers are set:
        Content-Type
        Content-Length



/HTTP Cookie -bo @name @cookie @value [@options]
    Stores an initial cookie value
    Only applicable if the instance was created with the -c switch

    -b
        Indicates @value is a bvar

    -o
        Forces the cookie to be overwrote even if the expiration is before the currently stored one
        This switch is unneeded if an expiration for the cookie is not set in @options

    @name
        HTTP client instance

    @cookie
        The cookie name to store

    @value
        The value of the cookie

    @options - Optional
        Options related to the cookie
        Format of these options is a semi-colon(;) delimited list of key=value pairs
            Example: SameSite=Strict; Expires=Wed, 21 Oct 2015 07:28:00 GMT; HttpOnly; Secure; Path=/

        If not specified the cookie will default to using:
            Domain=<url_domain>
            Path=/
            SameSite=None



/HTTP Form -bfFh @name [@mime] @key @value
    Prepares a new segment of data to send
    The script will decide to use either URL-encoded query string or Multipart when building the data to send
    The script will automatically set the Content-Type and Content-Length headers; attempts to override them will be ignored

    -b
        Indicates @value is a bvar that should be URL encoded

    -B
        Indicates @value is a bvar that should be treated as a file

    -f
        Indicates @value is a file to be read into memory

    -F
        Indicates @value is a file that should be streamed from the harddisk

    -h
        Indicates a header for the last segment added is to be set
        Forces multipart over url-encoding

    @name
        HTTP client instance

    @mime - Switch dependent(-B, -f, -F)
        Indicates the mime type for the file being added

    @key
        The name of the form-value or header

    @value
        The value for the key



/HTTP Fetch -bdfF @name [@source]
    Initiates the HTTP request

    -b
        Indicates @source is a bvar

    -d
        Indicates the HTTP Data has been prepared using /HTTP Form
        @source will be ignored

    -f
        Indicates @source is a file to send
        The entire file will be read into memory for sending

    -F
        Indicates @source is a file to send
        The file will be streamed from disk

    @name
        HTTP client instance

    @source - Switch dependent(not -d)
        The data source to send



/HTTP Takeover @name @sockname
    Allows for another script to take over the connection
    Once called, the underlying socket is renamed and all other related resources for the instance are freed
    Only applicable from within the HTTPHead event

    @name
        HTTP client instance name

    @sockname
        The new sockname to use for the underlying socket

    Note:
        This command is meant for supplemental scripts to add functionality to the base HTTP client
        An example of this would be a websocket script



/HTTP Close -w @name
    Closes all matching HTTP client instance

    -w
        Indicates @name is a wildcard pattern

    @name
        The name or wildcard pattern to use to close HTTP client instances



/HTTP Shutdown
    Closes all HTTP client instances and frees all related resources



$HTTP()
    TODO - Returns various information about the request/response



$HTTPMime(@ext|file)
    Returns the mime type for the specified file extension

    @ext
        The extension, file path or file name to get the mime-type of
        The last "." delimited token will be used as the ext to look up



Events are emitted via signals, formatted as @event-@name
    @event : The event that triggered

    @name : The name of the HTTP client instance that triggered the event

    $1 : Will be the name of the HTTP client instance for all events

    $HTTPSockErr
        Will be filled if any socket errors occur

    $HTTPProtoErr
        Will be filled if any HTTP protocol errors occur

    $HTTPSysErr
        Will be filled if any system errors occur


    HTTPOpen
        Emitted when the socket connection has been established or fails to connect

    HTTPSend
        Emitted each time a portion of the request data is successfully sent

    HTTPSent
        Emitted after the request has been sent and a response is pending

    HTTPReceive
        Emitted each time a portion of the response is received

    HTTPHead
        Emitted once the HTTP response head has been received
        $2 is the status code
        $3- is the status text

    HTTPRedirect
        Emitted when an http redirect is about to be followed
        Redirects are followed after the body for the current request has been received

    HTTPDone
        Emitted once the request has finished
*/