Difference between revisions of "SLGOGP Teleport Strawman"

From Second Life Wiki
Jump to navigation Jump to search
(Replacing page with 'This document has been deprecated. Please reference OGP Explained')
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
This strawman represents a possible open teleport protocol. The sequencing is described first, which also introduces the major players: Client, Agent Domain, Simulator/Region Domain A, Simulator/Region Domain B. For perspective, the current Second Life Grid teleport flow is also included. Following that are the draft specifications for the two main pieces, called rezAvatar and derezAvatar on the agent domain. The simulator side portions of this protocol have been tentatively dubbed "teleport_avatar" and "give_up_av_to_pipe".
This document has been deprecated.  Please reference [[OGP Explained]]
 
 
= Teleport Flow =
 
Here is the basic flow for current SL teleports:
[[Image:Old teleport.png]]
 
<b>Fine tuning the proposed protocol and cap names after discussion with AWG groupies resulted in a unified approach for Login, Teleport, and Logout, diagrammed below:</b>
 
== Login ==
[[Image:Strawman-login-flowchart.png]]
[[Image:Open grid login.png]]
 
== Teleport ==
[[Image:Open Grid Teleport.png | 760px]]
 
== Logout ==
[[Image:Open Grid Logout.png]]
 
= Authentication =
 
*In order to get the agent host seed capability, credentials must first be posted to http://login.aditi.lindenlab.com/cgi-bin/auth.cgi
 
 
== Request: viewer -> auth.cgi ==
 
 
=== Required Parameters ===
{
    'firstname':  <string>,
    'lastname':  <string>,
    'password':  <string>
}
 
or
 
{
    'firstname':    <string>,
    'lastname':    <string>,
    'md5-password': <string>
}
 
=== Optional Parameters ===
{
    'agree_to_tos' : <bool>,
    'read_critical': <bool>
}
 
== Response ==
 
=== Successful ===
 
  status:  302
 
  {
    'authenticated': true
    'location'    : <agent host seed capability url>
  }
 
* Note: the 302 status code will be changed to 200 status in the future
 
=== Unsuccessful ===
 
  status:  4xx - login was unsuccessful
  status:  5xx - server error
 
  {
    'authenticated' : false
    'reason'        : <one word identifier>
    'message'      : <error description>
  }
 
*Non-transport/server errors will be changed to 200 status in the future
 
 
Terms of Service
 
  {
    'authenticated' : false
    'reason'        : 'tos'
    'message'      : <terms of service text>
  }
 
*Once user agrees to terms of service call authenticate again with { 'agreed_to_tos' : true }
 
 
Critical Message
 
  {
    'authenticated' : false
    'reason'        : 'critical'
    'message'      : <critical message text>
  }
 
*Once user has read the message call authenticate again with { 'read_critical' : true }
 
 
Miscellaneous Reason
 
* data - bad input or server side data fetch failed
* key - bad password
* god, restricted, ban, suspend, disabled  - denied based on account details
 
= Agent Information =
{| border="1"
|-
| colspan="2" |
Agent Information
|-
|
Name
|
agent/info
|-
|
URL
|
capability from agent domain
|-
|
Verb
|
GET
|-
|
Response
|
{ agent_id: <uuid>, circuit_code: <int>, session_id: <uuid>, secure_session_id: <uuid>, presence: { status : online|offline, region_url: <url> }
|-
|
|
a map of agent information for this session
|}
 
 
= rez_avatar/place =
* Once the viewer acquires the cap for place_avatar, it requests it from the agent domain
* The viewer can also invoke place_avatar for teleport
== Request: viewer -> agentd ==
{
    'region_url': <r_url>
    'position':  [x, y, z]
}
== Response ==
{
  'seed_capability': uri string
  'look_at' : [f32, f32, f32]
  'sim_ip': ip string
  'sim_port': int
  'region_x': int
  'region_y': int
  'region_id' : uuid
  'sim_access' : <PG/Mature>
  'connect': bool
  'position': [f32, f32, f32]
// The above are the same as response to rez_avatar
// The following are only returned on login, not over teleport
    'session_id':<uuid>
    'secure_session_id':<uuid>
    'circuit_code':<int>
// Extra stuff
    'connect': <bool>
}
 
 
 
= rez_avatar/request =
== Request: agentd -> simulator ==
{
    'agent_id' : <uuid>,
    'first_name': <string>,
    'last_name': <string>,
    'age_verified' : <boolean>,
    'agent_access' : <boolean>,
    'allow_redirect: <boolean>,
    'god_level':  <int>,
    'identified':  <bool>,
    'transacted': <bool>,
    'limited_to_estate': <int>
    'sim_access' : <PG/Mature>,
    'granters': []
}
 
== Example: (hard coded) ==
{
  'agent_id' : <uuid>,
  'first_name': <string>,
  'last_name': <string>,
  'age_verified' : false,
  'agent_access' : false,
  'allow_redirect: 1,
  'god_level':  0,
  'identified':  false,
  'transacted': false,
  'limited_to_estate': 1
  'sim_access' : 'PG'
}
 
== Response to request_rez_avatar ==
{
    'connect':True
    'rez_avatar/rez':<cap>
    'sim_ip': ip string
    'sim_port': int
    'region_x': int
    'region_y': int
    'region_id' : uuid
    'sim_access' : <PG/Mature>
    'seed_capability': uri string
Optional params for Second Life regions only:
    'src_can_see_mainland':<bool>,
    'src_estate_id':<int>
}
 
Failed request.
{
    'connect':False
    'redirect':False
    'resethome':False
    'message': string
}
 
Failed request.  Need to reset home location.
{
    'connect':False
    'redirect':False
    'resethome':True
    'message': string
}
 
Failed request.  Need to redirect to new location
{
    'connect':False
    'redirect':True
    'resethome':False
    'message': "You have been redirected to a telehub."
}
 
= rez_avatar/rez =
== Request: agentd -> simulator OR simulator a -> simulator b via derez_avatar ==
* For login, the agent domain then invokes rez_avatar on the simulator at the given region_url
* For teleport, the agent domain invokes derez_avatar on simulator a, which invokes rez_avatar on simulator b
{
    'circuit_code': <int>,
    'god_overide':  <bool>,
    'position': [x, y, z],
    'secure_session_id':  <uuid>,
    'session_id':  <uuid>,
    'inventory_host':  <uri string>, // not really here!
    'voice_password': <string> // what to do?
 
    // The following are only sent from simulator a -> simulator b via derez_avatar
    // Note: No assets are actually being sent through when going from SL -> non-SL regions
    'attachment_data': [ {'attachment_point':<int>, 'item_id':<uuid>, 'asset_id':<uuid> | 'asset_data':<binary>}...]
    'baked_texture_data': [ {'texture_id':<uuid>, 'asset_host_name':<host?????>}...]
    'texture_data': [ <uuid>...]
    'animations':[{'state':<uuid>, 'source':<uuid>, 'sequence':<int>}...]
}
 
== Response: simulator -> agentd ==
* The simulator then returns the actual region (in case it might be different from requested) and the seed cap.
{
    'look_at' : [f32, f32, f32]
    'position': [f32, f32, f32]
// Extra stuff
    'connect': <bool>
}
 
 
= rez_avatar/derez =
== Request: agentd -> simulator a ==
{
    'rez_avatar/rez': <url>
    'position':  [x, y, z]
}
Response: simulator a -> agentd
 
== Response: simulator -> agentd ==
  {
    'look_at' : [f32, f32, f32]
    'position': [f32, f32, f32]
// Extra stuff
    'connect': <bool>
}
 
 
= 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]]

Latest revision as of 14:39, 13 August 2008

This document has been deprecated. Please reference OGP Explained

Retrieved from "https://wiki.secondlife.com/w/index.php?title=SLGOGP_Teleport_Strawman&oldid=85836"