i'm extending the RestStreamHandler.Handler(...) signature to actually

provide OSHttpRequest and OSHttpResponse to our REST handler. 

also, this adds proper RestPlugin.IsGod() checking against the X-OpenSim-Godkey
HTTP request header.

last, i added XML doc comments to RestPlugin.cs

11 files changed, 110 insertions, 24 deletions

diff --git a/OpenSim/ApplicationPlugins/Rest/Regions/GETRestRegionPlugin.cs b/OpenSim/ApplicationPlugins/Rest/Regions/GETRestRegionPlugin.cs
index 2b006e0..a319a8b 100644
--- a/OpenSim/ApplicationPlugins/Rest/Regions/GETRestRegionPlugin.cs
+++ b/OpenSim/ApplicationPlugins/Rest/Regions/GETRestRegionPlugin.cs
@@ -54,10 +54,16 @@ namespace OpenSim.ApplicationPlugins.Rest.Regions
     public partial class RestRegionPlugin : RestPlugin
     {
         #region GET methods
-        public string GetHandler(string request, string path, string param)
+        public string GetHandler(string request, string path, string param, 
+                                 OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
+            // foreach (string h in httpRequest.Headers.AllKeys) 
+            //     foreach (string v in httpRequest.Headers.GetValues(h))
+            //         m_log.DebugFormat("{0} IsGod: {1} -> {2}", MsgID, h, v);
+
+            MsgID = RequestID;
             m_log.DebugFormat("{0} GET path {1} param {2}", MsgID, path, param);
-            
+
             try
             {
                 // param empty: regions list
diff --git a/OpenSim/ApplicationPlugins/Rest/RestPlugin.cs b/OpenSim/ApplicationPlugins/Rest/RestPlugin.cs
index 8c370ed..4b8cdc1 100644
--- a/OpenSim/ApplicationPlugins/Rest/RestPlugin.cs
+++ b/OpenSim/ApplicationPlugins/Rest/RestPlugin.cs
@@ -240,9 +240,15 @@ namespace OpenSim.ApplicationPlugins.Rest
             }
         }
 
-
         private List<RestStreamHandler> _handlers = new List<RestStreamHandler>();
 
+        /// <summary>
+        /// Add a REST stream handler to the underlying HTTP server.
+        /// </summary>
+        /// <param name="httpMethod">GET/PUT/POST/DELETE or
+        /// similar</param>
+        /// <param name="path">URL prefix</param>
+        /// <param name="method">RestMethod handler doing the actual work</param>
         public virtual void AddRestStreamHandler(string httpMethod, string path, RestMethod method)
         {
             if (!IsEnabled) return;
@@ -259,20 +265,50 @@ namespace OpenSim.ApplicationPlugins.Rest
             m_log.DebugFormat("{0} Added REST handler {1} {2}", MsgID, httpMethod, path);
         }
 
-        public bool AddAgentHandler(string agentname, IHttpAgentHandler handler)
+        /// <summary>
+        /// Add a powerful Agent handler to the underlying HTTP
+        /// server.
+        /// </summary>
+        /// <param name="agentName">name of agent handler</param>
+        /// <param name="handler">agent handler method</param>
+        /// <returns>true when the plugin is disabled or the agent
+        /// handler could not be added..</returns>
+        public bool AddAgentHandler(string agentName, IHttpAgentHandler handler)
         {
             if (!IsEnabled) return false;
-            return _httpd.AddAgentHandler(agentname, handler);
+            return _httpd.AddAgentHandler(agentName, handler);
         }
 
+        /// <summary>
+        /// Check whether the HTTP request came from god; that is, is
+        /// the god_key as configured in the config section supplied
+        /// via X-OpenSim-Godkey?
+        /// </summary>
+        /// <param name="request">HTTP request header</param>
+        /// <returns>true when the HTTP request came from god.</returns>
         protected bool IsGod(OSHttpRequest request)
         {
-            string[] keys = request.Headers.GetValues("x-opensim-godkey");
+            string[] keys = request.Headers.GetValues("X-OpenSim-Godkey");
             if (null == keys) return false;
+
             // we take the last key supplied
             return keys[keys.Length-1] == _godkey;
         }
 
+        /// <summary>
+        /// Checks wether the X-OpenSim-Password value provided in the
+        /// HTTP header is indeed the password on file for the avatar
+        /// specified by the UUID
+        /// </summary>
+        protected bool IsVerifiedUser(OSHttpRequest request, LLUUID uuid)
+        {
+            // XXX under construction
+            return false;
+        }
+
+        /// <summary>
+        /// Clean up and remove all handlers that were added earlier.
+        /// </summary>
         public virtual void Close()
         {
             foreach (RestStreamHandler h in _handlers)
@@ -282,12 +318,26 @@ namespace OpenSim.ApplicationPlugins.Rest
             _handlers = null;
         }
 
+        /// <summary>
+        /// Return a failure message.
+        /// </summary>
+        /// <param name="method">origin of the failure message</param>
+        /// <param name="message>failure message</param>
+        /// <remarks>This should probably set a return code as
+        /// well. (?)</remarks> 
         protected string Failure(string method, string message)
         {
             m_log.ErrorFormat("{0} {1} failed: {2}", MsgID, method, message);
             return String.Format("<error>{0}</error>", message);
         }
 
+        /// <summary>
+        /// Return a failure message.
+        /// </summary>
+        /// <param name="method">origin of the failure message</param>
+        /// <param name="e">exception causing the failure message</param>
+        /// <remarks>This should probably set a return code as
+        /// well. (?)</remarks> 
         public string Failure(string method, Exception e)
         {
             m_log.DebugFormat("{0} {1} failed: {2}", MsgID, method, e.ToString());
diff --git a/OpenSim/Framework/Communications/CAPSService.cs b/OpenSim/Framework/Communications/CAPSService.cs
index caf96ff..07bea9d 100644
--- a/OpenSim/Framework/Communications/CAPSService.cs
+++ b/OpenSim/Framework/Communications/CAPSService.cs
@@ -45,7 +45,8 @@ namespace OpenSim.Framework.Communications
             m_server.AddStreamHandler(new RestStreamHandler("POST", path, restMethod));
         }
 
-        public string CapsRequest(string request, string path, string param)
+        public string CapsRequest(string request, string path, string param, 
+                                  OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             System.Console.WriteLine("new caps request " + request + " from path " + path);
             return String.Empty;
diff --git a/OpenSim/Framework/Communications/Capabilities/Caps.cs b/OpenSim/Framework/Communications/Capabilities/Caps.cs
index 9725c94..8d8f945 100644
--- a/OpenSim/Framework/Communications/Capabilities/Caps.cs
+++ b/OpenSim/Framework/Communications/Capabilities/Caps.cs
@@ -208,8 +208,11 @@ namespace OpenSim.Framework.Communications.Capabilities
         /// <param name="request"></param>
         /// <param name="path"></param>
         /// <param name="param"></param>
+        /// <param name="httpRequest">HTTP request header object</param>
+        /// <param name="httpResponse">HTTP response header object</param>
         /// <returns></returns>
-        public string CapsRequest(string request, string path, string param)
+        public string CapsRequest(string request, string path, string param, 
+                                  OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             m_log.Debug("[CAPS]: Seed Caps Request in region: " + m_regionName);
             //Console.WriteLine("caps request " + request);
@@ -503,8 +506,11 @@ namespace OpenSim.Framework.Communications.Capabilities
         /// <param name="request"></param>
         /// <param name="path"></param>
         /// <param name="param"></param>
+        /// <param name="httpRequest">HTTP request header object</param>
+        /// <param name="httpResponse">HTTP response header object</param>
         /// <returns></returns>
-        public string ScriptTaskInventory(string request, string path, string param)
+        public string ScriptTaskInventory(string request, string path, string param, 
+                                          OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             try
             {
@@ -558,7 +564,8 @@ namespace OpenSim.Framework.Communications.Capabilities
         /// <param name="path"></param>
         /// <param name="param"></param>
         /// <returns></returns>
-        public string NoteCardAgentInventory(string request, string path, string param)
+        public string NoteCardAgentInventory(string request, string path, string param, 
+                                             OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             m_log.Debug("[CAPS]: NoteCardAgentInventory Request in region: " + m_regionName);
             //libsecondlife.StructuredData.LLSDMap hash = (libsecondlife.StructuredData.LLSDMap)libsecondlife.StructuredData.LLSDParser.DeserializeBinary(Helpers.StringToField(request));
diff --git a/OpenSim/Framework/Servers/RestMethod.cs b/OpenSim/Framework/Servers/RestMethod.cs
index 1a31ef1..6bd34f5 100644
--- a/OpenSim/Framework/Servers/RestMethod.cs
+++ b/OpenSim/Framework/Servers/RestMethod.cs
@@ -27,5 +27,6 @@
 
 namespace OpenSim.Framework.Servers
 {
-    public delegate string RestMethod(string request, string path, string param);
+    public delegate string RestMethod(string request, string path, string param, 
+                                      OSHttpRequest httpRequest, OSHttpResponse httpResponse);
 }
diff --git a/OpenSim/Framework/Servers/RestStreamHandler.cs b/OpenSim/Framework/Servers/RestStreamHandler.cs
index 301b0a9..44c9dfc 100644
--- a/OpenSim/Framework/Servers/RestStreamHandler.cs
+++ b/OpenSim/Framework/Servers/RestStreamHandler.cs
@@ -49,7 +49,7 @@ namespace OpenSim.Framework.Servers
             streamReader.Close();
 
             string param = GetParam(path);
-            string responseString = m_restMethod(requestBody, path, param);
+            string responseString = m_restMethod(requestBody, path, param, httpRequest, httpResponse);
 
             return Encoding.UTF8.GetBytes(responseString);
         }
diff --git a/OpenSim/Grid/GridServer/GridManager.cs b/OpenSim/Grid/GridServer/GridManager.cs
index 83b5319..5a6a328 100644
--- a/OpenSim/Grid/GridServer/GridManager.cs
+++ b/OpenSim/Grid/GridServer/GridManager.cs
@@ -877,10 +877,13 @@ namespace OpenSim.Grid.GridServer
         /// <param name="request"></param>
         /// <param name="path"></param>
         /// <param name="param"></param>
+        /// <param name="httpRequest">HTTP request header object</param>
+        /// <param name="httpResponse">HTTP response header object</param>
         /// <returns></returns>
-        public string RestGetRegionMethod(string request, string path, string param)
+        public string RestGetRegionMethod(string request, string path, string param, 
+                                          OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
-            return RestGetSimMethod(String.Empty, "/sims/", param);
+            return RestGetSimMethod(String.Empty, "/sims/", param, httpRequest, httpResponse);
         }
 
         /// <summary>
@@ -889,10 +892,13 @@ namespace OpenSim.Grid.GridServer
         /// <param name="request"></param>
         /// <param name="path"></param>
         /// <param name="param"></param>
+        /// <param name="httpRequest">HTTP request header object</param>
+        /// <param name="httpResponse">HTTP response header object</param>
         /// <returns></returns>
-        public string RestSetRegionMethod(string request, string path, string param)
+        public string RestSetRegionMethod(string request, string path, string param, 
+                                          OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
-            return RestSetSimMethod(String.Empty, "/sims/", param);
+            return RestSetSimMethod(String.Empty, "/sims/", param, httpRequest, httpResponse);
         }
 
         /// <summary>
@@ -901,8 +907,11 @@ namespace OpenSim.Grid.GridServer
         /// <param name="request"></param>
         /// <param name="path"></param>
         /// <param name="param">A string representing the sim's UUID</param>
+        /// <param name="httpRequest">HTTP request header object</param>
+        /// <param name="httpResponse">HTTP response header object</param>
         /// <returns>Information about the sim in XML</returns>
-        public string RestGetSimMethod(string request, string path, string param)
+        public string RestGetSimMethod(string request, string path, string param, 
+                                       OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             string respstring = String.Empty;
 
@@ -946,8 +955,11 @@ namespace OpenSim.Grid.GridServer
         /// <param name="request"></param>
         /// <param name="path"></param>
         /// <param name="param"></param>
+        /// <param name="httpRequest">HTTP request header object</param>
+        /// <param name="httpResponse">HTTP response header object</param>
         /// <returns>"OK" or an error</returns>
-        public string RestSetSimMethod(string request, string path, string param)
+        public string RestSetSimMethod(string request, string path, string param, 
+                                       OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             Console.WriteLine("Processing region update via REST method");
             RegionProfileData theSim;
diff --git a/OpenSim/Grid/UserServer/UserManager.cs b/OpenSim/Grid/UserServer/UserManager.cs
index 1cf2a48..706f461 100644
--- a/OpenSim/Grid/UserServer/UserManager.cs
+++ b/OpenSim/Grid/UserServer/UserManager.cs
@@ -35,6 +35,7 @@ using log4net;
 using Nwc.XmlRpc;
 using OpenSim.Framework;
 using OpenSim.Framework.Communications;
+using OpenSim.Framework.Servers;
 
 namespace OpenSim.Grid.UserServer
 {
@@ -53,8 +54,11 @@ namespace OpenSim.Grid.UserServer
         /// <param name="request">The request</param>
         /// <param name="path">The path (eg /bork/narf/test)</param>
         /// <param name="param">Parameters sent</param>
+        /// <param name="httpRequest">HTTP request header object</param>
+        /// <param name="httpResponse">HTTP response header object</param>
         /// <returns>Success "OK" else error</returns>
-        public string RestDeleteUserSessionMethod(string request, string path, string param)
+        public string RestDeleteUserSessionMethod(string request, string path, string param, 
+                                                  OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             // TODO! Important!
 
diff --git a/OpenSim/Region/DataSnapshot/DataRequestHandler.cs b/OpenSim/Region/DataSnapshot/DataRequestHandler.cs
index abf2c1a..6ecae06 100644
--- a/OpenSim/Region/DataSnapshot/DataRequestHandler.cs
+++ b/OpenSim/Region/DataSnapshot/DataRequestHandler.cs
@@ -72,7 +72,8 @@ namespace OpenSim.Region.DataSnapshot
                 new RestStreamHandler("POST", capsBase + m_discoveryPath, OnDiscoveryAttempt));
         }
 
-        public string OnDiscoveryAttempt(string request, string path, string param)
+        public string OnDiscoveryAttempt(string request, string path, string param, 
+                                         OSHttpRequest httpRequest, OSHttpResponse httpResponse)
         {
             //Very static for now, flexible enough to add new formats
             LLSDDiscoveryResponse llsd_response = new LLSDDiscoveryResponse();
diff --git a/OpenSim/Region/Environment/Modules/Avatar/Voice/AsterixVoice/AsteriskVoiceModule.cs b/OpenSim/Region/Environment/Modules/Avatar/Voice/AsterixVoice/AsteriskVoiceModule.cs
index f8651a3..2e8a8da 100644
--- a/OpenSim/Region/Environment/Modules/Avatar/Voice/AsterixVoice/AsteriskVoiceModule.cs
+++ b/OpenSim/Region/Environment/Modules/Avatar/Voice/AsterixVoice/AsteriskVoiceModule.cs
@@ -131,14 +131,16 @@ namespace OpenSim.Region.Environment.Modules.Avatar.Voice.AsterixVoice
             string capsBase = "/CAPS/" + caps.CapsObjectPath;
             caps.RegisterHandler("ParcelVoiceInfoRequest",
                                  new RestStreamHandler("POST", capsBase + m_parcelVoiceInfoRequestPath,
-                                                       delegate(string request, string path, string param)
+                                                       delegate(string request, string path, string param, 
+                                                                OSHttpRequest httpRequest, OSHttpResponse httpResponse)
                                                            {
                                                                return ParcelVoiceInfoRequest(request, path, param,
                                                                                              agentID, caps);
                                                            }));
             caps.RegisterHandler("ProvisionVoiceAccountRequest",
                                  new RestStreamHandler("POST", capsBase + m_provisionVoiceAccountRequestPath,
-                                                       delegate(string request, string path, string param)
+                                                       delegate(string request, string path, string param, 
+                                                                OSHttpRequest httpRequest, OSHttpResponse httpResponse)
                                                            {
                                                                return ProvisionVoiceAccountRequest(request, path, param,
                                                                                                    agentID, caps);
diff --git a/OpenSim/Region/Environment/Modules/Avatar/Voice/SIPVoice/SIPVoiceModule.cs b/OpenSim/Region/Environment/Modules/Avatar/Voice/SIPVoice/SIPVoiceModule.cs
index feb716e..77f761f 100644
--- a/OpenSim/Region/Environment/Modules/Avatar/Voice/SIPVoice/SIPVoiceModule.cs
+++ b/OpenSim/Region/Environment/Modules/Avatar/Voice/SIPVoice/SIPVoiceModule.cs
@@ -104,14 +104,16 @@ namespace OpenSim.Region.Environment.Modules.Avatar.Voice.SIPVoice
             string capsBase = "/CAPS/" + caps.CapsObjectPath;
             caps.RegisterHandler("ParcelVoiceInfoRequest",
                                  new RestStreamHandler("POST", capsBase + m_parcelVoiceInfoRequestPath,
-                                                       delegate(string request, string path, string param)
+                                                       delegate(string request, string path, string param, 
+                                                                OSHttpRequest httpRequest, OSHttpResponse httpResponse)
                                                            {
                                                                return ParcelVoiceInfoRequest(request, path, param,
                                                                                              agentID, caps);
                                                            }));
             caps.RegisterHandler("ProvisionVoiceAccountRequest",
                                  new RestStreamHandler("POST", capsBase + m_provisionVoiceAccountRequestPath,
-                                                       delegate(string request, string path, string param)
+                                                       delegate(string request, string path, string param, 
+                                                                OSHttpRequest httpRequest, OSHttpResponse httpResponse)
                                                            {
                                                                return ProvisionVoiceAccountRequest(request, path, param,
                                                                                                    agentID, caps);