Content and Scripting: Same-origin versus multi-origin (cross-domain)

For simple HTTP requests, it does not matter whether your web pages come from the PyMOL server or from another server at your site. So if you are using PyMOL web applications that contain only simple HTTP requests, or if you do not need to get results back from PyMOL, then this same-origin (same-origin) versus multi-origin issue will not affect you.

However, if you need to get results back from PyMOL, typically via AJAX and API requests, then there are some limitations. For security reasons, most (if not all) modern browsers do not allow content from one server to interact with content from another server. For AJAX and API requests, this Same-Origin Policy (SOP) requires some attention.

If you want to develop more interactive PyMOL web applications that make use of results from PyMOL, this document will give you some background on how to do this using a central web server to serve the application.

Same-origin Policy

Web pages routinely contain links to resources (html documents, images, javascript, web-services, etc.) from the same server as well as links to resources from remote servers located anywhere on the web. While a single web page may even be composed of resources from various servers (sometimes called a mashup), JavaScript code from one server is not allowed to interact with resources from a different server. This SOP is inherent in most (if not all) modern browsers.

"Simply stated, the SOP states that JavaScript code running on a web page may not interact with any resource not originating from the same web site. The reason this security policy exists is to prevent malicious web coders from creating pages that steal web users' information or compromise their privacy. While very necessary, this policy also has the side effect of making web developers' lives difficult."

Same-origin PyMOL web applications

Since PyMOL and its web server are running on the user's desktop (localhost), a same-origin PyMOL web application would also be run on the desktop. This can be accomplished by writing a web application (html files and associated JavaScript) and placing them in a folder accessible by the PyMOL server. The first seven sample applications are implemented like this, residing in folders at $PYMOL_PATH/modules/web/examples/sample[0-7] There may be future PyMOL web applications delivered with new versions of PyMOL. Of course, you are free to write your own PyMOL web applications and store them on each user's machine, or perhaps on a central file server accessible to each user's machine.

Multi-origin PyMOL web applications

You can also develop PyMOL web applications that reside on a central server at your site. The application will be started by loading a web page from that server. The links, AJAX requests or API requests on that page will send requests to PyMOL running on the user's desktop (localhost). PyMOL will execute the command and send back a result. That result can be displayed in a FRAME, ignored, or used by the JavaScript in your application. However, for PyMOL web applications that come from another server, a JavaScript callback approach is necessary to conform to the SOP. Several sample applications illustrate this multi-origin approach.

Information flow and JavaScript callbacks

The basic function of an HTTP server is to listen for requests (GET/URL requests and POST/FORM requests) and send back HTML documents, images, etc. These documents are rendered by the browser, typically on a new page or tab or into an existing FRAME. Using AJAX, it is possible to process the "documents" using JavaScript, possibly causing the web page to change dynamically instead of refreshing completely. While the "A" in AJAX stands for asynchronous, it is possible to use the AJAX's underlying JavaScript XMLHTTPRequest synchronously, but only when the JavaScript issuing the XMLHTTPRequest originates from the same server to which the XMLHTTPRequest is being made (same-origin). A synchronous request means that the XMLHTTPRequest will not return until the server has answered the request. An asynchronous request means that the call to XMLHTTPRequest will send the request to the server and return immediately, before the request is answered. The document or information from the server can be processed by a callback function supplied to the XMLHTTPRequest or simply ignored. If you are using AJAX directly, or through JQuery or another JavaScript library, you should be familiar with the callback mechanism.

The PyMOL JavaScript API uses XMLHTTPRequest in either synchronous or ansynchronous mode. Synchronous mode can only be effectively used for same-origin web applications. Asynchronous mode with callbacks can be used for same-origin or multi-origin web applications.

Same-origin advantages

• No need to explicitly include host and port in URL links.
• PyMOL results can be handled synchronously in JavaScript using simpler programming techniques and avoiding callbacks.

Same-origin disadvantages

• Application content must be served up from the local machine (localhost).

Multi-origin advantages

• Allows development of PyMOL web applications maintained and run from one central server.
• No need to update files on users' machines when web application is updated.

Multi-origin disadvantages

• Must explicitly include the hostname (localhost) and port number in URL links.
• PyMOL results must be handled asynchronously in JavaScript using callbacks.
• The execution order of pending requests is random on certain browers (e.g. IE6).