ServerJS/Modules/SecurableModules: Difference between revisions

From MozillaWiki
Jump to navigation Jump to search
(moved to CommonJS wiki)
 
(28 intermediate revisions by 8 users not shown)
Line 1: Line 1:
This specification addresses how modules should be written in order to be interoperable among a class of module systems that can be both client and server side, secure or insecure, implemented today or supported by future systems with syntax extensions.  These modules are offered privacy of their top scope, facility for importing singleton objects from other modules, and exporting their own API.
This specification has moved to the [http://wiki.commonjs.org/wiki/Modules/1.0 CommonJS wiki].
 
# A module receives a "require" function.
## The "require" function accepts a module identifier.
## "require" returns an object containing the exported API of the foreign module.
## If there is a dependency cycle, the foreign module may not have finished executing at the time it is required by one of its transitive dependencies; in this case, the object returned by "require" must contain at least the exports that the foreign module has prepared before the call to require that led to the current module's execution.
## If the requested module cannot be returned, "require" must throw an error.
# A module receives an "exports" object that it may add its exported API to as it executes.
# Interoperable modules must use the exports object as the only means of exporting, since an implementation may prevent tampering with any other object shared among modules.
 
=== Module Identifiers ===
 
# A module identifier is a String of "terms" delimited by forward slashes.
# A term must be a camelCase identifier, ".", or "..".
# The extension of the file corresponding to a module identifier must be inferred by loaders.
# Module identifiers may be "relative" or "absolute".  A module identifier is "relative" if the first term is "." or "..".
# Absolute identifiers are resolved off the conceptual name space root.  A loader may check multiple roots in a consistent order, like a PATH.
# Relative identifiers are resolved relative to the file in which "require" is called.
 
 
=== Security ===
 
To be interoperable with secure environments, a module must satisfy the following additional constraints:
 
# A module must not have any free variables apart from primordials ("Object", "Array", etc.), "require", and "exports".
# A module must not tamper with (assign to, assign to members of, delete, or otherwise mutate) the transitive primordials, the "require" object, or any object returned by "require".
 
=== Unspecified ===
 
This specification leaves the following important points of interoperability unspecified:
 
# Whether relative module identifiers are supported.
# Whether a PATH is supported by the module loader for resolving module identifiers.
 
 
== Loaders ==
 
A prototype for a client-side module loader that supports modules that conform to this specification using PATH relative URL's or module relative URL's without making security guarantees is partially complete in the  [[http://code.google.com/p/chironjs/source/browse/branch/safe/src/modules.js "safe" branch of modules.js]].
 
pmuellr posted a sample loader http://wiki.github.com/pmuellr/modjewel
 
== Sample Code ==
 
// ==================================================================
// source code
//
// math.js
//
exports.add = function() {
  var sum = arguments[0];
  for (var i=1; i<arguments.length; i++) {
    sum += arguments[i];
  }
  return sum;
};
//
// increment.js
//
var add = require('math').add;
exports.increment = function(val) {
  return add(val, 1);
};
//
// program.js
//
var inc = require('increment').increment;
var a = 1;
inc(a); // 2
// ==================================================================
// browser code in development
// locked into on of these options
//
//  1) using a special XHR synchronous script loader and   
//      a) seeing poor error messages with strange line numbering
//        not corresponding with source code line numbering or
//      b) using a JavaScript interpreter written in JavaScript
//        to execute the code retrieved by the XHR. Line numbers
//        would then correspond to source code line numbers.
//        (Seems like an extreme solution.)
//
//  2) edit-compile-load-test cycle using the code below. Also
//    strange numbering in error messages that does not match
//    source files. Tools could make compile automatic but that
//    means tools are required and that is not the case in
//    the current browser scripting world.
// ==================================================================
// compiled for production in browser
//
// library.js
//
var require = (function() {
 
  // memoized export objects
  var exportsObjects = {}
  // don't want outsider redefining "require" and don't want
  // to use arguments.callee so name the function here.
  var require = function(name) {
    if (exportsObject.hasOwnProperty(name)) {
      return exportsObject[name];
    }
    var exports = {};
    // memoize before executing module for cyclic dependencies
    exportsObject[name] = exports;
    modules[name](require, exports);
    return exports;
  };
 
  return require;
})();
var run = function(name) {
  require(name); // doesn't return exports
};
var modules = {};
//
// compiledModules.js
//
modules["math"] = function(require, exports) {
  exports.add = function() {
    var sum = arguments[0];
    for (var i=1; i<arguments.length; i++) {
      sum += arguments[i];
    }
    return sum;
  };
};
modules["increment"] = function(require, exports) {
  var add = require('math').add;
  exports.increment = function(val) {
    add(val, 1);
  };
};
modules["program"] = function(require, exports) {
  var inc = require('increment').increment;
  var a = 1;
  inc(a); // 2
};
//
// html in document head
//
<script src="library.js" type="text/javascript"></script>
<script src="compiledModules.js" type="text/javascript"></script>
<script type="text/javascript">
  // You might not use use the window.onload property
  // but rather addEventListener/attachEvent.
  window.onload = function() {
    run("program");
  };
</script>
 
== Browser Sharable as Written ==
 
It would be handy to be able to share modules "as written" with the browser by loading the source code with html script tags. I think the following source code allows this feature. The first and last lines of the modules would be idiomatic boilerplate for modules to be shared on both the client and server.
 
There are several ways to write the first and last lines. Some of them are shorter than below but give up some of the protection of the global namespace. The technique below only relies on the browser having the "require.install" property and the server not having it.
 
// ==================================================================
// source code
//
// math.js
//
(function(){var mod=function(require,exports) {
exports.add = function() {
  var sum = arguments[0];
  for (var i=1; i<arguments.length; i++) {
    sum += arguments[i];
  }
  return sum;
};
};require.install?require.install('math',mod):mod(require,exports);})();
//
// increment.js
//
(function(){var mod=function(require,exports) {
var add = require('math').add;
exports.increment = function(val) {
  return add(val, 1);
};
};require.install?require.install('increment',mod):mod(require,exports);})();
//
// program.js
//
var inc = require('increment').increment;
var a = 1;
inc(a); // 2
 
 
Below is a comparison of a module written two different ways.
 
First, the "normal" way for the browser that people are accustom to seeing these days. There are other ways to do it but this is certainly one way in an attempt to make an oranges-to-oranges comparison.
 
// define the library in a file called asdf.js
// first and last lines are boilerplate
var LIB=LIB||{};LIB.asdf=(function(){var exports={};
var c = 1;
exports.a = function() {return c;};
exports.b = 2;
return exports;})();
// use the library in the browser
LIB.asdf.a();
// use the library on the server
require('asdf').LIB.asdf.a();
// Use the library on the server or in browser.
// A module dependent on asdf would need to
// be written like this or something similar.
(require?require('asdf'):window).LIB.asdf.a();
 
Now write the library so it can be used the same way in the browser and on the server where the server has securable module loading. Note the boilerplate is only a little longer and both versions of boilerplate include the name of the module once. The main three lines of the library are the same.
// define the library in a file called asdf.js
// assume "exports" is not defined
// assume "modules" and "require" are defined
// first and last lines are boilerplate
(function(){var mod=function(require,exports) {
var c = 1;
exports.a = function() {return c;};
exports.b = 2;
};require.install?require.install('asdf',mod):mod(require,exports);})();
// use the library in the browser or on the server
require('asdf').a();

Latest revision as of 00:26, 3 November 2009

This specification has moved to the CommonJS wiki.

Retrieved from "https://wiki.mozilla.org/index.php?title=ServerJS/Modules/SecurableModules&oldid=180180"