PGI: Porthole Gateway Interface PGI: Porthole Gateway InterfaceIn the previous section we defined the basic PGI specification. In this section we layer three important features of PGI which add to this basic operation.
Fronting is the process of executing a PGI first, for the purpose of performing some task which might affect the layout of a request beyond the extent of the porthole from which the request came. This is similar to action methods being executed before render methods in JSR168. A request marks a particular porthole as being fronted by means of a reserved query key, _pgi_front. The value of this query key is the key of the porthole to be fronted.
In PGI-Single mode (and PGI-CGI) the output is taken as the output for each instance on the page. In other modes output is ignored and the PGI is reinvoked (or perhaps not, if not displayed) at rendering time. When the environment is transmitted, the PGI-Fronted environment variable is set to the string 1. If a porthole is fronted then it is the only script to receive input data on stdin, other scripts receive blank inputs.
PGI authors should be wary of claims of frontedness, as these may be altered, added or removed by a malicious user.
Bursting is the process of an inner porthole overriding the output of an outer porthole, so that it forms the top level-output element, this is called bursting a page. Outer porthole output is discarded, and only the inner content is displayed. This is most useful when central content wishes to display content of a type other than html (or similar hypertext), such as pdf or postscript.
To burst, a porthole simply includes a burst header with value 1.
A session intended to correspond to a period of interaction of a particular user at a particular computer with a website, during which a large quantity state can be expected to be maintained. It's a little like the idea of a conversation between two people. This is a wooly concept, it can be interpreted in many different ways. A PGI-based system needs to come up with some heuristic. Certainly logging in and out should terminate a session. Some period of inactivity, perhaps thrity minutes, perhaps a day, can also be seen as terminating a session.
A session is terminated (and a new one created) by use of the Session header line from any PGI script with value terminate. No other value is currently defined.
Telegraphics are the communications between portholes. The standard names and conventions to allow collaboration are described elsewhere, here we define the mechanism. Telegraphics are intended to be short messages to issue signals, to select under small closed sets (skins, userid, and so on), and to indicate the location of more comprehensive resources. They are not intended to be efficient for transfer in more bulk quantities.
A telegram is a key-value pair. Each is a string. The value is URL-encoded, so can contain any byte value. Telegrams have a scope and a visibility. The scope is the extent of a telegram, from creation to destruction, the visibility determines whether a telegram can be seen. A telegram may well be within scope, but invisible. However, implicit in being visible is being in scope.
The scope of a telegram can be scope-global, scope-session, or scope-request. A global telegram persists indefinately, a session scoped request persists whilst a session exists, and a request just for a particular page request. Visibility takes the form of a set of constraints. Only when all the constraints are satisfied does the telegram become visible. Visibility constraints are arranged into sets of mutually exclusive choices. These sets are known as strata. Exactly one constraint must be chosen from each stratum. The purpose of restricting visibility is that it allows loose keying of telegrams, relatively simple names can be used within a restricted scope. No telegram ever overwrites another, though more-specific telegrams hide less specific ones. Specificity is judged by considering strata in order. The first stratum is the primary key, the second is the secondary key, and so on.
The first, implicit, stratum is determined by the telegram's scope. A scope-global telegram has no constraints of visiblity placed upon it by this stratum, a scope-session telegram is only visible when rendering within that session, and a scope-request only within that request. For the purposes of hiding, this is the primary key for ordering purposes, and request is more specific than session which is more specific than global.
The second stratum is determined by the nesting of the portholes within the output page. A nest-only telegram is only visible to inner portholes, a nest-all telegram is not so restricted. An fronted request is assumed to be an outermost nest for this calculation. For the purpose of hiding, this is the secondary key. A nest-only telegram is more specific than a nest-all telegram.
A third stratum is dependent upon porthole key. Either a telegram is restricted to a particular key, or else is key-global. For the purpose of hiding, this is the tertiary key. A porthole-specific key is more specific than a porthole-all key. porthole-specific keys can never hide each other, their comparative specificity is undefined. Further strata are expected to be defined in the future.
Therefore, a scope-session, nest-all, porthole-all telegram is visible throughout a session, throughout all portholes, however nested, and whatever their key. It will obscure a scope-global, nest-only, porthole-specific key. When a key is returned its visibility is returned alongside, so a PGI programmer can be assured they have the correct key. A programmer can also specify one or more of the strata upon retrieval or deletion to reveal hidden keys.
Telegrams are manipulated using line-blocks on stdin/stdout, communicating with the assembler. A request takes the form of PGI-telegram-set, PGI-telegram-get, PGI-telegram-del headers. They return a PGI-telegram-X-status (with X set, get or del) header with value okay or an error message. Get can also return missing if no value has been set. Get additionally subsequently returns PGI-telegram-get-value on okay, which is a URL encoded value of the telegram. The request is a single line-block, as is the response.
Each request takes the form of a set of strata, followed by a key. The strata are enclosed in square brackets, in order, and are comma delimited. There is optional whitespace around all tokens. For get and del the stratum list is optional. If supplied, a value can be omitted for get and del by specifying an empty entry. If not supplied [] must be written. For set the stratum list is mandatory and must be complete. The value return header begins with a stratum list, followed by ws and then a URL-encoded value. Stratum values are case and minus/underscore insensitive, and valid values are:
Telegraphics requests must take place in the context of a particular porthole key. For PGI-normal and PGI-wide mode, then, and optionally in other modes, a telegram request must be preceded by a PGI-context: header, followed by a pgi-id supplied to the request. The response is PGI-context-status:, which will be okay or an error message. The context continues to stream closure, or the next PGI-context header.
main spec page | Basic Spec (spec1) | Fronting, Bursting and Telegraphics (spec 2) | Caching (spec 3) | Naming (spec 4)
This project was executed as an infrastructure component of an
EPSRC CTA award at CARET.