services/request.esp

   1 <%
   2
   3 /*
   4  * Copyright:
   5  *   (C) 2006 by Derrell Lipman
   6  *       All rights reserved
   7  *
   8  * License:
   9  *   LGPL 2.1: http://creativecommons.org/licenses/LGPL/2.1/
  10  */
  11
  12 /*
  13  * This is a simple JSON-RPC server.
  14  */
  15
  16 /* Bring in the json format/parse functions */
  17 jsonrpc_include("json.esp");
  18
  19 /* Bring in the date class */
  20 jsonrpc_include("jsondate.esp");
  21
  22 /* Load the authentication script */
  23 jsonrpc_include("json_auth.esp");
  24
  25
  26 /* bring the string functions into the global frame */
  27 string_init(global);
  28
  29 /* Bring the system functions into the global frame */
  30 sys_init(global);
  31
  32 /* Bring the session functions into the global frame */
  33 system_session(global);
  34
  35
  36 function printf()
  37 {
  38         print(vsprintf(arguments));
  39 }
  40
  41
  42 /*
  43  * All of our manipulation of JSON RPC methods will be through this object.
  44  * Each class of methods will assign to here, and all of the constants will
  45  * also be in this object.
  46  */
  47 jsonrpc = new Object();
  48 jsonrpc.Constant = new Object();
  49 jsonrpc.Constant.ErrorOrigin = new Object(); /* error origins */
  50 jsonrpc.Constant.ServerError = new Object(); /* server-generated error codes */
  51 jsonrpc.method = new Object();       /* methods available in requested class */
  52
  53 /*
  54  * ScriptTransport constants
  55  */
  56 jsonrpc.Constant.ScriptTransport = new Object();
  57 jsonrpc.Constant.ScriptTransport.NotInUse        = -1;
  58
  59
  60 /*
  61  * JSON-RPC error origin constants
  62  */
  63 jsonrpc.Constant.ErrorOrigin.Server              = 1;
  64 jsonrpc.Constant.ErrorOrigin.Application         = 2;
  65 jsonrpc.Constant.ErrorOrigin.Transport           = 3;
  66 jsonrpc.Constant.ErrorOrigin.Client              = 4;
  67
  68
  69
  70 /*
  71  * JSON-RPC server-generated error code constants
  72  */
  73
  74 /**
  75  * Error code, value 0: Unknown Error
  76  *
  77  * The default error code, used only when no specific error code is passed to
  78  * the JsonRpcError constructor.  This code should generally not be used.
  79  */
  80 jsonrpc.Constant.ServerError.Unknown               = 0;
  81
  82 /**
  83  * Error code, value 1: Illegal Service
  84  *
  85  * The service name contains illegal characters or is otherwise deemed
  86  * unacceptable to the JSON-RPC server.
  87  */
  88 jsonrpc.Constant.ServerError.IllegalService        = 1;
  89
  90 /**
  91  * Error code, value 2: Service Not Found
  92  *
  93  * The requested service does not exist at the JSON-RPC server.
  94  */
  95 jsonrpc.Constant.ServerError.ServiceNotFound       = 2;
  96
  97 /**
  98  * Error code, value 3: Class Not Found
  99  *
 100  * If the JSON-RPC server divides service methods into subsets (classes), this
 101  * indicates that the specified class was not found.  This is slightly more
 102  * detailed than "Method Not Found", but that error would always also be legal
 103  * (and true) whenever this one is returned. (Not used in this implementation)
 104  */
 105 jsonrpc.Constant.ServerError.ClassNotFound         = 3;
 106
 107 /**
 108  * Error code, value 4: Method Not Found
 109  *
 110  * The method specified in the request is not found in the requested service.
 111  */
 112 jsonrpc.Constant.ServerError.MethodNotFound        = 4;
 113
 114 /*
 115  * Error code, value 5: Parameter Mismatch
 116  *
 117  * If a method discovers that the parameters (arguments) provided to it do not
 118  * match the requisite types for the method's parameters, it should return
 119  * this error code to indicate so to the caller.
 120  *
 121  * This error is also used to indicate an illegal parameter value, in server
 122  * scripts.
 123  */
 124 jsonrpc.Constant.ServerError.ParameterMismatch     = 5;
 125
 126 /**
 127  * Error code, value 6: Permission Denied
 128  *
 129  * A JSON-RPC service provider can require authentication, and that
 130  * authentication can be implemented such the method takes authentication
 131  * parameters, or such that a method or class of methods requires prior
 132  * authentication.  If the caller has not properly authenticated to use the
 133  * requested method, this error code is returned.
 134  */
 135 jsonrpc.Constant.ServerError.PermissionDenied      = 6;
 136
 137 /*** Errors generated by this server which are not qooxdoo-standard ***/
 138
 139 /*
 140  * Error code, value 1000: Unexpected Output
 141  *
 142  * The called method illegally generated output to the browser, which would
 143  * have preceeded the JSON-RPC data.
 144  */
 145 jsonrpc.Constant.ServerError.UnexpectedOutput      = 1000;
 146
 147 /*
 148  * Error code, value 1001: Resource Error
 149  *
 150  * Too many resources were requested, a system limitation on the total number
 151  * of resources has been reached, or a resource or resource id was misused.
 152  */
 153 jsonrpc.Constant.ServerError.ResourceError         = 1001;
 154
 155 /*
 156  * Error code, value 1002: Not Logged In
 157  *
 158  * The user has logged out and must re-authenticate, or this is a brand new
 159  * session and the user must log in.
 160  *
 161  */
 162 jsonrpc.Constant.ServerError.NotLoggedIn           = 1002;
 163
 164 /*
 165  * Error code, value 1003: Session Expired
 166  *
 167  * The session has expired and the user must re-authenticate.
 168  *
 169  */
 170 jsonrpc.Constant.ServerError.SessionExpired        = 1003;
 171
 172 /*
 173  * Error code, value 1004: Login Failed
 174  *
 175  * An attempt to log in failed.
 176  *
 177  */
 178 jsonrpc.Constant.ServerError.LoginFailed           = 1004;
 179
 180
 181
 182
 183
 184 function sendReply(reply, scriptTransportId)
 185 {
 186     /* If not using ScriptTransport... */
 187     if (scriptTransportId == jsonrpc.Constant.ScriptTransport.NotInUse)
 188     {
 189         /* ... then just output the reply. */
 190         write(reply);
 191     }
 192     else
 193     {
 194         /* Otherwise, we need to add a call to a qooxdoo-specific function */
 195         reply =
 196             "qx.io.remote.ScriptTransport._requestFinished(" +
 197             scriptTransportId + ", " + reply +
 198             ");";
 199         write(reply);
 200     }
 201 }
 202
 203
 204 function _jsonValidRequest(req)
 205 {
 206     if (req == undefined)
 207     {
 208         return false;
 209     }
 210
 211     if (typeof(req) != "object")
 212     {
 213         return false;
 214     }
 215
 216     if (req["id"] == undefined)
 217     {
 218         return false;
 219     }
 220
 221     if (req["service"] == undefined)
 222     {
 223         return false;
 224     }
 225
 226     if (req["method"] == undefined)
 227     {
 228         return false;
 229     }
 230
 231     if (req["params"] == undefined)
 232     {
 233         return false;
 234     }
 235
 236     return true;
 237 }
 238 jsonrpc.validRequest = _jsonValidRequest;
 239 _jsonValidRequest = null;
 240
 241 /*
 242  * class JsonRpcError
 243  *
 244  * This class allows service methods to easily provide error information for
 245  * return via JSON-RPC.
 246  */
 247 function _JsonRpcError_create(origin, code, message)
 248 {
 249     var o = new Object();
 250
 251     o.data = new Object();
 252     o.data.origin = origin;
 253     o.data.code = code;
 254     o.data.message = message;
 255     o.scriptTransportId = jsonrpc.Constant.ScriptTransport.NotInUse;
 256     o.__type = "_JsonRpcError";
 257
 258     function _origin(origin)
 259     {
 260         this.data.origin = origin;
 261     }
 262     o.setOrigin = _origin;
 263
 264     function _setError(code, message)
 265     {
 266         this.data.code = code;
 267         this.data.message = message;
 268     }
 269     o.setError = _setError;
 270
 271     function _setId(id)
 272     {
 273         this.id = id;
 274     }
 275     o.setId = _setId;
 276
 277     function _setScriptTransportId(id)
 278     {
 279         this.scriptTransportId = id;
 280     }
 281     o.setScriptTransportId = _setScriptTransportId;
 282
 283     function _setInfo(info)
 284     {
 285         // Add the info field only if info is actually provided.
 286         // This is an extension to qooxdoo's normal Error return value.
 287         this.data.info = info;
 288     }
 289     o.setInfo = _setInfo;
 290
 291     function _Send()
 292     {
 293         var error = this;
 294         var id = this.id;
 295         var ret = new Object();
 296         ret.error = this.data;
 297         ret.id = this.id;
 298         sendReply(Json.encode(ret), this.scriptTransportId);
 299     }
 300     o.Send = _Send;
 301
 302     return o;
 303 }
 304
 305 jsonrpc.createError = _JsonRpcError_create;
 306 _JsonRpcError_create = null;
 307
 308 /*
 309  * 'input' is the user-provided json-encoded request
 310  * 'jsonInput' is that request, decoded into its object form
 311  */
 312 var input;
 313 var jsonInput = null;
 314
 315 /* Allocate a generic error object */
 316 error = jsonrpc.createError(jsonrpc.Constant.ErrorOrigin.Server,
 317                             jsonrpc.Constant.ServerError.Unknown,
 318                             "Unknown error");
 319
 320 /* Assume (default) we're not using ScriptTransport */
 321 scriptTransportId = jsonrpc.Constant.ScriptTransport.NotInUse;
 322
 323 /* What type of request did we receive? */
 324 if (request["REQUEST_METHOD"] == "POST" &&
 325     request["CONTENT_TYPE"] == "application/json")
 326 {
 327     /* We found literal POSTed json-rpc data (we hope) */
 328     input = request["POST_DATA"];
 329     jsonInput = Json.decode(input);
 330 }
 331 else if (request["REQUEST_METHOD"] == "GET" &&
 332          form["_ScriptTransport_id"] != undefined &&
 333          form["_ScriptTransport_id"] !=
 334            jsonrpc.Constant.ScriptTransport.NotInUse &&
 335          form["_ScriptTransport_data"] != undefined)
 336 {
 337     /* We have what looks like a valid ScriptTransport request */
 338     scriptTransportId = form["_ScriptTransport_id"];
 339     error.setScriptTransportId(scriptTransportId);
 340     input = form["_ScriptTransport_data"];
 341     jsonInput = Json.decode(input);
 342 }
 343
 344 /* Ensure that this was a JSON-RPC service request */
 345 if (! jsonrpc.validRequest(jsonInput))
 346 {
 347     /*
 348      * This request was not issued with JSON-RPC so echo the error rather than
 349      * issuing a JsonRpcError response.
 350      */
 351     write("JSON-RPC request expected; service, method or params missing<br>");
 352     return;
 353 }
 354
 355 /*
 356  * Ok, it looks like JSON-RPC, so we'll return an Error object if we encounter
 357  * errors from here on out.
 358  */
 359 error.setId(jsonInput.id);
 360
 361 /* Service and method names may contain these characters */
 362 var nameChars =
 363     "_abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890";
 364
 365 /* The first letter of service and method names must be a letter */
 366 var nameFirstLetter =
 367     "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
 368
 369 /*
 370  * Ensure the method name is kosher.  A method name should be:
 371  *
 372  *   - first character is in [a-zA-Z]
 373  *   - other characters are in [_a-zA-Z0-9]
 374  */
 375
 376 /* First check for legal characters */
 377 if (strspn(jsonInput.method, nameChars) != strlen(jsonInput.method))
 378 {
 379     /* There's some illegal character in the service name */
 380     error.setError(jsonrpc.Constant.ServerError.MethodNotFound,
 381                    "Illegal character found in method name.");
 382     error.Send();
 383     return;
 384 }
 385
 386 /* Now ensure that it begins with a letter */
 387 if (strspn(substr(jsonInput.method, 0, 1), nameFirstLetter) != 1)
 388 {
 389     error.setError(jsonrpc.Constant.ServerError.MethodNotFound,
 390                    "The method name does not begin with a letter");
 391     error.Send();
 392     return;
 393 }
 394
 395 /*
 396  * Ensure the requested service name is kosher.  A service name should be:
 397  *
 398  *   - a dot-separated sequences of strings; no adjacent dots
 399  *   - first character of each string is in [a-zA-Z]
 400  *   - other characters are in [_a-zA-Z0-9]
 401  */
 402
 403 /* First check for legal characters */
 404 if (strspn(jsonInput.service, "." + nameChars) != strlen(jsonInput.service))
 405 {
 406     /* There's some illegal character in the service name */
 407     error.setError(jsonrpc.Constant.ServerError.IllegalService,
 408                    "Illegal character found in service name.");
 409     error.Send();
 410     return;
 411 }
 412
 413 /*
 414  * Now ensure there are no double dots.
 415  *
 416  * Frustration with ejs.  Result must be NULL, but we can't use the ===
 417  * operator: strstr() === null so we have to use typeof.  If the result isn't
 418  * null, then it'll be a number and therefore not type "pointer".
 419  */
 420 if (typeof(strstr(jsonInput.service, "..")) != "pointer")
 421 {
 422     error.setError(jsonrpc.Constant.ServerError.IllegalService,
 423                    "Illegal use of two consecutive dots in service name");
 424     error.Send();
 425     return;
 426 }
 427
 428 /* Explode the service name into its dot-separated parts */
 429 var serviceComponents = split(".", jsonInput.service);
 430
 431 /* Ensure that each component begins with a letter */
 432 for (var i = 0; i < serviceComponents.length; i++)
 433 {
 434     if (strspn(substr(serviceComponents[i], 0, 1), nameFirstLetter) != 1)
 435     {
 436         error.setError(jsonrpc.Constant.ServerError.IllegalService,
 437                        "A service name component does not begin with a letter");
 438         error.Send();
 439         return;
 440     }
 441 }
 442
 443 /*
 444  * Now replace all dots with slashes so we can locate the service script.  We
 445  * also retain the split components of the path, as the class name of the
 446  * service is the last component of the path.
 447  */
 448 var servicePath = join("/", serviceComponents) + ".esp";
 449
 450 /* Load the requested class */
 451 if (jsonrpc_include(servicePath))
 452 {
 453     /* Couldn't find the requested service */
 454     error.setError(jsonrpc.Constant.ServerError.ServiceNotFound,
 455                    "Service class `" + servicePath + "` does not exist.");
 456     error.Send();
 457     return;
 458 }
 459
 460 /*
 461  * Find the requested method.
 462  *
 463  * What we really want to do here, and could do in any reasonable language,
 464  * is:
 465  *
 466  *   method = jsonrpc.method[jsonInput.method];
 467  *   if (method && typeof(method) == "function") ...
 468  *
 469  * The following completely unreasonable sequence of commands is because:
 470  *
 471  *  (a) ejs evaluates all OR'ed expressions even if an early one is false, and
 472  *      barfs on the typeof(method) call if method is undefined
 473  *
 474  *  (b) ejs does not allow comparing against the string "function"!!!  What
 475  *      the hell is special about that particular string???
 476  *
 477  * E-gad.  What a mess.
 478  */
 479 var method = jsonrpc.method[jsonInput.method];
 480 var valid = (method != undefined);
 481 if (valid)
 482 {
 483     var type = typeof(method);
 484     if (substr(type, 0, 1) != 'f' || substr(type, 1) != "unction")
 485     {
 486         valid = false;
 487     }
 488 }
 489
 490 if (! valid)
 491 {
 492     error.setError(jsonrpc.Constant.ServerError.MethodNotFound,
 493                    "Method `" + jsonInput.method + "` not found.");
 494     error.Send();
 495     return;
 496 }
 497
 498 /*
 499  * Ensure the logged-in user is allowed to issue the requested method.  We
 500  * provide the scriptTransportId as one of the determining factors because
 501  * accepting requests via ScriptTransport is dangerous.  Only methods which
 502  * one might allow when unauthenticated should be allowed via ScriptTransport
 503  * as it is easy for a rogue site to trick a user into bypassing
 504  * authentication.
 505  */
 506 if (! json_authenticate(serviceComponents,
 507                         jsonInput.method,
 508                         scriptTransportId,
 509                         error))
 510 {
 511     error.Send();
 512     return;
 513 }
 514
 515 /* Most errors from here on out will be Application-generated */
 516 error.setOrigin(jsonrpc.Constant.ErrorOrigin.Application);
 517
 518 /* Call the requested method passing it the provided params */
 519 var retval = method(jsonInput.params, error);
 520
 521 /* See if the result of the function was actually an error object */
 522 if (retval["__type"] == "_JsonRpcError")
 523 {
 524     /* Yup, it was.  Return the error */
 525     retval.Send();
 526     return;
 527 }
 528
 529 /* Give 'em what they came for! */
 530 var ret = new Object();
 531 ret.result = retval;
 532 ret.id = jsonInput.id;
 533 sendReply(Json.encode(ret), scriptTransportId);
 534
 535 /*
 536  * Local Variables:
 537  * mode: c
 538  * End:
 539  */
 540 %>