OGP Maintenance Design

= Maintenance =
OGP Maintenance refers to an extension of the existing OGP Login protocol to support per-user maintenance tasks when an agent "logs in." Per-user, login-time maintenance is considered "better" in some cases than universal maintenance because:
# it reduces the requirement for system-wide downtime
# assuming that all agents do not "log in" simultaneously, it distributes the load of maintenance across time
# and, it consumes system resources only for those agents who actually "log in."
 
It is not, however, without disadvantages:
# performing per-user maintenance can lead to more complex systems
# agents who do not "log in" frequently will experience delays as pending maintenance is performed.
== Dramatis Personae ==
* the user : the human or automated service on whose behalf interaction with the grid is initiated
* an account : an administrative convenience maintained by the agent domain on behalf of the user "containing" one or more agents
* the agent : a specific actor on the grid, identified uniquely by a name, a UUID and a credential
* the client : the software component participating in the protocol with the agent domain and optionally (hopefully) a region
* the agent domain : a collection of systems that respond to OGP and report and manipulate agent related information
* the credential : a syndrome of a shared secret presented by the client to the agent domain on behalf of the user
* a maintenance token : an opaque data structure representing maintenance being done by the agent domain on the user's behalf
== Requirements ==
* Maintenance must occur subsequent to authentication
* The client must be alerted that maintenance is occurring
* The agent domain must not require a client to re-authenticate themselves in order to check on the status of ongoing maintenance, once the client has been informed that maintenance is occurring (subject to reasonable limitation on the validity period of the credential)
* The agent domain must use the initial authentication (that started the maintenance process) to continue the login process (subject to reasonable limitation on the validity period of the credential)
* (reasonable limitation on the validity period of a credential)
** In situations where a credential has a validity period (X.509, OpenID, etc.) the agent domain must not depend on an authenticator after it's validity period is expired.
** An agent domain may choose a "reasonable" validity period for credentials that do not have an explicit validity period (shared secret, SRP, etc.)
* The agent domain should give the client an estimate on how long maintenance should last
* If a user "logs in" using two distinct clients with the same agent, the agent domain should provide the same maintenance token to both clients
* The agent domain must expose an interface allowing the client to use the maintenance token to retrieve status information regarding ongoing maintenance
 
== A Few Comments ==
* If the agent domain has a good estimate for how long maintenance will take, it may choose to delay responding to maintenance caps for some period of time.
** This has the benefit of discouraging clients from repeatedly querying for status updates. 
* If the agent domain does not have a good estimate for how long maintenance will take, it may choose to insert a smaller delay in responding to maintenance caps.
** This will allow the client to retrieve progressively more accurate estimates of maintenance lengths.
 
== How it maps to the existing implementation ==
* the "maintenance token" is a "maintenance cap"
* when auth.py determines that a transform must be applied, it:
** checks to see if maintenance is under way. If it is not, it:
*** queries ??? for a new maintenance cap
*** updates the user_transformation table to include the current maintenance cap that is executing
*** tells ??? to start performing transforms
** then returns the current maintenance cap
 
== Open Questions ==
* it's possible for an agent to have several transformations to be applied (denoted as several rows in the user_transformation table), so:
** do we use the same maintenance cap for each transformation, or do we create a new cap for each transform?
== Maintenance / Transform ideas ==
Current Maintenance Flow:
 * next_url -> transform.cgi
 * viewer POST credentials again to transform.cgi (not okay for protocol)
OGP Maintenance
 * next_url is a cap
 * Need expiry/lifetime of cap -> connect to user.transform_until
 * If transform_until: give back same cap for next_url
credential is { password | openid url }
Viewer Auth.py
(name,credential) ==>
 * do authentication
 * is a transform currently being performed?
 * return transform cap
 * is there a transform?
 * get cap for transform
 (name,transform type) ==>
 <== (cap)OGP Maintenance
Category:Grid_Interoperability
Category: Pyogp
Category:Pyogp_Kitchen_Sink