PGI: Porthole Gateway Interface

PGI Spec: Naming, Case-Folding and Escaping

Introduction

PGI uses a number of name spaces, which must be managed, and has a number of escaping conventions which should be described carefully. This document covers those two topics.

Methods of Escaping

Line Escape

Definition: Line escape consists of key-value pairs. They are emitted in blocks comprising a set of key/values. Keys are constrained in their contents. They may contain alphanumerics, digits, minus and underscore. The key is transmitted first, followed by a colon, then any number of SPC or HT. Text after this is the value. The value is terminated by CRLF, though a receiver must accept CR or LF as terminating too. CR/LF and NUL may not occur in the value. Values which may contain these characters or significant leading/trailing/multiple SPC or HT will be specified as additionally url-escaped.

A CRLF CR or LF may occur at any point. If followed by one or more SPC or HT, all these characters are discarded, and the value continues. If it is followed by another CR LF or CRLF, then this marks the block end. Otherwise it marks the end of this pair.

Uses: Line escape is used on stdin/stdout, it forms a single block which never terminates. There should be a flush at least after each key/value pair. In PGI modes where the environment is sent on stdin, a single header block represents the transmission of the environment. After exactly content-length bytes, the system reverts to header mode for the next request. stdout uses this escaping system for output to the assembler.

URL Escape

Definition: URL escaping is used throughout PGI, not only in URLs. Its definition is specific. Any character other than alphanumerics, minus or underscore must be escaped with a two digit hex code follwoing a PERCENT. Decoders may accept other carachters as valid. Encoding is byte-literal, without reference to a character set.

Uses: The Pgi-Request: environment variable is URL escaped, as are values in telegraphics (after stratum specs), and lifetime list values.

Unescapable keys

Keys in line escape environments, preferons, product keys, PGI IDs, and in arguments are unescapable. They can contain only alphanumerics, minus and underscore.

Methods of Case-folding

Case folding is the process of reducing a form with variant representaions, such as case-insensitivity into a canonical form.

Key-Folding

Keys are case insensitive, and they do not distinguish minus from underscore. The canonical form uses lower-case and minus. All unescapable keys are case-folded, as are values of the PGI_REVISION environment variable, the will and wont responses of mode negotiation, pgi-*-status responses, telegraphics stratum names, preferons, product prefixes, lifetime list keys and atom names.

stdin/stdout communication

Different namespaces cover requests and responses. Headers beginning X- can be used for experimentation.

Requests

Responses

Output Headers

These headers occupy the same space as claimed by both HTTP and CGI. Future headers may be defined by future revisions of this standard. Headers beginning X- are reserved for experimentation.

Key	Defined in	Value escaping
burst	spec2	none
session	spec2	none
preferon-set	spec3	none
preferon-add	spec3	none
preferon-remove	spec3	none
sales-line	spec3	none
various	CGI and HTTP	none

Environment

The environment key namespace should only be expanded by future revisions of this specification apart from those beginning X_ which may be used for experementaion and extensions.

Key	Defined in	Value escaping
various	CGI as modified by PGI in spec1	none
pgi-revision	spec1	key-folded
pgi-request	spec1	url-escaped
pgi-fonted	spec2	none
pgi-get-sales	spec3	none
pgi-preferons	spec3	none
pgi-product	spec3	none

Request Key/Value pairs

Request key value pairs are arguments, with the addition of further values to specify the reuqest. All these begin pgi- which is prohibited as a prefix in arguments.

Key	Defined in	Value escaping
pgi-path	spec1	All values are URL encoded
pgi-key	spec1
pgi-id	spec1

Inclusion and Arguments

Arguments can be any key-value, excluding those beginning pgi-. The pgi-name argument in HTML inclusion specifies the name of the included portlet. A namespace-partitioning scheme is established to allow the division of argument space amongst applications. Agruments containing at least two hyphens are managed by this convention, other arguments are local in scope. Preceding the first hyphen is a name coding a naming authority. Between the two hyphens is a name corresponding to a project, after is freeform.

Naming Authorities

HTML Parameters

Parameters beginning _pgi_ are reserved, PGI applications should avoid using them.

Parameter	Allocation
_pgi_fronted	Fronting (see spec2)
others	Currently unused

Telegraphics Strata

Strata are key-folded.

Name	Stratum
scope-global	First
scope-session	First
scope-request	First
nest-all	Second
nest-only	Second
porthole-this	Third
porthole-all	Third

Interoperation with Arguments/Telegraphics

Telegraphics notionally occupy the same namespace as arguments, and use the same namespace-partitioning system. Porthole names for paths are also conventional, if they contain a single hyphen.

Prefix	Use
r	Relationships
x	Experimental/Local
others	Currently unallocated

The relationships namespace is used to denote nesting in pre-established ways. It is defined below, and may be extended.

Name	Application
r-main	Principal inner porthole which this outer porthole surrounds in ephemora.
others	Currently unallocated

Preferons

Preferons with two or more hyphens operate in a de facto managed namespace. Before the first hyphen, the managed namespace to be used is specified, followed by the base name of the preferon. Following the hyphen is a value field which is open to user indexes.

The following namespaces are defined.

Prefix	Use
g	Generic preferons, common in web-applications.
x	Local/experimental use
others	Currently unallocated

The following is the current contents of the generic preferons.

Prefix	Application
g-user-	User ID
g-class-	Member of user class
g-skin-	Skin/Appearance chosen by user
g-mode-	Website 'mode' (eg edit/view/minimal, etc)
others	Currently unallocated

Product Prefixes

Product prefixes have a managed filespace for common classes of product, though products may well find few advantages to using them, it can do no harm, particularly as the future of the PGI spec is unknown, and it will help debugging programmers, and those who use product inputs and library code for scripts. A single hyphen is used in managed products. A managed space within this system is provided as an alternative to hyphenless product prefixes.

Prefix	Application
g	Generic product prefixes, common in web-applications.
u	User prefixes, unmanaged.
x	Local/experimental use
others	Currently unallocated

The following is the current contents of the generic product prefixes.

Prefix	Application
g-forbidden	Page indicating permission denied
g-view	View mode product (usual pages)
g-edit	Edit/Admin mode product
g-error-*	Error page of some type

Lifetime List

Keys in lifetime lists are defined in this specification. Those beginning X- are reserved for experimentation or local use. They are defined in spec3. Values are url-escaped. Currently defined keys are as follows.

Key	Value Type
not-used-for	time string
last-checked	time string
check-file	file path
x-*	local/experimental use
others	Currently unallocated

Predicate Atoms

Predicate atoms are key-folded. They are defined below, those beginning x are available for local/experimental use.

Predicate	Summary	Arguments
t	true	none
f	false	none
pr	preferon	preferon name
pi	pathinfo	pathinfo name
kp	key presence	key name
kv	key value	key name,key value
ap	arg presence	arg name
av	arg value	arg name,arg value

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.