class: Handlebars

[594:14] (extern: com.lehman.aussomserver.connectors.HandlebarsObj) extends: object

Handlebars support object.

Methods

• compileString (string Template)

  Compiles the provided template string.

  • @p Template is a string with the HTML template to compile.
  • @r This object.

• compile (string Template)

  Compiles the provided template with the provided template file name.

  • @p Template is a string with the file name of the template to compile.
  • @r This object.

• apply (JsonArgs)

  Applies the provided JSON arguments to the template and returns it as a string.

  • @p JsonArgs is a JSON string or an Aussom Object with the values to apply to the template.
  • @r A string with the template and values.

class: HttpFormData

[339:14] (extern: com.lehman.aussomserver.connectors.HttpFormData) extends: object

HttpFormData is the object returned from HttpReq.getStreamingFormData(). It carries a parsed multipart or url-encoded form and lets a handler access fields one at a time without ever pulling file contents into the JVM heap. The form holds two kinds of fields:

• Value fields. Plain text values like name=value or non-file parts of a multipart upload. Read with getValue(name).
• File fields. Multipart file parts. The parser spools them to a temp file on disk during parse. The handler reads them via getFile(name), which returns an HttpFormFile reader. Each file is read a chunk at a time so heap usage scales with the chunk size, not the upload size. Typical usage: fd = req.getStreamingFormData(); for (k in fd.keys()) { if (fd.isFile(k)) { ff = fd.getFile(k); while (!ff.eof()) { buf = ff.readChunk(65536); // hash, forward, verify, etc. } } else { val = fd.getValue(k); } } fd.close(); Lifetime: an HttpFormData is only valid while the request handler is running. The underlying temp files are deleted by the server when the exchange closes. close() should be called before the handler returns so any opened file streams are released cleanly.

Methods

• keys ()

  Lists every field name in insertion order, file and non-file alike. The handler typically iterates this list and dispatches on isFile(name).

  • @r A list of strings with the field names.

• fileFields ()

  Lists only the file field names in insertion order.

  • @r A list of strings with the file field names.

• valueFields ()

  Lists only the non-file (text value) field names in insertion order.

  • @r A list of strings with the value field names.

• hasField (string Name)

  Reports whether the form carries a field with the provided name (either a file or a value field).

  • @p Name is a string with the field name.
  • @r A bool, true if the field is present and false otherwise.

• isFile (string Name)

  Reports whether the named field is a file part. Returns false for missing fields and for plain text value fields.

  • @p Name is a string with the field name.
  • @r A bool, true if the field is a file part.

• getValue (string Name)

  Gets the text value of a non-file field. Returns an empty string when the field is missing or is actually a file part, so handlers may query without first checking isFile().

  • @p Name is a string with the field name.
  • @r A string with the field value, or "" if absent.

• getFile (string Name)

  Gets the HttpFormFile reader for a file field. Returns null when the field is missing or is not a file part. Repeated calls for the same field return the same reader, so a chunked read can continue across helper functions without the caller needing to thread the stream state through.

  • @p Name is a string with the field name.
  • @r An HttpFormFile, or null if the field is absent or is not a file part.

• close ()

  Closes every HttpFormFile reader that was handed out by getFile() and marks the form as closed. Idempotent. Should be called before the request handler returns so any opened file streams are released cleanly.

  • @r This object.

class: api

[731:21] static (extern: com.lehman.aussomserver.connectors.AussomApi) extends: object

Class that handles API operations.

Methods

• unpack (string Method, string JsonStr)

  The unpack function will attempt to take the provided JSON string and using the API definition will create the object graph it represents.

  • @p Method is the method enum value to unpack for.
  • @p JsonStr is a JSON formatted string with the request data to unpack.
  • @r The object or list of objects unpacked.

• unpackQueryParams (string Method, map QueryParams)

  The unpack function will attempt to take the provided query params map and create the defined object graph. You can define this with api--req-query-params value.

  • @p Method is the method enum value to unpack for.
  • @p QueryParams is a map with the request query params to unpack.
  • @r The object unpacked.

class: HttpReq

[24:14] (extern: com.lehman.aussomserver.connectors.HttpReqObj) extends: object

HttpReq object is the object provided by the handle(req) function. This object has all of the HTTP request information and also provides the API for sending the HTTP response.

Methods

• getReqPath ()

  Gets the request path.

  • @r A string with the request path.

• getReqMethod ()

  Gets the request method.

  • @r A string with the request method.

• getReqScheme ()

  Gets the HTTP request scheme.

  • @r A string with the request scheme.

• getReqURI ()

  Gets the request URI.

  • @r A string with the request URI.

• getReqURL ()

  Gets the request URL.

  • @r A string with the request URL.

• getReqContentLength ()

  Gets the request content length.

  • @r An integer with the request content length.

• getReqStartTime ()

  Gets the request start time.

  • @r A Date with the request start time.

• getReqHeaders ()

  Gets the request HTTP headers.

  • @r A map with the HTTP request headers.

• getReqCookies ()

  Gets the request cookies.

  • @r A list of objects that store the cookie data. Each object has domain, name, path, comment, value, expires, maxAge, and version keys.

• getHost ()

  Gets the request host.

  • @r A string with the request host.

• getAddress ()

  Gets the request IP address.

  • @r A string with the request IP address.

• getPort ()

  Gets the request port number.

  • @r An integer with the request port number.

• getSrcHost ()

  Gets the source/client host name.

  • @r A string with the source host name.

• getSrcAddress ()

  Gets the source/client IP address.

  • @r A string with the source IP address.

• getSrcPort ()

  Gets the source/client port number.

  • @r An integer with the source port number.

• getProtocol ()

  Gets the request protocol.

  • @r A string with the request protocol.

• getQueryString ()

  Gets the request query string.

  • @r A string with the request query string.

• getQueryParams ()

  Gets the request query parameters.

  • @r A map with the request query parameters.

• getPathParams ()

  Gets the request path parameters.

  • @r A list with the request path parameters.

• getReq ()

  Gets the request object. This function gathers all the request fields and returns them as a map. Possible keys in the returned map are path, method, charset, scheme, uri, url, contentLenght, startTime, headers, cookies, host, address, port, srcHost, srcAddress, srcPort, protocol, queryString, queryParams, pathParams, formData, and body. The formData and body keys will only be present if they were provided.

  • @r A map with the request object.

• getRespBytesSent ()

  Gets the response number of bytes sent.

  • @r An integer with the number of response bytes sent.

• getRespContentLength ()

  Gets the response content length sent.

  • @r An integer with the content length sent.

• getRespCharset ()

  Gets the response character set.

  • @r A string with the response character set.

• getRespHeaders ()

  Gets a map with the response headers.

  • @r A map with the response headers.

• getRespCookies ()

  Gets a list of response cookie objects.

  • @r A list of maps with the response cookie data.

• getResp ()

  Gets a response object with all fields.

  • @r A map with the response object fields.

• putHeader (string Key, value)

  Sets the provided header value for the connection.

  • @p Key is a string with the header name.
  • @p value is a string to set as the header value.
  • @r This object.

• setStatusCode (int Value)

  Sets the HTTP status code for the response.

  • @p Value is an integer to set for the HTTP status code.
  • @r This object.

• send (value)

  Sends the provided value as the response.

  • @p value is the value to send as the response.
  • @r This object.

• sendBytes (object value)

  Sends the provided bytes as the response.

  • @p value is a Buffer object with the bytes to send.
  • @r This object.

• sendChunk (object value)

  Sends a single chunk of bytes synchronously as part of a streamed response. This method may be called repeatedly to send a response in chunks, for example when reading a large file in a loop. Do not set a Content-Length header when using this method. With no Content-Length on an HTTP/1.1 response, the server will automatically use Transfer-Encoding: chunked and each call will flush a chunk to the client. The response is closed when the handler returns.

  • @p value is a Buffer object with the bytes for this chunk.
  • @r This object.

• addPathParam (string Name, string Value)

  Adds a path param.

  • @p Name is a string with name of the path param.
  • @p Value is a string with the value of the path param.
  • @r This object.

• addQueryParam (string Name, string Value)

  Adds a query param.

  • @p Name is a string with the query param name.
  • @p Value is a string with the query param value.
  • @r This object.

• getBody ()

  Gets the body of the request as a string.

  • @r A string with the request body.

• formSubmitted ()

  Gets the form submitted flag.

  • @r A boolean with true if a form was submitted and false if not. (Based on Content-Type)

• getFormData ()

  Gets the sent form data.

  • @r a map of the url-encoded or multipart form data.

• getStreamingFormData ()

  Gets the submitted form data as a streaming HttpFormData object. Use this instead of getFormData() when uploads may be large enough to risk exhausting the JVM heap. File parts are kept on disk in temp files by the parser and the returned object reads them a chunk at a time via HttpFormFile, so memory usage scales with chunk size rather than upload size. The returned object is only valid for the lifetime of the current request handler. Call close() on it before the handler returns so any opened file streams are released cleanly.

  • @r An HttpFormData object.

• setCookie (string name, string value, int expires = -1, bool secure = false, string path = "/")

  Sets a response cookie with the provided arguments.

  • @p name is a string with the cookie name.
  • @p value is a string with the cookie value.
  • @p expires is an integer with the number of milliseconds until the cookie expires.
  • @p secure is the flag that sets if the cookie is secure or not.
  • @p path is a string with the cookie path to set.
  • @r This object.

class: WsConn

[503:14] (extern: com.lehman.aussomserver.connectors.WsConnObj) extends: object

WsConn object is the object provided by a @Websocket-annotated handler function. One WsConn is created per inbound connection and lives until the channel closes. The handler typically registers onMessage / onClose / onError callbacks and may immediately send a greeting frame. Apps that want broadcast or room semantics keep their own peer list (e.g. this.peers @= ws). The WsConn object intentionally has no built-in subscriber list.

Methods

• send (string Text)

  Sends a text frame to the connected client. Non-blocking.

  • @p Text is a string with the text to send.
  • @r this object

• sendBytes (object Buf)

  Sends a binary frame to the connected client. Non-blocking.

  • @p Buf is a Buffer with the bytes to send.
  • @r this object

• onMessage (callback Cb)

  Registers (or replaces) the callback invoked on each incoming text frame. Cb is called with the frame text as its single argument.

  • @p Cb is a callback with signature (text).
  • @r this object

• onBinary (callback Cb)

  Registers (or replaces) the callback invoked on each incoming binary frame. Cb is called with a Buffer as its single argument.

  • @p Cb is a callback with signature (buffer).
  • @r this object

• onClose (callback Cb)

  Registers (or replaces) the close callback. Fires once when the channel closes (whether client- or server-initiated). Cb is called with the close code (int) and reason (string).

  • @p Cb is a callback with signature (code, reason).
  • @r this object

• onError (callback Cb)

  Registers (or replaces) the error callback. Fires for IO errors and other channel-level failures. Cb is called with the error message string.

  • @p Cb is a callback with signature (message).
  • @r this object

• close (int Code = 1000, string Reason = "")

  Server-initiated close. Defaults to code 1000 (normal) and an empty reason.

  • @p Code is an int with the close code. Defaults to 1000.
  • @p Reason is a string with a human-readable reason. Defaults to "".
  • @r this object

• getReqPath ()

  Returns the original handshake request URI path.

  • @r A string with the request path.

• getReqHeaders ()

  Returns the handshake request headers as a map (lower-cased keys). Multi-valued headers come back as lists of strings; single-valued headers come back as plain strings.

  • @r A map of headers from the original handshake.

• getQueryString ()

  Returns the raw query string from the handshake URI, or "" if none was supplied.

  • @r A string with the query string.

• getSrcAddress ()

  Returns the source IP of the client connection.

  • @r A string with the source IP.

class: cache

[758:14] (extern: com.lehman.aussomserver.connectors.AussomCache) extends: object

Class that handles caching operations.

Methods

• cache (int expireAfterMins = 30, int maxNumberOfEntries = 10000)

  Constructor that creates a new cache.

  • @p expireAfterMins is an optional int with the number of minutes that the entry can live for.
  • @p maxNumberOfEntries is an optional int with the maximum number of entries that the cache can hold.
  • @r A new cache instance.

• _newCache (expireAfterMins, maxNumberOfEntries)

• put (string key, val)

  Puts the provided key and value into the cache. If the value already exists it is overwritten.

  • @p key is a string with the key.
  • @p val is the value to store.
  • @r This object.

• get (string key)

  Gets the value with the provided key, or returns null if not found.

  • @p key is a string with the key to get.
  • @r The value, or null if not found.

• invalidate (string key)

  Invalidates (deletes) the cache entry with the provided key.

  • @p key is a string with the key to invalidate.
  • @r This object.

class: method

[717:6] static extends: object

Defines the HTTP method types.

Members

• get
• put
• post
• delete
• options
• head
• patch
• trace

class: AppBase

[630:7] extends: object

Base App object that other Aussom Server apps extend. For lifecycle queries (reload / shutdown polling and pre-event callbacks), use the app static class: if (app.isStopRequested()) return; app.onBeforeReload(::cleanup);

Methods

• http_err_404 (req)

  Handles the default 404 error.

  • @p req is the http request object.

• http_err_500 (req)

  Handles the default 500 error.

  • @p req is the http request object.

class: props

[662:21] static (extern: com.lehman.aussomserver.connectors.Properties) extends: object

Provides property support.

Methods

• encrypt (string Str)

  Encrypts the provided string using the app encryption key. The key is either sent on startup with -Daussom-server.key or is provided as the 'key' entry in the config file.

  • @p Str is the plain text string to encrypt.
  • @r The encrypted string.

• decrypt (string Str)

  Decrypts the provided string using the app encryption key. The key is either sent on startup with -Daussom-server.key or is provided as the 'key' entry in the config file.

  • @p Str is the encrypted string to decrypt.
  • @r The decrypted string.

• getEnv ()

  Gets the environment identifier. (ie dev, qa, prod) This is set in config.yaml at the root level as 'env' and defaults to local.

• load (string FileName)

  Loads the YAML properties file with the provided file name. The file must exist in the app directory, but NOT in the public or app_data directories. This will load the properties under the root node that corresponds to the current environment set (env) in the config.yaml. For instance if env is set to 'local', then the root node in the properties file to load must be 'local'. Note that this appends the properties to the existing properties.

  • @p FileName is a string with the YAML file to load.
  • @r A map with all of the properties.

• get ()

  Gets the map with all the properties. Note that this is a copy of the properties map. You can change the values but they won't change the one's stored.

  • @r A map with all the properties.

class: HttpFormFile

[434:14] (extern: com.lehman.aussomserver.connectors.HttpFormFile) extends: object

HttpFormFile is the per-file reader returned by HttpFormData.getFile(). It wraps a single multipart file part and exposes a chunked read API that mirrors HttpReq.sendChunk on the response side. The underlying input stream reads from a temp file the server spooled to disk during the multipart parse, so nothing larger than the chunk buffer ever sits on the JVM heap. Reading the same file a second time is not supported - readChunk() advances a stream cursor and at EOF further calls return an empty Buffer. Typical usage: ff = fd.getFile("upload"); while (!ff.eof()) { buf = ff.readChunk(65536); // process the chunk } ff.close(); Lifetime: an HttpFormFile is only valid while the request handler is running. The form's close() method closes every reader it created, so handlers should normally let the HttpFormData own the cleanup rather than closing each reader individually.

Methods

• getFieldName ()

  Gets the form field name that carried this file part.

  • @r A string with the field name.

• getFileName ()

  Gets the original file name as supplied by the client. May be empty if the client did not provide one. Do not trust this value as a path; treat it as untrusted user input.

  • @r A string with the uploaded file name.

• getContentType ()

  Gets the content type the client advertised for this part, or an empty string if none was provided.

  • @r A string with the content type.

• getFileSize ()

  Gets the size in bytes of the uploaded file as known to the parser. The size is known up front because the parser has the complete part on disk by the time HttpFormData is returned.

  • @r An int with the file size in bytes.

• eof ()

  Reports whether the reader has reached end of file. Becomes true after a readChunk() call that returns no more data.

  • @r A bool, true once EOF has been observed.

• readChunk (int MaxBytes)

  Reads up to MaxBytes from the underlying stream and returns the bytes as a Buffer. At EOF returns an empty Buffer, and every subsequent call also returns an empty Buffer. The Buffer's length tells you how many bytes were actually read, which may be less than MaxBytes even before EOF.

  • @p MaxBytes is an int with the maximum number of bytes to read.
  • @r A Buffer with up to MaxBytes of file content. Empty at EOF.

• close ()

  Closes the underlying input stream. Idempotent. Prefer letting HttpFormData.close() sweep every reader in one call rather than closing each one explicitly.

  • @r This object.