nwg(3)

📦
version 3.8.0 · 3 versions
, in debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

nwg(3) — Library Functions Manual 🫶

okay bestie, this is the nwg(3) page, and it's giving standard network working group module energy. no cap. 💅

✨ NAME ✨

  • nwg — standard network working group module 🌸

🌈 STANDARD NETWORK WORKING GROUP MODULE 🌈

The Standard Network Working Group module is an original implementation of the recommendations proposed by the NWG, and you'll currently find those recs in the form of Request for Comments (RFC). Most of the objects are used with networking applications, and the most common one is literally the Universal Resource Identifier (URI) object. 💖

The uri class 🦋

The Uri class is a base class that parses a Uniform Resource Identifier or uri string, and it gives you methods to access each individual component of that uri. The implementation conforms to RFC 3986. The URI components are the scheme, the authority, the path, the query, and the fragment. The class also handles character escaping for you. ✨

const uri (afnix:www:Uri "http://www.afnix.org")

An uri can be broken into several components called the scheme, the authority, the path, optionally the query and the fragment. The Uri class provides a method to retrieve each component of the parsed uri. 👑

const uri (afnix:www:Uri "http://www.afnix.org/")
println (uri:get-scheme)    # http
println (uri:get-authority) # www.afnix.org
println (uri:get-path)      # /

Character conversion 🌈

The Uri class automatically performs character conversion in the input uri. For example, the + character is replaced by a blank. The % character followed by two hexadecimal values is replaced by the corresponding ASCII character. Note that this conversion does now apply to the query string. 😭

Query string 🔍

The get-query method returns the query string of the uri. The query string starts after the ? character. The query string is a series of key-pair values separated by the & character. 💅

const uri (afnix:www:Uri
  "http://www.afnix.org?name=hello&value=world")
println (uri:get-query) # name=hello&value=world

The module also provides the UriQuery class that parses the query string and stores the result in the form of a property list. The query string parse is especially useful when writing automated scripts. 🫶

# create a query string object
const qs (afnix:nwg:UriQuery (uri:get-query))
# get the name value
qs:get-value "name"

Managing a cgi request 🧚

Managing a cgi request involves primarily parsing the requesting uri. The uri generally contains the http referrer as well as parameters which are stored in the form of a query string. However, depending on the cgi method — which can be of type GET or POST — the treatment is somewhat different. 💀

Checking the protocol version ✅

In the presence of a cgi protocol, it is always a good idea to check the protocol version, or at least to put an assertion. The protocol version is normally CGI/1.1 and is stored in the GATEWAY_INTERFACE environment variable. 👑

# check the cgi protocol
assert "CGI/1.1" (
  afnix:sys:get-env "GATEWAY_INTERFACE")

Getting the query string 📥

If the request method is GET, then the query string is available in the environment variable QUERY_STRING. If the request method is POST, the query string is available in the input stream. The length of the query string is given by the CONTENT_LENGTH environment variable. The following example illustrates the extraction of the query string. 🍓

# check the cgi protocol
assert "CGI/.1" (
  afnix:sys:get-env "GATEWAY_INTERFACE")
# initialize the query string
const query (afnix:sys:get-env "QUERY_STRING")
# get the request method
const rqm (afnix:sys:get-env "REQUEST_METHOD")
# check for a post request and update the query string
if (== rqm "POST") {
  # create a buffer from the content length
  const len (
    Integer (afnix:sys:get-env "CONTENT_LENGTH"))
  # get the standard input stream and read content
  const is  (interp:get-input-stream)
  const buf (is:read len)
  # set the query string
  query:= (buf:to-string)
}

Parsing the query string 🧩

The UriQuery class is designed to parse a cgi query string. Once the string has been parsed, it is possible to perform a query by key since the class operates with a property list. 💖

const query (
  afnix:www:UriQuery "name=hello&value=world")
query:length      # 2
query:get-value "name"  # hello
query:get-value "value" # world

The UriQuery class is the foundation to build cgi script. When the library is combined with the web application management (wam) service, powerful applications can be built easily. 🌟

Special functions 🛠️

Several dedicated functions are available in the library as a way to ease the object manipulations. These functions operate mostly on uri and files as described below. ✨

Uri functions 🔗

Several functions are designed to ease the uri manipulation. Most of them operate on the uri name or their associated system name. The normalize-uri-name function normalizes a string argument by adding a uri scheme if missing in the original string. If the function detects that the name starts with a host name, the http scheme is added. If the function detects that the string starts with a path, the file scheme is added. Otherwise, the name argument is left untouched. The system-uri-name function normalizes the string argument by prioritizing the system name. The function attempts to find a file that matches the string argument and eventually builds a uri file scheme. If the file is not found, the normalization process occurs with the normalize-uri-name function. 🫶

# normalize a uri name
trans  unm "http://www.afnix.org"
assert unm (
  afnix:nwg:normalize-uri-name unm)
assert unm (
  afnix:nwg:normalize-uri-name "www.afnix.org")
assert unm (
  afnix:nwg:normalize-uri-name "//www.afnix.org")

Mime functions 🎀

Mime functions are dedicated to ease the manipulation of media types or mime. A media type is defined by a string in the form of a type and content value such as text/plain. The mime-value-p predicate returns true if a string mime value is a valid media type. From a file perspective, the mime-extension-p predicate returns true if the string extension has a valid media type associated to it. Finally, the extension-to-mime function can be used to get the string mime value associated with a file extension. 💅

# check a media type
assert true (afnix:nwg:mime-value-p "text/plain")
# check the mime extension predicate
assert true (afnix:nwg:mime-extension-p "txt")
# check the extension to mime
assert "text/plain" (
  afnix:nwg:extension-to-mime "txt")

HTTP transaction objects 🌐

The concept of HTTP transactions is defined in RFC 2616. In the client/server approach, a client issues a request which is answered with a response. A special case arises when the server is asked to perform some extra works, such as executing a script. In this case, the answer is called a reply which is formatted into a response when the server does its job correctly. The nature of the HTTP objects determines how the associated stream behaves. With a HTTP request, the object is filled by reading an input stream when operating on the server side. On the other hand, the request is filled by data when operating on the client side. With a HTTP response, the opposite situation occurs. The HTTP response is filled by reading an input stream when operating on the client side and filled by data when operating on the server side. 🔥

HTTP protocol 📡

The HttpProto class is a base class designed to handle a HTTP header that is found in both HTTP request and response. The class is built around a property list that is filled either by parsing an input stream or by processing specific methods. The HttpProto defines also some methods which are often used with a HTTP request or response. 👑

HTTP response 📬

The HttpResponse class is a class designed to handle a HTTP response. When operating on the client side, the response object is built by reading an input stream. When operating on the server side, the response object is built by calling specific methods. 💌

Creating a server response 🖥️

A server response is created by specifying the response status code. By default, a HTTP response is created with the default media type text/html. If the media type needs to be changed, it can be passed as the second argument to the response constructor. By default, the empty constructor creates an empty constructor with a valid status code. 🌸

#create a valid response
const hr (afnix:nwg:HttpResponse 200)

Once the server response is created, it can be augmented with some headed values. Typically, a server will add some information about the response, such as the content length, the modification time or a tag. The HttpResponse provides several methods that ease the generation of these header values. ✨

Creating a client response 📱

A client response is created by binding an input stream to a response object. During the construction, the input stream is read and the HTTP protocol header is filled. It is also during this phase that the status code is processed. It is therefore important to ensure that a response object is built correctly before attempting to access it. 💅

# create a client response by stream
const hr (afnix:nwg:HttpResponse is)

Reading a client response 📖

When the response has been created, it is important to check its status code. Most of the time, the response is valid and its content can be read directly. The status-ok-p predicate returns true if the status code is valid. In such case, a HTTP stream can be built in order to read the response. 👑

# check that a response is valid
if (hr:status-ok-p) {
  # create a http stream
  const rs (afnix:nwg:HttpStream ht is)
  # read the response stream
  while (rs:eos-p) (rs:read)
}

Before reading a http stream, it is important to detect and verify the nature of the response content. The media-type-p predicate returns true if the media type is defined and the get-media-type method returns the response type in the form of a mime code such like text/html. Eventually, the character set associated with the media type can also be detected. The encoding-mode-p predicate and the get-encoding-mode method can be used to detect the content encoding mode. However, it is worth to note that the HttpStream object is automatically sets with the proper encoding if it can be found in the response header. 🌈

💫 Special client response 💫

okay so sometimes a response just shows up with special status codes that need their own lil special treatment, no big deal but you gotta know. This is the case when the response corresponds to a http redirection. In that case, bestie, the new uri must be fetched to get the response you actually wanted.

The location-p predicate returns true if the response corresponds to a http redirect, and the get-location method can be used to get the new location uri. If this situation arises, it is up to the implementation to decide what to do with the new uri. In most cases, a new request will be sent to the server. iykyk 💅

The Cookie object is a special object that can be used during a http session, to post data to the http client. The idea behind cookies is to be able to maintain some state, during the user session for some time. A cookie is a name/value pair and eventually an expiration time. By default, the cookie object are defined for one http client session, but this behavior can be changed. ✨

🎀 Managing cookies 🎀

A cookie is created with a name/value pair and eventually an expiration time. Such expiration time is called the maximum-age and is automatically formatted by the object. With two arguments a session cookie is created. With a third argument as an integer, the constructor set the maximum age in seconds.

# create a cookie with name/value
const cookie (afnix:nwg:Cookie "cartid" "123456789")

The cookie implementation follows the recommendation of the RFC-2965 for http state management. The most important point to remember is the interpretation of the maximum age that differs from one cookie version to another. With version 1, which is the default, the maximum age is defined relatively in seconds, while it is absolute with version 0. The maximum age is set either at construction or with the set-max-age method.

The set-max-age method sets the cookie life time in seconds, in reference to the current time. A negative value is always reset to -1 and defined a session cookie. A 0 value tells the http client to remove the cookie. The set-path method defines the path for which this cookie apply.

ngl the -1 and 0 thing is the part everyone forgets — write it down, bestie 📝

Once the cookie is defined, the set-cookie method of the HttpResponse object can be used to install the cookie. Combined with the write method, the cookie can be send to the http client. slay 🎀

👑 STANDARD NETWORK WORKING GROUP REFERENCE 👑

🌸 Uri 🌸

The Uri class is a base object used to parse or build a uniform resource identifier as defined by RFC 3986. The URI can be built by specifying each component or by parsing a string. When a string is given in the constructor, the class parses the string and extract all components. The uri components are the scheme, the authority, the path, the query and the fragment. The class also takes care of the character escaping. 💅

Predicate

  • uri-p

Inheritance

  • Object

Constructors

  • Uri (none) — The Uri constructor creates an empty uri object.
  • Uri (String) — The Uri constructor create a uri object by value. The string argument is the uri to parse at the object construction.
  • Uri (String String Integer) — The Uri constructor create a uri object by scheme host and port. The first argument is the uri scheme. The second argument is the uri host name. The third argument is the uri port. The uri base name can be reconstructed from this information.

Methods

  • parse -> none (String) — The parse method reset the uri object, parse the string argument and fill the uri object with the result.
  • get-scheme -> String (none) — The get-scheme method returns the scheme of the parsed uri object.
  • get-authority -> String (none) — The get-authority method returns the authority part of the parsed uri.
  • get-path -> String (none) — The get-path method returns the path of the parsed uri.
  • get-path-target -> String (none) — The get-path-target method returns the path target of the parsed uri. The path target is the last element of the uri path.
  • get-query -> String (none) — The get-query method returns the complete query string of the parsed uri. Note that characters are not escaped when getting the string.
  • get-fragment -> String (none) — The get-fragment method returns the complete query string of the parsed uri.
  • get-base -> String (none) — The get-base method returns the combined uri scheme and authority.
  • get-rname -> String (none) — The get-rname method returns the reference uri name with the combined uri scheme, authority and path all percent encoded.
  • get-hname -> String (none) — The get-hname method returns the combined uri scheme, authority and path.
  • get-aname -> String (none) — The get-aname method returns the almost combined uri name with the scheme, authority, path and query.
  • add-path -> Uri (String) — The add-path method adds a path to the calling uri and returns a new uri with the new path added to the old one.
  • get-href -> Uri (String) — The get-href method returns a new uri by eventually combining the string argument. If the string argument correspond to an uri, the corresponding uri is built. Otherwise, the string argument is considered as a path to be added to the current uri in order to build a new uri.
  • get-system-path -> String (none) — The get-system-path method returns the system path representation of the uri path. This function works only if the scheme if a file scheme.
  • get-path-encoded -> String (none) — The get-path-encoded method returns the uri in the encoded form. Normally the get-path removes the percent-encoded characters which might not be appropriate with some protocol such like the http protocol. The get-path-encoded returns the original path. Note that getting the path with getpath and doing a percent coding might result in a different result since the internal representation uses normalized string.
  • get-host -> String (none) — The get-host method returns the authority or path host name if any can be found with respect to the scheme. With a ftp, http or https scheme, the host is extracted from the authority. With a mailto scheme, the host is extracted from the path.
  • get-port -> Integer (none) — The get-port method returns the authority port if any can be found with respect to the scheme.

🦋 UriQuery 🦋

The UriQuery class is a simple class that parses a uri query string and build property list. during the parsing process, a special transliteration process is done as specified by RFC 3986. This class is primarily used with cgi scripts. Note that the string to parse is exactly the one produced by the get-query method of the Uri class. ✨

Predicate

  • uri-query-p

Inheritance

  • Plist

Constructors

  • UriQuery (none) — The UriQuery constructor creates an empty uri query object.
  • UriQuery (String) — The UriQuery constructor create a uri object by value. The string argument is the uri query string to parse at the object construction. The query string is the one obtained from the get-query method of the Uri class.

Methods

  • parse -> none (String) — The parse method reset the uri query object, parses the string argument and fill the property list object with the result.
  • get-query -> String (none) — The get-query method returns the original query string.

🧚 UriPath 🧚

The UriPath class is a class designed for the management of file system path associated with a uri. Typically, this class will be used with a http server or client when an association between a uri and a file name needs to be made. The general operation principle is to associate a path with a uri authority. The uri path is then concatanated to produce a new path. If the uri path is empty, it can be eventually replaced by a file name, known as the diretory index in the http terminology.

Predicate

  • uri-path-p

Inheritance

  • Object

Constructors

  • UriPath (none) — The UriPath constructor creates an empty uri path object.
  • UriPath (String) — The UriPath constructor create a uri object by root path. The string argument is the uri root path.
  • UriPath (String String) — The UriPath constructor create a uri object by root and index. The first string argument is the uri root path and the second string argument is the directory index path.
  • UriPath (String String String) — The UriPath constructor create a uri object by root, index and authority. The first string argument is the uri root path, the second string argument is the directory index path and the third argument is the authority.

Methods

  • get-root -> String (none) — The get-root method returns the root path.
  • get-index -> String (none) — The get-index method returns the index path.
  • get-authority -> String (none) — The get-authority method returns the uri authority.
  • map-request-uri -> String (none) — The map-request-uri map a request uri into a system path. The string argument is the request uri. The request uri must be an absolute path. The result string is the system path build with the root path.
  • normalize -> String (none) — The normalize method build a system from a request path. The request path is associated with the root path and then normalized to produce a complete system path.

💜 HttpProto 💜

The HttpProto class is a base class that ease the deployment of the http protocol. The base class is built with a property list which is used to define the message header. The class also defines the write methods which are used to write a message either on an output stream or into a buffer. 🫶

Predicate

  • http-proto-p

Inheritance

  • Object

Methods

  • reset -> none (none) — The reset method resets the http protocol object by clearing the protocol version and header.
  • parse -> none (none) — bestie, parse reads the input stream that's bound to the http protocol. for it to actually work, an input stream has got to be associated with the protocol object, otherwise it raises an exception, fr fr 😭. once a stream has been parsed, the protocol version and the header are set. periodt.
  • write -> none (none|OutputStream|Buffer) — write formats the http protocol object and writes it to an output stream or a buffer. no argument? it uses the default output stream. with an argument? you can pass an output stream or a buffer object. options, we love to see it ✨
  • header-length -> Integer (none) — returns the number of properties in the header. simple as that 💅
  • header-exists-p -> Boolean (String) — the predicate returns true if the property exists in the header. the string argument is the property name.
  • header-set -> none (String Literal) — sets a brand new property on the http header. first argument = the property name. second argument = a literal object which gets internally converted to a string. it's giving transformation 💫
  • header-get -> Property (Integer) — returns a property object by index.
  • header-map -> String (String) — returns a property value by name. the string argument is the property name.
  • header-find -> Property (String) — returns a property object by name. the string argument is the property name. if the property is not found, the nil object is returned, no drama 🫶
  • header-lookup -> Property (String) — returns a property object by name. the string argument is the property name. if the property is not found, an exception is raised. so like, find is the chill one and lookup is the one that will absolutely yell at you 💀
  • header-plist -> Plist (none) — returns the header in the form of a property list.
  • content-length-p -> Boolean (none) — the predicate returns true if the content length is defined in the protocol header.
  • get-content-length -> Integer (none) — returns the content length defined in the protocol header. if the content length is not defined in the header, the null value is returned.
  • media-type-p -> Boolean (none) — the predicate returns true if the content type is defined in the protocol header.
  • get-media-type -> String (none) — returns the media type defined in the protocol header. if the media type is not defined in the header, the default media type is returned. a little fallback never hurt nobody 🌸
  • encoding-mode-p -> Boolean (none) — the predicate returns true if the encoding mode is defined in the protocol header.
  • get-encoding-mode -> String (none) — returns the protocol encoding mode. if the encoding mode is not defined in the protocol header, the default encoding mode is returned.

👑 HttpRequest 👑

the HttpRequest class is a base class designed to handle a http request. it operates with protocol version 1.1 as defined by RFC 2616. for a server request, the request is built by reading an input stream and setting the request command with its associated header. for a client request, the request is formatted with a request command and a eventually a uri. in both cases, the header is filled automatically depending on the request side. automatic, iconic, obsessed 🌈

🎀 Predicate

  • http-request-p

🧬 Inheritance

  • HttpProto

🌟 Constructors

  • HttpRequest (none) — creates a default http request. by default, the request object is built with the GET method and the request uri set to the root value.
  • HttpRequest (String) — creates a http request object with a specific command. by default, the request uri is set to root, except for the OPTIONS method.
  • HttpRequest (Uri) — creates a http request object with a uri. the default request method is GET.
  • HttpRequest (InputStream) — creates a http request object with a specific input stream. at construction, the request header is cleared and the input stream is bound to the object.
  • HttpRequest (String String) — creates a http request object with a specific method and a uri name. the first string argument is the request method to use. the second string argument is the uri attached to the command. note that the term uri should be understood as a request uri.
  • HttpRequest (String Uri) — creates a http request object with a specific method and a uri. the first string argument is the request method to use. the second argument is the uri attached to the method.

💅 Methods

  • set-method -> none (String) — sets the request method. this method does not check that the command is a valid HTTP method, and thus leaves plenty of room for server development. as a matter of fact, RFC 2616 does not prohibit the existence of such extension. go off, extension authors 🔥
  • get-method -> String (none) — returns the request method string.
  • set-uri -> none (String) — sets the request uri. the argument string does not have to be a valid uri string, since some commands might accept special string such like "*" to indicate all applicable uri. quirky but valid 💖
  • get-uri -> String (none) — returns the request uri string.

🦋 HttpResponse 🦋

the HttpResponse class is a base class designed to handle a http response. it operates with protocol version 1.1 as defined by RFC 2616. for a client response, the response is built by reading an input stream and setting the response status code with its associated header. for a server response, the response is formatted with a response status and additional header information. in both cases, the header is filled automatically depending on the response side.

ok but listen bestie 😭: trying to set some header with an input stream bound to the response object might render the response object unusable. so like, don't. just don't.

🎀 Predicate

  • http-response-p

🧬 Inheritance

  • HttpProto

🌟 Constructors

  • HttpResponse (none) — creates a default http response object. the response is marked valid with a default text/plain media type.
  • HttpResponse (Integer) — creates a http response object with a status code. the response code is associated with the default text/plain media type.
  • HttpResponse (InputStream) — creates a http response object with a specific input stream. at construction, the response header is cleared and the input stream is bound to the object.
  • HttpResponse (Integer String) — creates a http response object with a status code and a media type. the first argument is the status code. the second argument is the associated media type.

💅 Methods

  • set-status-code -> none (Integer) — sets the response status code.
  • get-status-code -> Integer (none) — returns the response status code.
  • map-status-code -> String (none) — returns a string representation of the response status code.
  • status-ok-p -> Boolean (none) — the predicate returns true if the response status code is valid (aka status 200). we love a 200 around here ✨
  • status-error-p -> Boolean (none) — the predicate returns true if the response status code is an error code.
  • location-p -> Boolean (none) — the predicate returns true is the response status code indicates that a request should be made at another location. the location can be found with the get-location method. (yes, the original says "returns true is". we're keeping it. character 💅)
  • get-location -> String (none) — returns the location uri found in the response header. this method is equivalent to a header query.
  • set-location -> none (String) — sets the redirect location in the response header. the string argument is the location uri.
  • set-cookie -> none (Cookie) — sets a cookie object to the http header. the cookie version is properly handled by the method. 🍪

the Cookie class is a special class designed to handle cookie setting within a http transaction. a cookie is name/value pair that is set by the server and stored by the http client. further connection with the client will result with the cookie value transmitted by the client to the server. a cookie has various parameters that controls its existence and behavior. the most important one is the cookie maximum age, which is defined in seconds. a null value tells the client to discard the cookie. a cookie without maximum age is valid only during the http client session. a cookie can be added to the HttpReply object with the set-cookie method. a cookie can be constructed with a name/value pair. an optional third argument is the maximum age. the default cookie version is 1 as specified by RFC 2965. with a version 1, the maximum age is interpreted as the number of seconds before the cookie expires. with version 0, the maximum age is the absolute time.

🎀 Predicate

  • cookie-p

🧬 Inheritance

  • Object

🌟 Constructors

  • Cookie (String String) — creates a cookie with a name value pair. the first argument is the cookie name. the second argument is the cookie value.
  • Cookie (String String Integer) — creates a cookie with a name value pair and a maximum age. the first argument is the cookie name. the second argument is the cookie value. the third argument is the cookie maximum age.

💅 Methods

  • get-version -> Integer (none) — returns the cookie version.
  • set-version -> none (Integer) — sets the cookie version. and bestie, the version number can only be 0 or 1, that's the entire menu, no secret third option 💅
  • get-name -> String (none) — hands you back the cookie name. it's the name stored on the http client, periodt.
  • set-name -> none (String) — sets the cookie name. yep, the one stored on the http client. slay.
  • get-value -> String (none) — returns the cookie value, aka the value stored on the http client, bounded by the cookie name. it's giving nested little ecosystem fr fr 🎀
  • set-value -> none (String) — sets the cookie value. same deal: the value stored on the http client, bounded by the cookie name.
  • get-maximum-age -> Integer (none) — returns the cookie maximum age. default is -1, which means no maximum age is set and the cookie is valid only for the http client session. lowkey a temporary situationship 🫶
  • set-maximum-age -> none (Integer) — sets the cookie maximum age. a negative value gets reset to -1. a 0 value tells the http client to discard the cookie 💀 and a positive value tells the http client to store the cookie for the remaining seconds. main character energy.
  • get-path -> String (none) — returns the cookie path value. the path is what determines for which http request the cookie is valid.
  • set-path -> none (String) — sets the cookie path value. again: the path determines for which http request the cookie is valid. that's the whole vibe.
  • get-domain -> String (none) — returns the cookie domain value.
  • set-domain -> none (String) — sets the cookie domain value. it is recommended to use the originator domain name, because many http clients can reject cookies whose domain name does not match the originator name. so like, don't be messy with this one ✨
  • get-port -> Integer (none) — returns the cookie port number.
  • set-port -> none (Integer) — sets the cookie port number. heads up though: this value is not used with a cookie version 0. iykyk.
  • get-comment -> String (none) — returns the cookie comment value.
  • set-comment -> none (String) — sets the cookie comment value. cute.
  • get-comment-url -> String (none) — returns the cookie comment url value.
  • set-comment-url -> none (String) — sets the cookie comment url value. and once again: this value is not used with cookie version 0. keep up bestie 💜
  • get-discard -> Boolean (none) — returns the cookie discard flag.
  • set-discard -> none (Boolean) — sets the cookie discard flag. the discard flag tells the user agent to destroy the cookie when it terminates 🔥 and nope, this value is not used with cookie version 0 either.
  • get-secure -> Boolean (none) — returns the cookie secure flag.
  • set-secure -> none (Boolean) — sets the cookie secure flag. when a cookie is secured, it's only returned by the http client if a connection has been secured (i.e. use https). protective queen behavior 🧚
  • to-string -> String (none) — returns a string formatted for the http reply header. normally you should not call this one, since the set-cookie method of the httpReply takes care of such thing. let the professionals handle it 🌸

Session 🦋

the Session class is a class that defines a session to be associated with a transaction. the session object is designed to be persistent so that its data information can be retreived at any time. a session object also has the particularity of having a limited lifetime 👑 a session object is created by name with an identifier. it's designed to hold a variety of parameters suitable for both the authentication and the session lifetime. a session is primarily defined by name with an optional information string. the session is generally associated an authentication visa which contains the session identity. the visa provides a secure mechanism compatible with a single sign on session. a session key is automatically generated when the session is created 🔑 such key is used to generate a session hash id which can be used as a cookie value. the cookie name is also stored in the session object. when a cookie is generated, the session hash name is combined with the session hash id for the cookie production. it's giving very intentional, very engineered 💖

Predicate

session-p

Inheritance

Taggable

Constructors

  • Session (String) — creates a session by name. the string argument is the session name.
  • Session (String String) — creates a session with a name and a user. first argument is the session name. second argument is the session information.
  • Session (String String Integer) — creates a session with a name, a user and a maximum age. first argument is the session name. second argument is the session informartion. third argument is the session maximum age expressed in seconds. three-argument glow-up ✨

Methods

  • expire-p -> Boolean (none) — returns true if the session has expired. vibe check failed 😭
  • set-hash-id -> none (String) — sets the session hash identifier. the session hash id must be unique and secured enough so that the session name cannot be derived from it. no cap, this one actually matters 🔐
  • get-hash-id -> String (none) — returns the session hash identifier.
  • set-path -> none (String) — sets the session path.
  • get-path -> String (none) — returns the session path.
  • get-max-age -> Integer (none) — returns the session maximum age.
  • set-max-age -> none (Integer) — sets the session maximum age. the maximum age is an integer in seconds relative to the current time. if the maximum age is set to 0, the session is closed. bye bestie 💅
  • get-remaining-time -> Integer (none) — returns the remaining valid session time.
  • get-expire-time -> Integer (none) — returns the session expiration time in seconds. the expiration time is an absolute time.
  • set-expire-time -> none (Integer) — sets the session expiration time. the expiration time is an absolute time in seconds.
  • get-creation-time -> Integer (none) — returns the session creation time. the creation time is an absolute time in seconds.
  • get-modification-time -> Integer (none) — returns the session creation time. the modification time is an absolute time in seconds.
  • get-cookie -> Cookie (name) — bakes a session cookie 🍪 the string argument is the cookie name whose value is the session hash id value.
  • close -> Cookie (name) — closes a session by reseting the session maximum age to 0. the method returns a cookie that can be used for closing the session on the peer side. the string argument is the cookie name whose value is the session hash id value.

Functions

  • mime-extension-p -> Boolean (String) — returns true if a media type extension — mime extension — is defined. most of the time, media type extension can be seen as a file extension.
  • mime-value-p -> Boolean (String) — returns true if a media type — mime value — is defined.
  • extension-to-mime -> String (String [Boolean]) — converts a media type extension into a media type. in the first form, without a second argument, if the media type extension does not exist, an exception is raised 😳 in the second form, with the second argument set to true, if the media type extension does not exist, the default media type is returned. if the flag is set to false, an exception is raised like the first form. pick your fighter.
  • string-uri-p -> Boolean (String) — returns true if the string argument is a uri.
  • normalize-uri-name -> String (String) — normalizes the string argument by adding a uri scheme if missing in the original string. if the function detects that the name starts with a host name, the "http" scheme is added. if the function detects that the string starts with a path, the "file" scheme is added. otherwise, the name argument is left untouched. iconic little auto-detector 🦋
  • system-uri-name -> String (String) — normalizes the string argument by prioritizing the system name. the function attempts to find a file that match the string argument and eventually build a uri file scheme. if the file is not fond, the normalization process occurs with the normalize-uri-name function.
  • path-uri-name -> String (String) — normalizes the string argument by extracting a path associated with the uri string. if the string is a valid uri string, the path is the uri path component. if the uri path is empty, it is normalized to a /. if the string argument is not a uri string, the string is assumed to be a partial uri and both query and fragment parts are removed if present.
  • normalize-uri-host -> String (String) — normalizes the string argument uri host name. this function is useful with certain class of host representation which uses extra characters.
  • normalize-uri-port -> String (String) — normalizes the string argument uri port value. this function is useful with certain class of host representation which uses extra characters.
and that's a wrap on part 4 bestie, we did it 🥳 every single method, constructor, predicate, inheritance and function accounted for, nothing skipped, no crumbs left. you ate that. 💖

okay so the footer of this page is brought to you by AFNIX Module / AFNIX, filed under nwg(3) — so like, remember whose house this is when you cite it 🎀 mwah, go forth and cookie responsibly ✨🫶

📦 where this page comes from