Yxorp has several types of rule, each of which is applicable to a specific phase of processing a request or reply, or addresses a specific situation that may occur during the processing of a request or response.
For the purpose of documentation, it is easiest to deal with the rule types by dividing the processing of a single request and the response to that request in three groups: Request processing, server selection, and response processing.
The drawing below shows which rules are run during Yxorp's request processing, i.e. the process that happens from the point when Yxorp has received a request from a client, to the point where Yxorp needs to figure out which server to send that request to.
In the drawing, the observant reader will note that the green 'state' box in the lower left includes 'request ready to be processed from cache'. The current version of Yxorp does not define rules to run if a request is served from Yxorp's cache; this will be added in some future version.
The request rule is run whenever a request is processed, and a request rule is defined. The request rule must be defined on the listener that the request comes in on. Because the request rule is by definition the first rule that runs in the processing of a request, it has no context (i.e. no variables set by other rule types can exist).
The request rule has access to all headers that have been taken from the request, and the following special variables:
|
Name |
Use |
|---|---|
|
uri |
The uri variable has the uri for the current request. It is in the form as taken from the request, except that it is normalized to a relative uri, i.e. the protocol and host parts are removed if the request contained them. In RFC2396 terms, everything up to the path specification is removed. The uri variable may be assigned a different value. If this is done, the request that is sent to the server will contain the modified value. |
|
method |
Set to the method name. Use for reference only; changing this variable will have no effect. |
|
rejectedheaders |
If Yxorp rejects a header (because it does not know this header, it is overlength, contains illegal characters, etc) the header name is appended to this variable to form a space-separated list of all rejected variables. |
An inboundentity rule is used when a request is processed, and an inboundentity is present on the request, and the rule is set for this request. The rule may either be inherited from a definition on the listener that this request came in on, or it may be set by a request rule by calling the setinboundentityrule() function.
The inboundentity rule runs in the context of the request; that means that it has access to all the header variables and also non-header variables that were set in the request rule. All values for the variables will be as they were left by the request rule.
Inboundentity rules also have access to the same special variables as request rules do. Beyond that, the entity itself is also available to this rule type, but currently this is limited to access through function calls only (there is an experimental function that takes the entity and puts it in a variable, but that function will be deprecated in a future version).
The reject rule is run whenever the base code of Yxorp detects an error during the processing of a request, or when a rule executes a reject() function call. The context of the reject rule depends on the rules that ran before it. It inherits all non-header variables from those rules.
If a reject rule runs (either by a call to the reject() function or triggered by the base code), the effect is ultimately that the request or response is not processed normally. If a connection to the client exists at the time that the reject is processed, an error message will be sent to the client. In some cases, this will include a meaningful error code as defined in the HTTP specification. In many other cases, the error code will be a default of 400 – Bad request, because the HTTP specification does not include status codes for all reasons that Yxorp may reject a request for.
Reject rules have access to a number of special variables that allow you to change the error that is sent to the client. It is also possible to include HTML into the error message, so that a simple page can be displayed by a browser.
|
Name |
Use |
|---|---|
|
rejectreason |
holds the text message explaining the reason that the Yxorp base code rejected the request. |
|
statuscode |
holds the status code reported by the server that processed the request |
|
errorcode |
if set, the error code from this variable will be reported to the client instead of the default (400 – Bad Request) in case of a rejected request |
|
errormessage |
if set, the error reason string from this variable will be reported to the client instead of the default (400 – Bad Request) in case of a rejected request. |
|
errorhtml |
if set, html code contained in this variable will be inserted in the reject message. |
|
errortitle |
if set and errorhtml is not set, this variable defines the contents of the <title> tag in a reject page. |
|
errorrejectreason |
if set and errorhtml is not set, this variable allows an override of the default reason string in a reject page. |
The diagram below shows how Yxorp selects to which server a request should be sent, and which rules may run during this process. Rules only run during the server selection process if something went wrong; either Yxorp is unable to send the request to a server, or the server that the user was sticky-loadbalanced to is no longer available.
A sorry rule is run by Yxorp if it can not connect to a server, respecting the in- or out-of-service and available status, and retries to the maximum configured in the globalconfiguration item maxserverconnectionattempts.
The sorry rule can call functions that change the processing of the request (for instance sending it to another server by calling the settargetserver() function); or call the redirect() function that will cause the client to redirect to another URL (for instance a 'sorry' page), or call the reject() function, causing an error to be returned to the client.
Both the reject() and redirect() function calls cause the reject rule defined for this request to be run. If neither of these functions is actually called during the execution of the sorry rule, Yxorp assumes that some other aspect of the request was changed by the rule and will retry to setup a session, up to and until the maximum specified in maxserverconnectionattempts. If the maximum retries are exhausted, Yxorp ends the request by causing a reject, and causing a reject rule, if defined, to be run.
Sorry rules inherit variable tables, including header variables, from earlier rules. Sorry rules may also access the following special variables:
|
connectionretries |
holds the number of times that yxorp attempted to set up a connection to a server during the processing of this request. |
|
maxconnectionretries |
holds the number configured in globalconfiguration item maxserverconnectionattempts. |
A stickyloss rule is run by Yxorp if it can not contact, within the current retry limits set in the globalconfiguration, and respecting the available status, the specific server that this specific request should be send to according to the sticky load balancing state that Yxorp maintains for this client.
A stickyloss rule can call functions to change the processing of the request (exactly like sorry rules can). In this specific situation however, changing something about the request may not make sense; the specific server maintaining the state can not be made contactable in this way.
Both the reject() and redirect() function calls explicitly or implicitly cause the reject rule defined for this request to run. If neither of these functions is called, Yxorp assumes that some other aspect of the request was changed by the rule and will retry to setup a session, up to and until the maximum specified in maxserverconnectionattempts. Keep in mind however that this may not make sense, because the specific server maintaining the state will most probably still not be contactable.
If the maximum retries are exhausted, Yxorp ends the request by causing a reject, and causing a reject rule, if defined, to be run.
Stickyloss rules inherit variable tables, including header variables, from earlier rules. Stickyloss rules may also access the following special variables:
|
connectionretries |
holds the number of times that yxorp attempted to set up a connection to a server during the processing of this request. |
|
maxconnectionretries |
holds the number configured in globalconfiguration item maxserverconnectionattempts. |
|
stickylost |
set to 1 if a stickyloss situation has occurred for this request; this variable may be used to disambiguate where the same rule code is shared by sorry or stickyloss rules |
The diagram below shows which rules Yxorp runs during the processing of a response. This is the final stage of Yxorp's processing of a request.
Response rules are run by Yxorp when a response rule is defined for this request, either inherited from the listener the request originally came in on, or set by calling the setresponserule() function in a rule previously run for this request.
The response rule inherits any non-header variables from earlier rules. Header variables are taken from the response as sent by the server. The response rule also has access to the following special variables:
|
Name |
Use |
|---|---|
|
uri |
for reference only |
|
method |
Set to the method name. Use for reference only; changing this variable will have no effect. |
|
rejectedheaders |
If Yxorp rejects a header (because it does not know this header, it is overlength, contains illegal characters, etc) the header name is appended to this variable to form a space-separated list of all rejected variables. |
Outboundentity rules are run by Yxorp when a response rule is defined for this request, either inherited from the listener the request originally came in on, or set by calling the setoutboundentityrule() function in a rule previously run for this request.
The outboundentity rule inherits header variables from the response rule that ran before it. If no such rule exists, no header variables are available to the outboundentity rule. Other, non-header variables are inherited from any other rule that ran before the outboundentity rule.