Kno Requests

Kno services usually operate by processing requests which might be a web server, a queue server (like Kafka or SQS), or an RPC call using any of a variety of protocols.

Rather than passing request descriptions from function to function, Kno provides a native representation of the current request which can be accessed generically. This implementation also has a way of logging request specific events for debugging or auditing.

The function (REQ/LIVE?) identifies whether a request is active in the current thread. The current request has a collection of fields named by symbols. Request fields differ from thread variables because request contexts may move from thread to thread as the request is processed.

The function (REQ/GET *fieldname*) gets the value of a particular field and returns the empty choice if the field doesn't exist within the current request. (REQ/GET *fieldname* [*default*]) returns default if the field doesn't exist.

The function (REQ/VAL *fieldname*) is just like REQ/GET but if the value is a string, it attempts to parse it as an argstring.

Request fields can be modified by REQ/STORE!, REQ/ADD!, and REQ/DROP!, which work like the corresponding table functions.

The function (REQ/DATA) returns a copy of the underlying data structure for the requests fields. This is usually a slotmap.

Request-specific logging can be done by using the REQ/LOG special form, which has the form:

(REQ/LOG [*loglevel*] [*condition*] [*context*] *printout args*...)

where loglevel must be a fixnum and condition and context must be symbols. These are not evaluated. A message is then generated by processing printout args. This generates an XML log entry of the form:

<logentry level=*level* scope=*request*>
 <level>*level*</level>
 <datetime tick=*unixtime_secs* nsecs=*nanoseconds*>*timestring</datetime>
 <condition>*condition*</condition>
 <context>*context*</context>
 <message>*message*</message>
</logentry>

The current log can be retrieved (as a string) with the function (REQ/GETLOG) and it may be handy to just get the length of the log by calling (REQ/LOGLEN).

The special form WITH-REQUEST executes its body within an active request. It has the form:

(with-request *req*
  *body*...)