node_modules/policyfile/doc/index.html

   1 <html>
   2         <head>
   3                 <title>FlashPolicyFileServer</title>
   4                 <script src="http://ajax.googleapis.com/ajax/libs/jquery/1/jquery.min.js"></script>
   5                 <style>body {
   6     margin: 0;
   7     padding: 0;
   8     font: 14px/1.5 'Palatino Linotype', 'Book Antiqua', Palatino, FreeSerif, serif;
   9     color: #252519;
  10 }
  11 a {
  12     color: #252519;
  13 }
  14 a:hover {
  15     text-decoration: underline;
  16     color: #19469D;
  17 }
  18 p {
  19     margin: 12px 0;
  20 }
  21 h1, h2, h3 {
  22     margin: 0;
  23     padding: 0;
  24 }
  25 table#source {
  26     width: 100%;
  27     border-collapse: collapse;
  28 }
  29 table#source td:first-child {
  30     padding: 30px 40px 30px 40px;
  31     vertical-align: top;
  32 }
  33 table#source td:first-child,
  34 table#source td:first-child pre {
  35     width: 450px;
  36 }
  37 table#source td:last-child {
  38     padding: 30px 0 30px 40px;
  39     border-left: 1px solid #E5E5EE;
  40     background: #F5F5FF;
  41 }
  42 table#source tr {
  43     border-bottom: 1px solid #E5E5EE;
  44 }
  45 table#source tr.filename {
  46     padding-top: 40px;
  47     border-top: 1px solid #E5E5EE;
  48 }
  49 table#source tr.filename td:first-child {
  50     text-transform: capitalize;
  51 }
  52 table#source tr.filename td:last-child {
  53     font-size: 12px;
  54 }
  55 table#source tr.filename h2 {
  56     margin: 0;
  57     padding: 0;
  58     cursor: pointer;
  59 }
  60 table#source tr.code h1,
  61 table#source tr.code h2,
  62 table#source tr.code h3 {
  63     margin-top: 30px;
  64     font-family: "Lucida Grande", "Helvetica Nueue", Arial, sans-serif;
  65     font-size: 18px;
  66 }
  67 table#source tr.code h2 {
  68     font-size: 16px;
  69 }
  70 table#source tr.code h3 {
  71     font-size: 14px;
  72 }
  73 table#source tr.code ul {
  74     margin: 15px 0 15px 35px;
  75     padding: 0;
  76 }
  77 table#source tr.code ul li {
  78     margin: 0;
  79     padding: 1px 0;
  80 }
  81 table#source tr.code ul li p {
  82     margin: 0;
  83     padding: 0;
  84 }
  85 table#source tr.code td:first-child pre {
  86     padding: 20px;
  87 }
  88 #ribbon {
  89     position: fixed;
  90     top: 0;
  91     right: 0;
  92 }
  93 code .string { color: #219161; }
  94 code .regexp { color: #219161; }
  95 code .keyword { color: #954121; }
  96 code .number { color: #19469D; }
  97 code .comment { color: #bbb; }
  98 code .this { color: #19469D; }</style>
  99                 <script>
 100                         $(function(){
 101                                 $('tr.code').hide();
 102                                 $('tr.filename').toggle(function(){
 103                                         $(this).nextUntil('.filename').fadeIn();
 104                                 }, function(){
 105                                         $(this).nextUntil('.filename').fadeOut();
 106                                 });
 107                         });
 108                 </script>
 109         </head>
 110         <body>
 111 <table id="source"><tbody><tr><td><h1>FlashPolicyFileServer</h1></td><td></td></tr><tr class="filename"><td><h2 id="lib/server.js"><a href="#">server</a></h2></td><td>lib/server.js</td></tr><tr class="code">
 112 <td class="docs">
 113 <p>Module dependencies and cached references.
 114  </p>
 115 </td>
 116 <td class="code">
 117 <pre><code><span class="keyword">var</span> <span class="variable">slice</span> = <span class="class">Array</span>.<span class="variable">prototype</span>.<span class="variable">slice</span>
 118   , <span class="variable">net</span> = <span class="variable">require</span>(<span class="string">'net'</span>);</code></pre>
 119 </td>
 120 </tr>
 121 <tr class="code">
 122 <td class="docs">
 123 <p>The server that does the Policy File severing</p>
 124
 125 <h2>Options</h2>
 126
 127 <ul><li><code>log</code>  false or a function that can output log information, defaults to console.log?</li></ul>
 128
 129 <h2></h2>
 130
 131 <ul><li><p><strong>param</strong>: <em>Object</em>  options Options to customize the servers functionality.</p></li><li><p><strong>param</strong>: <em>Array</em>  origins The origins that are allowed on this server, defaults to <code>*:*</code>.</p></li><li><p><strong>api</strong>: <em>public</em></p></li></ul>
 132 </td>
 133 <td class="code">
 134 <pre><code><span class="keyword">function</span> <span class="class">Server</span> (<span class="variable">options</span>, <span class="variable">origins</span>) {
 135   <span class="keyword">var</span> <span class="variable">me</span> = <span class="this">this</span>;
 136
 137   <span class="this">this</span>.<span class="variable">origins</span> = <span class="variable">origins</span> || [<span class="string">'*:*'</span>];
 138   <span class="this">this</span>.<span class="variable">port</span> = <span class="number integer">843</span>;
 139   <span class="this">this</span>.<span class="variable">log</span> = <span class="variable">console</span>.<span class="variable">log</span>;
 140
 141   <span class="comment">// merge `this` with the options</span>
 142   <span class="class">Object</span>.<span class="variable">keys</span>(<span class="variable">options</span>).<span class="variable">forEach</span>(<span class="keyword">function</span> (<span class="variable">key</span>) {
 143     <span class="variable">me</span>[<span class="variable">key</span>] &<span class="variable">amp</span>;&<span class="variable">amp</span>; (<span class="variable">me</span>[<span class="variable">key</span>] = <span class="variable">options</span>[<span class="variable">key</span>])
 144   });
 145
 146   <span class="comment">// create the net server</span>
 147   <span class="this">this</span>.<span class="variable">socket</span> = <span class="variable">net</span>.<span class="variable">createServer</span>(<span class="keyword">function</span> <span class="variable">createServer</span> (<span class="variable">socket</span>) {
 148     <span class="variable">socket</span>.<span class="variable">on</span>(<span class="string">'error'</span>, <span class="keyword">function</span> <span class="variable">socketError</span> () {
 149       <span class="variable">me</span>.<span class="variable">responder</span>.<span class="variable">call</span>(<span class="variable">me</span>, <span class="variable">socket</span>);
 150     });
 151
 152     <span class="variable">me</span>.<span class="variable">responder</span>.<span class="variable">call</span>(<span class="variable">me</span>, <span class="variable">socket</span>);
 153   });
 154
 155   <span class="comment">// Listen for errors as the port might be blocked because we do not have root priv.</span>
 156   <span class="this">this</span>.<span class="variable">socket</span>.<span class="variable">on</span>(<span class="string">'error'</span>, <span class="keyword">function</span> <span class="variable">serverError</span> (<span class="variable">err</span>) {
 157     <span class="comment">// Special and common case error handling</span>
 158     <span class="keyword">if</span> (<span class="variable">err</span>.<span class="variable">errno</span> == <span class="number integer">13</span>) {
 159       <span class="variable">me</span>.<span class="variable">log</span> &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">me</span>.<span class="variable">log</span>(
 160         <span class="string">'Unable to listen to port `'</span> + <span class="variable">me</span>.<span class="variable">port</span> + <span class="string">'` as your Node.js instance does not have root privileges. '</span> +
 161         (
 162           <span class="variable">me</span>.<span class="variable">server</span>
 163           ? <span class="string">'The Flash Policy File requests will only be served inline over the supplied HTTP server. Inline serving is slower than a dedicated server instance.'</span>
 164           : <span class="string">'No fallback server supplied, we will be unable to answer Flash Policy File requests.'</span>
 165         )
 166       );
 167
 168       <span class="variable">me</span>.<span class="variable">emit</span>(<span class="string">'connect_failed'</span>, <span class="variable">err</span>);
 169       <span class="variable">me</span>.<span class="variable">socket</span>.<span class="variable">removeAllListeners</span>();
 170       <span class="keyword">delete</span> <span class="variable">me</span>.<span class="variable">socket</span>;
 171     } <span class="keyword">else</span> {
 172       <span class="variable">me</span>.<span class="variable">log</span> &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">me</span>.<span class="variable">log</span>(<span class="string">'FlashPolicyFileServer received an error event:\n'</span> + (<span class="variable">err</span>.<span class="variable">message</span> ? <span class="variable">err</span>.<span class="variable">message</span> : <span class="variable">err</span>));
 173     }
 174   });
 175
 176   <span class="this">this</span>.<span class="variable">socket</span>.<span class="variable">on</span>(<span class="string">'timeout'</span>, <span class="keyword">function</span> <span class="variable">serverTimeout</span> () {});
 177   <span class="this">this</span>.<span class="variable">socket</span>.<span class="variable">on</span>(<span class="string">'close'</span>, <span class="keyword">function</span> <span class="variable">serverClosed</span> (<span class="variable">err</span>) {
 178     <span class="variable">err</span> &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">me</span>.<span class="variable">log</span> &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">me</span>.<span class="variable">log</span>(<span class="string">'Server closing due to an error: \n'</span> + (<span class="variable">err</span>.<span class="variable">message</span> ? <span class="variable">err</span>.<span class="variable">message</span> : <span class="variable">err</span>));
 179
 180     <span class="keyword">if</span> (<span class="variable">me</span>.<span class="variable">server</span>) {
 181       <span class="comment">// Remove the inline policy listener if we close down</span>
 182       <span class="comment">// but only when the server was `online` (see listen prototype)</span>
 183       <span class="keyword">if</span> (<span class="variable">me</span>.<span class="variable">server</span>[<span class="string">'@'</span>] &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">me</span>.<span class="variable">server</span>.<span class="variable">online</span>) {
 184         <span class="variable">me</span>.<span class="variable">server</span>.<span class="variable">removeListener</span>(<span class="string">'connection'</span>, <span class="variable">me</span>.<span class="variable">server</span>[<span class="string">'@'</span>]);
 185       }
 186
 187       <span class="comment">// not online anymore</span>
 188       <span class="keyword">delete</span> <span class="variable">me</span>.<span class="variable">server</span>.<span class="variable">online</span>;
 189     }
 190   });
 191
 192   <span class="comment">// Compile the initial `buffer`</span>
 193   <span class="this">this</span>.<span class="variable">compile</span>();
 194 }</code></pre>
 195 </td>
 196 </tr>
 197 <tr class="code">
 198 <td class="docs">
 199 <p>Start listening for requests</p>
 200
 201 <h2></h2>
 202
 203 <ul><li><p><strong>param</strong>: <em>Number</em>  port The port number it should be listening to.</p></li><li><p><strong>param</strong>: <em>Server</em>  server A HTTP server instance, this will be used to listen for inline requests</p></li><li><p><strong>param</strong>: <em>Function</em>  cb The callback needs to be called once server is ready</p></li><li><p><strong>api</strong>: <em>public</em></p></li></ul>
 204 </td>
 205 <td class="code">
 206 <pre><code><span class="class">Server</span>.<span class="variable">prototype</span>.<span class="variable">listen</span> = <span class="keyword">function</span> <span class="variable">listen</span> (<span class="variable">port</span>, <span class="variable">server</span>, <span class="variable">cb</span>){
 207   <span class="keyword">var</span> <span class="variable">me</span> = <span class="this">this</span>
 208     , <span class="variable">args</span> = <span class="variable">slice</span>.<span class="variable">call</span>(<span class="variable">arguments</span>, <span class="number integer">0</span>)
 209     , <span class="variable">callback</span>;
 210
 211   <span class="comment">// assign the correct vars, for flexible arguments</span>
 212   <span class="variable">args</span>.<span class="variable">forEach</span>(<span class="keyword">function</span> <span class="variable">args</span> (<span class="variable">arg</span>){
 213     <span class="keyword">var</span> <span class="variable">type</span> = <span class="keyword">typeof</span> <span class="variable">arg</span>;
 214
 215     <span class="keyword">if</span> (<span class="variable">type</span> === <span class="string">'number'</span>) <span class="variable">me</span>.<span class="variable">port</span> = <span class="variable">arg</span>;
 216     <span class="keyword">if</span> (<span class="variable">type</span> === <span class="string">'function'</span>) <span class="variable">callback</span> = <span class="variable">arg</span>;
 217     <span class="keyword">if</span> (<span class="variable">type</span> === <span class="string">'object'</span>) <span class="variable">me</span>.<span class="variable">server</span> = <span class="variable">arg</span>;
 218   });
 219
 220   <span class="keyword">if</span> (<span class="this">this</span>.<span class="variable">server</span>) {
 221
 222     <span class="comment">// no one in their right mind would ever create a `@` prototype, so Im just gonna store</span>
 223     <span class="comment">// my function on the server, so I can remove it later again once the server(s) closes</span>
 224     <span class="this">this</span>.<span class="variable">server</span>[<span class="string">'@'</span>] = <span class="keyword">function</span> <span class="variable">connection</span> (<span class="variable">socket</span>) {
 225       <span class="variable">socket</span>.<span class="variable">once</span>(<span class="string">'data'</span>, <span class="keyword">function</span> <span class="variable">requestData</span> (<span class="variable">data</span>) {
 226         <span class="comment">// if it's a Flash policy request, and we can write to the </span>
 227         <span class="keyword">if</span> (
 228              <span class="variable">data</span>
 229           &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">data</span>[<span class="number integer">0</span>] === <span class="number integer">60</span>
 230           &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">data</span>.<span class="variable">toString</span>() === <span class="string">'&lt;policy-file-request/&gt;\0'</span>
 231           &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">socket</span>
 232           &<span class="variable">amp</span>;&<span class="variable">amp</span>; (<span class="variable">socket</span>.<span class="variable">readyState</span> === <span class="string">'open'</span> || <span class="variable">socket</span>.<span class="variable">readyState</span> === <span class="string">'writeOnly'</span>)
 233         ){
 234           <span class="comment">// send the buffer</span>
 235           <span class="keyword">try</span> { <span class="variable">socket</span>.<span class="variable">end</span>(<span class="variable">me</span>.<span class="variable">buffer</span>); }
 236           <span class="keyword">catch</span> (<span class="variable">e</span>) {}
 237         }
 238       });
 239     };
 240
 241     <span class="comment">// attach it</span>
 242     <span class="this">this</span>.<span class="variable">server</span>.<span class="variable">on</span>(<span class="string">'connection'</span>, <span class="this">this</span>.<span class="variable">server</span>[<span class="string">'@'</span>]);
 243   }
 244
 245   <span class="comment">// We add a callback method, so we can set a flag for when the server is `enabled` or `online`.</span>
 246   <span class="comment">// this flag is needed because if a error occurs and the we cannot boot up the server the</span>
 247   <span class="comment">// fallback functionality should not be removed during the `close` event</span>
 248   <span class="this">this</span>.<span class="variable">port</span> &<span class="variable">gt</span>;= <span class="number integer">0</span> &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="this">this</span>.<span class="variable">socket</span>.<span class="variable">listen</span>(<span class="this">this</span>.<span class="variable">port</span>, <span class="keyword">function</span> <span class="variable">serverListening</span> () {
 249     <span class="variable">me</span>.<span class="variable">socket</span>.<span class="variable">online</span> = <span class="variable">true</span>;
 250     <span class="keyword">if</span> (<span class="variable">callback</span>) {
 251       <span class="variable">callback</span>.<span class="variable">call</span>(<span class="variable">me</span>);
 252       <span class="variable">callback</span> = <span class="variable">undefined</span>;
 253     }
 254   });
 255
 256   <span class="keyword">return</span> <span class="this">this</span>;
 257 };</code></pre>
 258 </td>
 259 </tr>
 260 <tr class="code">
 261 <td class="docs">
 262 <p>Adds a new origin to the Flash Policy File.</p>
 263
 264 <h2></h2>
 265
 266 <ul><li><p><strong>param</strong>: <em>Arguments</em>  The origins that need to be added.</p></li><li><p><strong>api</strong>: <em>public</em></p></li></ul>
 267 </td>
 268 <td class="code">
 269 <pre><code><span class="class">Server</span>.<span class="variable">prototype</span>.<span class="variable">add</span> = <span class="keyword">function</span> <span class="variable">add</span>(){
 270   <span class="keyword">var</span> <span class="variable">args</span> = <span class="variable">slice</span>.<span class="variable">call</span>(<span class="variable">arguments</span>, <span class="number integer">0</span>)
 271     , <span class="variable">i</span> = <span class="variable">args</span>.<span class="variable">length</span>;
 272
 273   <span class="comment">// flag duplicates</span>
 274   <span class="keyword">while</span> (<span class="variable">i</span>--) {
 275     <span class="keyword">if</span> (<span class="this">this</span>.<span class="variable">origins</span>.<span class="variable">indexOf</span>(<span class="variable">args</span>[<span class="variable">i</span>]) &<span class="variable">gt</span>;= <span class="number integer">0</span>){
 276       <span class="variable">args</span>[<span class="variable">i</span>] = <span class="keyword">null</span>;
 277     }
 278   }
 279
 280   <span class="comment">// Add all the arguments to the array</span>
 281   <span class="comment">// but first we want to remove all `falsy` values from the args</span>
 282   <span class="class">Array</span>.<span class="variable">prototype</span>.<span class="variable">push</span>.<span class="variable">apply</span>(
 283     <span class="this">this</span>.<span class="variable">origins</span>
 284   , <span class="variable">args</span>.<span class="variable">filter</span>(<span class="keyword">function</span> <span class="variable">filter</span> (<span class="variable">value</span>) {
 285       <span class="keyword">return</span> !!<span class="variable">value</span>;
 286     })
 287   );
 288
 289   <span class="this">this</span>.<span class="variable">compile</span>();
 290   <span class="keyword">return</span> <span class="this">this</span>;
 291 };</code></pre>
 292 </td>
 293 </tr>
 294 <tr class="code">
 295 <td class="docs">
 296 <p>Removes a origin from the Flash Policy File.</p>
 297
 298 <h2></h2>
 299
 300 <ul><li><p><strong>param</strong>: <em>String</em>  origin The origin that needs to be removed from the server</p></li><li><p><strong>api</strong>: <em>public</em></p></li></ul>
 301 </td>
 302 <td class="code">
 303 <pre><code><span class="class">Server</span>.<span class="variable">prototype</span>.<span class="variable">remove</span> = <span class="keyword">function</span> <span class="variable">remove</span> (<span class="variable">origin</span>){
 304   <span class="keyword">var</span> <span class="variable">position</span> = <span class="this">this</span>.<span class="variable">origins</span>.<span class="variable">indexOf</span>(<span class="variable">origin</span>);
 305
 306   <span class="comment">// only remove and recompile if we have a match</span>
 307   <span class="keyword">if</span> (<span class="variable">position</span> &<span class="variable">gt</span>; <span class="number integer">0</span>) {
 308     <span class="this">this</span>.<span class="variable">origins</span>.<span class="variable">splice</span>(<span class="variable">position</span>, <span class="number integer">1</span>);
 309     <span class="this">this</span>.<span class="variable">compile</span>();
 310   }
 311
 312   <span class="keyword">return</span> <span class="this">this</span>;
 313 };</code></pre>
 314 </td>
 315 </tr>
 316 <tr class="code">
 317 <td class="docs">
 318 <p>Closes and cleans up the server</p>
 319
 320 <ul><li><p><strong>api</strong>: <em>public</em></p></li></ul>
 321 </td>
 322 <td class="code">
 323 <pre><code><span class="class">Server</span>.<span class="variable">prototype</span>.<span class="variable">close</span> = <span class="keyword">function</span> <span class="variable">close</span> () {
 324   <span class="this">this</span>.<span class="variable">socket</span>.<span class="variable">removeAllListeners</span>();
 325   <span class="keyword">try</span> { <span class="this">this</span>.<span class="variable">socket</span>.<span class="variable">close</span>(); }
 326   <span class="keyword">catch</span> (<span class="variable">e</span>) {}
 327
 328   <span class="keyword">return</span> <span class="this">this</span>;
 329 };</code></pre>
 330 </td>
 331 </tr>
 332 <tr class="code">
 333 <td class="docs">
 334 <p>Proxy the event listener requests to the created Net server
 335  </p>
 336 </td>
 337 <td class="code">
 338 <pre><code><span class="class">Object</span>.<span class="variable">keys</span>(<span class="variable">process</span>.<span class="class">EventEmitter</span>.<span class="variable">prototype</span>).<span class="variable">forEach</span>(<span class="keyword">function</span> <span class="variable">proxy</span> (<span class="variable">key</span>){
 339   <span class="class">Server</span>.<span class="variable">prototype</span>[<span class="variable">key</span>] = <span class="class">Server</span>.<span class="variable">prototype</span>[<span class="variable">key</span>] || <span class="keyword">function</span> () {
 340     <span class="keyword">if</span> (<span class="this">this</span>.<span class="variable">socket</span>) {
 341       <span class="this">this</span>.<span class="variable">socket</span>[<span class="variable">key</span>].<span class="variable">apply</span>(<span class="this">this</span>.<span class="variable">socket</span>, <span class="variable">arguments</span>);
 342     }
 343
 344     <span class="keyword">return</span> <span class="this">this</span>;
 345   };
 346 });</code></pre>
 347 </td>
 348 </tr>
 349 <tr class="code">
 350 <td class="docs">
 351 <p>Creates a new server instance.</p>
 352
 353 <h2></h2>
 354
 355 <ul><li><p><strong>param</strong>: <em>Object</em>  options A options object to override the default config</p></li><li><p><strong>param</strong>: <em>Array</em>  origins The origins that should be allowed by the server</p></li><li><p><strong>api</strong>: <em>public</em></p></li></ul>
 356 </td>
 357 <td class="code">
 358 <pre><code><span class="variable">exports</span>.<span class="variable">createServer</span> = <span class="keyword">function</span> <span class="variable">createServer</span> (<span class="variable">options</span>, <span class="variable">origins</span>) {
 359   <span class="variable">origins</span> = <span class="class">Array</span>.<span class="variable">isArray</span>(<span class="variable">origins</span>)
 360       ? <span class="variable">origins</span>
 361       : (<span class="class">Array</span>.<span class="variable">isArray</span>(<span class="variable">options</span>) ? <span class="variable">options</span> : <span class="variable">false</span>);
 362
 363   <span class="variable">options</span> = !<span class="class">Array</span>.<span class="variable">isArray</span>(<span class="variable">options</span>) &<span class="variable">amp</span>;&<span class="variable">amp</span>; <span class="variable">options</span>
 364       ? <span class="variable">options</span>
 365       : {};
 366
 367   <span class="keyword">return</span> <span class="keyword">new</span> <span class="class">Server</span>(<span class="variable">options</span>, <span class="variable">origins</span>);
 368 };</code></pre>
 369 </td>
 370 </tr>
 371 <tr class="code">
 372 <td class="docs">
 373 <p>Provide a hook to the original server, so it can be extended if needed.</p>
 374
 375 <h2></h2>
 376
 377 <ul><li><p><strong>type</strong>: <em>Net.Server</em> </p></li></ul>
 378 </td>
 379 <td class="code">
 380 <pre><code><span class="variable">exports</span>.<span class="class">Server</span> = <span class="class">Server</span>;</code></pre>
 381 </td>
 382 </tr>
 383 <tr class="code">
 384 <td class="docs">
 385 <p>Module version</p>
 386
 387 <h2></h2>
 388
 389 <ul><li><p><strong>type</strong>: <em>String</em> </p></li></ul>
 390 </td>
 391 <td class="code">
 392 <pre><code><span class="variable">exports</span>.<span class="variable">version</span> = <span class="string">'0.0.5'</span>;
 393 </code></pre>
 394 </td>
 395 </tr>   </body>
 396 </html></tbody></table>