Open-ILS/web/js/ui/default/staff/services/hatch.js

   1 /**
   2  * Core Service - egHatch
   3  *
   4  * Dispatches print and data storage requests to the appropriate handler.
   5  *
   6  * If Hatch is configured to honor the request -- current request types
   7  * are 'settings', 'offline', and 'printing' -- the request will be
   8  * relayed to the Hatch service.  Otherwise, the request is handled
   9  * locally.
  10  *
  11  * Most handlers also provide direct remote and local variants to the
  12  * application can decide to which to use as needed.
  13  *
  14  * Local storage requests are handled by $window.localStorage.
  15  *
  16  * Note that all top-level and remote requests return promises.  All
  17  * local requests return immediate values, since local requests are
  18  * never asynchronous.
  19  *
  20  * BEWARE: never store "fieldmapper" objects, since their structure
  21  * may change over time as the IDL changes.  Always flatten objects
  22  * into key/value pairs before calling set*Item()
  23  *
  24  */
  25 angular.module('egCoreMod')
  26
  27 .factory('egHatch',
  28            ['$q','$window','$timeout','$interpolate','$cookies','egNet','$injector',
  29     function($q , $window , $timeout , $interpolate , $cookies , egNet , $injector ) {
  30
  31     var service = {};
  32     service.msgId = 1;
  33     service.messages = {};
  34     service.hatchAvailable = false;
  35     service.auth = null;  // ref to egAuth loaded on-demand to avoid circular ref.
  36     service.disableServerSettings = false;
  37
  38     // key/value cache -- avoid unnecessary Hatch extension requests.
  39     // Only affects *RemoteItem calls.
  40     service.keyCache = {};
  41
  42     // Keep a local copy of all retrieved setting summaries, which indicate
  43     // which setting types exist for each setting.
  44     service.serverSettingSummaries = {};
  45
  46     /**
  47      * List string prefixes for On-Call storage keys. On-Call keys
  48      * are those that can be set/get/remove'd from localStorage when
  49      * Hatch is not avaialable, even though Hatch is configured as the
  50      * primary storage location for the key in question.  On-Call keys
  51      * are those that allow the user to login and perform basic admin
  52      * tasks (like disabling Hatch) even when Hatch is down.
  53      * AKA Browser Staff Run Level 3.
  54      * Note that no attempt is made to synchronize data between Hatch
  55      * and localStorage for On-Call keys.  Only one destation is active
  56      * at a time and each maintains its own data separately.
  57      */
  58     service.onCallPrefixes = ['eg.workstation'];
  59
  60     // Returns true if the key can be set/get in localStorage even when
  61     // Hatch is not available.
  62     service.keyIsOnCall = function(key) {
  63         var oncall = false;
  64         angular.forEach(service.onCallPrefixes, function(pfx) {
  65             if (key.match(new RegExp('^' + pfx)))
  66                 oncall = true;
  67         });
  68         return oncall;
  69     }
  70
  71     /**
  72      * Settings with these prefixes will always live in the browser.
  73      */
  74     service.browserOnlyPrefixes = [
  75         'eg.workstation',
  76         'eg.hatch',
  77         'eg.cache',
  78         'current_tag_table_marc21_biblio',
  79         'FFPos',
  80         'FFValue'
  81     ];
  82
  83     service.keyStoredInBrowser = function(key) {
  84
  85         if (service.disableServerSettings) {
  86             // When server-side storage is disabled, treat every
  87             // setting like it's stored locally.
  88             return true;
  89         }
  90
  91         var browserOnly = false;
  92         service.browserOnlyPrefixes.forEach(function(pfx) {
  93             if (key.match(new RegExp('^' + pfx)))
  94                 browserOnly = true;
  95         });
  96
  97         return browserOnly;
  98     }
  99
 100     // write a message to the Hatch port
 101     service.sendToHatch = function(msg) {
 102         var msg2 = {};
 103
 104         // shallow copy and scrub msg before sending
 105         angular.forEach(msg, function(val, key) {
 106             if (key.match(/deferred/)) return;
 107             msg2[key] = val;
 108         });
 109
 110         console.debug("sending to Hatch: " + JSON.stringify(msg2));
 111
 112         msg2.from = 'page';
 113         $window.postMessage(msg2, $window.location.origin);
 114     }
 115
 116     // Send request to Hatch or reject if Hatch is unavailable
 117     service.attemptHatchDelivery = function(msg) {
 118         msg.msgid = service.msgId++;
 119         msg.deferred = $q.defer();
 120
 121         if (service.hatchAvailable) {
 122             service.messages[msg.msgid] = msg;
 123             service.sendToHatch(msg);
 124
 125         } else {
 126             console.error(
 127                 'Hatch request attempted but Hatch is not available');
 128             msg.deferred.reject(msg);
 129         }
 130
 131         return msg.deferred.promise;
 132     }
 133
 134
 135     // resolve the promise on the given request and remove
 136     // it from our tracked requests.
 137     service.resolveRequest = function(msg) {
 138
 139         if (!service.messages[msg.msgid]) {
 140             console.error('no cached message for id = ' + msg.msgid);
 141             return;
 142         }
 143
 144         // for requests sent through Hatch, only the cached
 145         // request will have the original promise attached
 146         msg.deferred = service.messages[msg.msgid].deferred;
 147         delete service.messages[msg.msgid]; // un-cache
 148
 149         if (msg.status == 200) {
 150             msg.deferred.resolve(msg.content);
 151         } else {
 152             console.warn("Hatch command failed with status="
 153                 + msg.status + " and message=" + msg.message);
 154             msg.deferred.reject();
 155         }
 156     }
 157
 158     service.openHatch = function() {
 159
 160         // When the Hatch extension loads, it tacks an attribute onto
 161         // the top-level documentElement to indicate it's available.
 162         if (!$window.document.documentElement.getAttribute('hatch-is-open')) {
 163             //console.debug("Hatch is not available");
 164             return;
 165         }
 166
 167         $window.addEventListener("message", function(event) {
 168             // We only accept messages from our own content script.
 169             if (event.source != window) return;
 170
 171             // We only care about messages from the Hatch extension.
 172             if (event.data && event.data.from == 'extension') {
 173
 174                 // Avoid logging full Hatch responses. they can get large.
 175                 console.debug(
 176                     'Hatch responded to message ID ' + event.data.msgid);
 177
 178                 service.resolveRequest(event.data);
 179             }
 180         });
 181
 182         service.hatchAvailable = true; // public flag
 183     }
 184
 185     service.remotePrint = function(
 186         context, contentType, content, withDialog) {
 187
 188         return service.getPrintConfig(context).then(
 189             function(config) {
 190                 // print configuration retrieved; print
 191                 return service.attemptHatchDelivery({
 192                     action : 'print',
 193                     settings : config,
 194                     content : content,
 195                     contentType : contentType,
 196                     showDialog : withDialog,
 197                 });
 198             }
 199         );
 200     }
 201
 202     service.getPrintConfig = function(context) {
 203         return service.getRemoteItem('eg.print.config.' + context);
 204     }
 205
 206     service.setPrintConfig = function(context, config) {
 207         return service.setRemoteItem('eg.print.config.' + context, config);
 208     }
 209
 210     service.getPrinterOptions = function(name) {
 211         return service.attemptHatchDelivery({
 212             action : 'printer-options',
 213             printer : name
 214         });
 215     }
 216
 217     service.getPrinters = function() {
 218         if (service.printers) // cached printers
 219             return $q.when(service.printers);
 220
 221         return service.attemptHatchDelivery({action : 'printers'}).then(
 222
 223             // we have remote printers; sort by name and return
 224             function(printers) {
 225                 service.printers = printers.sort(
 226                     function(a,b) {return a.name < b.name ? -1 : 1});
 227                 return service.printers;
 228             },
 229
 230             // remote call failed and there is no such thing as local
 231             // printers; return empty set.
 232             function() { return [] }
 233         );
 234     }
 235
 236     // TODO: once Hatch is printing-only, should probably store
 237     // this preference on the server.
 238     service.usePrinting = function() {
 239         return service.getLocalItem('eg.hatch.enable.printing');
 240     }
 241
 242     service.useSettings = function() {
 243         return service.getLocalItem('eg.hatch.enable.settings');
 244     }
 245
 246     service.useOffline = function() {
 247         return service.getLocalItem('eg.hatch.enable.offline');
 248     }
 249
 250     // get the value for a stored item
 251     service.getItem = function(key) {
 252
 253         console.debug('getting item: ' + key);
 254
 255         if (!service.keyStoredInBrowser(key)) {
 256             return service.getServerItem(key);
 257         }
 258
 259         var deferred = $q.defer();
 260
 261         service.getBrowserItem(key).then(
 262             function(val) { deferred.resolve(val); },
 263
 264             function() { // Hatch error
 265                 if (service.keyIsOnCall(key)) {
 266                     console.warn("Unable to getItem from Hatch: " + key +
 267                         ". Retrieving item from local storage instead");
 268                     deferred.resolve(service.getLocalItem(key));
 269                 }
 270
 271                 deferred.reject("Unable to getItem from Hatch: " + key);
 272             }
 273         );
 274
 275         return deferred.promise;
 276     }
 277
 278     // Collect values in batch.
 279     // For server-stored values espeically, this is more efficient
 280     // than a series of one-off calls.
 281     service.getItemBatch = function(keys) {
 282         var browserKeys = [];
 283         var serverKeys = [];
 284
 285         // To take full advantage of the getServerItemBatch call,
 286         // we have to know in advance which keys to send to the server
 287         // vs those to handle in the browser.
 288         keys.forEach(function(key) {
 289             if (service.keyStoredInBrowser(key)) {
 290                 browserKeys.push(key);
 291             } else {
 292                 serverKeys.push(key);
 293             }
 294         });
 295
 296         var settings = {};
 297
 298         var serverPromise = serverKeys.length === 0 ? $q.when() :
 299             service.getServerItemBatch(serverKeys).then(function(values) {
 300                 angular.forEach(values, function(val, key) {
 301                     settings[key] = val;
 302                 });
 303             });
 304
 305         var browserPromises = [];
 306         browserKeys.forEach(function(key) {
 307             browserPromises.push(
 308                 service.getBrowserItem(key).then(function(val) {
 309                     settings[key] = val;
 310                 })
 311             );
 312         });
 313
 314         return $q.all(browserPromises.concat(serverPromise))
 315             .then(function() {return settings});
 316     }
 317
 318     service.getBrowserItem = function(key) {
 319         if (service.useSettings()) {
 320             if (service.hatchAvailable) {
 321                 return service.getRemoteItem(key);
 322             }
 323         } else {
 324             return $q.when(service.getLocalItem(key));
 325         }
 326         return $q.reject();
 327     }
 328
 329     service.getRemoteItem = function(key) {
 330
 331         if (service.keyCache[key] != undefined)
 332             return $q.when(service.keyCache[key])
 333
 334         return service.attemptHatchDelivery({
 335             key : key,
 336             action : 'get'
 337         }).then(function(content) {
 338             return service.keyCache[key] = content;
 339         });
 340     }
 341
 342     service.getLocalItem = function(key) {
 343         var val = $window.localStorage.getItem(key);
 344         if (val === null || val === undefined) return;
 345         try {
 346             return JSON.parse(val);
 347         } catch(E) {
 348             console.error(
 349                 "Deleting invalid JSON for localItem: " + key + " => " + val);
 350             service.removeLocalItem(key);
 351             return null;
 352         }
 353     }
 354
 355     service.getLoginSessionItem = function(key) {
 356         var val = $cookies.get(key);
 357         if (val == null) return;
 358         return JSON.parse(val);
 359     }
 360
 361     service.getSessionItem = function(key) {
 362         var val = $window.sessionStorage.getItem(key);
 363         if (val == null) return;
 364         return JSON.parse(val);
 365     }
 366
 367     /**
 368      * @param tmp bool Store the value as a session cookie only.
 369      * tmp values are removed during logout or browser close.
 370      */
 371     service.setItem = function(key, value) {
 372
 373         if (!service.keyStoredInBrowser(key)) {
 374             return service.setServerItem(key, value);
 375         }
 376
 377         var deferred = $q.defer();
 378         return service.setBrowserItem(key, value).then(
 379             function(val) {deferred.resolve(val);},
 380
 381             function() { // Hatch error
 382
 383                 if (service.keyIsOnCall(key)) {
 384                     console.warn("Unable to setItem in Hatch: " +
 385                         key + ". Setting in local storage instead");
 386
 387                     deferred.resolve(service.setLocalItem(key, value));
 388                 }
 389                 deferred.reject("Unable to setItem in Hatch: " + key);
 390             }
 391         );
 392     }
 393
 394     service.setBrowserItem = function(key, value) {
 395         if (service.useSettings()) {
 396             if (service.hatchAvailable) {
 397                 return service.setRemoteItem(key, value);
 398             } else {
 399                 return $q.reject('Unable to get item from hatch');
 400             }
 401         } else {
 402             return $q.when(service.setLocalItem(key, value));
 403         }
 404     }
 405
 406     service.setServerItem = function(key, value) {
 407         if (!service.auth) service.auth = $injector.get('egAuth');
 408         if (!service.auth.token()) return $q.when();
 409
 410         // If we have already attempted to retrieve a value for this
 411         // setting, then we can tell up front whether applying a value
 412         // at the server will be an option.  If not, store locally.
 413         var summary = service.serverSettingSummaries[key];
 414         if (summary && !summary.has_staff_setting) {
 415
 416             if (summary.has_org_setting === 't') {
 417                 // When no user/ws setting types exist but an org unit
 418                 // setting type does, it means the value cannot be
 419                 // applied by an individual user.  Nothing left to do.
 420                 return $q.when();
 421             }
 422
 423             // No setting types of any flavor exist.
 424             // Fall back to local storage.
 425
 426             if (value === null) {
 427                 // a null value means clear the server setting.
 428                 return service.removeBrowserItem(key);
 429             } else {
 430                 console.warn('No server setting type exists for ' + key);
 431                 return service.setBrowserItem(key, value);
 432             }
 433         }
 434
 435         var settings = {};
 436         settings[key] = value;
 437
 438         return egNet.request(
 439             'open-ils.actor',
 440             'open-ils.actor.settings.apply.user_or_ws',
 441             service.auth.token(), settings
 442         ).then(function(appliedCount) {
 443
 444             if (appliedCount == 0) {
 445                 console.warn('No server setting type exists for ' + key);
 446                 // We were unable to store the setting on the server,
 447                 // presumably becuase no server-side setting type exists.
 448                 // Add to local storage instead.
 449                 service.setLocalItem(key, value);
 450             }
 451
 452             service.keyCache[key] = value;
 453             return appliedCount;
 454         });
 455     }
 456
 457     service.getServerItem = function(key) {
 458         if (key in service.keyCache) {
 459             return $q.when(service.keyCache[key])
 460         }
 461
 462         if (!service.auth) service.auth = $injector.get('egAuth');
 463         if (!service.auth.token()) return $q.when(null);
 464
 465         return egNet.request(
 466             'open-ils.actor',
 467             'open-ils.actor.settings.retrieve.atomic',
 468             [key], service.auth.token()
 469         ).then(function(settings) {
 470             return service.handleServerItemResponse(settings[0]);
 471         });
 472     }
 473
 474     service.handleServerItemResponse = function(summary) {
 475         var key = summary.name;
 476         var val = summary.value;
 477
 478         // For our purposes, we only care if a setting can be stored
 479         // as an org setting or a user-or-workstation setting.
 480         summary.has_staff_setting = (
 481             summary.has_user_setting === 't' ||
 482             summary.has_workstation_setting === 't'
 483         );
 484
 485         summary.value = null; // avoid duplicate value caches
 486         service.serverSettingSummaries[key] = summary;
 487
 488         if (val !== null) {
 489             // We have a server setting.  Nothing left to do.
 490             return $q.when(service.keyCache[key] = val);
 491         }
 492
 493         if (!summary.has_staff_setting) {
 494
 495             if (summary.has_org_setting === 't') {
 496                 // An org unit setting type exists but no value is applied
 497                 // that this workstation has access to.  The existence of
 498                 // an org unit setting type and no user/ws setting type
 499                 // means applying a value locally is not allowed.
 500                 return $q.when(service.keyCache[key] = undefined);
 501             }
 502
 503             console.warn('No server setting type exists for '
 504                 + key + ', using local value.');
 505
 506             return service.getBrowserItem(key);
 507         }
 508
 509         // A user/ws setting type exists, but no server value exists.
 510         // Migrate the local setting to the server.
 511
 512         var deferred = $q.defer();
 513         service.getBrowserItem(key).then(function(browserVal) {
 514
 515             if (browserVal === null || browserVal === undefined) {
 516                 // No local value to migrate.
 517                 return deferred.resolve(service.keyCache[key] = undefined);
 518             }
 519
 520             // Migrate the local value to the server.
 521
 522             service.setServerItem(key, browserVal).then(
 523                 function(appliedCount) {
 524                     if (appliedCount == 1) {
 525                         console.info('setting ' + key + ' successfully ' +
 526                             'migrated to a server setting');
 527                         service.removeBrowserItem(key); // fire & forget
 528                     } else {
 529                         console.error('error migrating setting to server,'
 530                             + ' falling back to local value');
 531                     }
 532                     deferred.resolve(service.keyCache[key] = browserVal);
 533                 }
 534             );
 535         });
 536
 537         return deferred.promise;
 538     }
 539
 540     service.getServerItemBatch = function(keys) {
 541         // no cache checking for now.  assumes batch mode is only
 542         // called once on page load.  maybe add cache checking later.
 543         if (!service.auth) service.auth = $injector.get('egAuth');
 544         if (!service.auth.token()) return $q.when({});
 545
 546         var foundValues = {};
 547         return egNet.request(
 548             'open-ils.actor',
 549             'open-ils.actor.settings.retrieve.atomic',
 550             keys, service.auth.token()
 551         ).then(
 552             function(settings) {
 553                 //return foundValues;
 554
 555                 var deferred = $q.defer();
 556                 function checkOne(setting) {
 557                     if (!setting) {
 558                         deferred.resolve(foundValues);
 559                         return;
 560                     }
 561                     service.handleServerItemResponse(setting)
 562                     .then(function(resp) {
 563                         if (resp !== undefined) {
 564                             foundValues[setting.name] = resp;
 565                         }
 566                         settings.shift();
 567                         checkOne(settings[0]);
 568                     });
 569                 }
 570
 571                 checkOne(settings[0]);
 572                 return deferred.promise;
 573             },
 574         );
 575     }
 576
 577
 578     // set the value for a stored or new item
 579     service.setRemoteItem = function(key, value) {
 580         service.keyCache[key] = value;
 581         return service.attemptHatchDelivery({
 582             key : key,
 583             content : value,
 584             action : 'set',
 585         });
 586     }
 587
 588     // Set the value for the given key.
 589     // "Local" items persist indefinitely.
 590     // If the value is raw, pass it as 'value'.  If it was
 591     // externally JSONified, pass it via jsonified.
 592     service.setLocalItem = function(key, value, jsonified) {
 593         if (jsonified === undefined ) {
 594             jsonified = JSON.stringify(value);
 595         } else if (value === undefined) {
 596             return;
 597         }
 598         $window.localStorage.setItem(key, jsonified);
 599     }
 600
 601     service.appendItem = function(key, value) {
 602         if (!service.useSettings())
 603             return $q.when(service.appendLocalItem(key, value));
 604
 605         if (service.hatchAvailable)
 606             return service.appendRemoteItem(key, value);
 607
 608         if (service.keyIsOnCall(key)) {
 609             console.warn("Unable to appendItem in Hatch: " +
 610                 key + ". Setting in local storage instead");
 611
 612             return $q.when(service.appendLocalItem(key, value));
 613         }
 614
 615         console.error("Unable to appendItem in Hatch: " + key);
 616         return $q.reject();
 617     }
 618
 619     // append the value to a stored or new item
 620     service.appendRemoteItem = function(key, value) {
 621         service.keyCache[key] = value;
 622         return service.attemptHatchDelivery({
 623             key : key,
 624             content : value,
 625             action : 'append',
 626         });
 627     }
 628
 629     service.appendLocalItem = function(key, value, jsonified) {
 630         if (jsonified === undefined )
 631             jsonified = JSON.stringify(value);
 632
 633         var old_value = $window.localStorage.getItem(key) || '';
 634         $window.localStorage.setItem( key, old_value + jsonified );
 635     }
 636
 637     // Set the value for the given key.
 638     // "LoginSession" items are removed when the user logs out or the
 639     // browser is closed.
 640     // If the value is raw, pass it as 'value'.  If it was
 641     // externally JSONified, pass it via jsonified.
 642     service.setLoginSessionItem = function(key, value, jsonified) {
 643         service.addLoginSessionKey(key);
 644         if (jsonified === undefined )
 645             jsonified = JSON.stringify(value);
 646         $cookies.put(key, jsonified);
 647     }
 648
 649     // Set the value for the given key.
 650     // "Session" items are browser tab-specific and are removed when the
 651     // tab is closed.
 652     // If the value is raw, pass it as 'value'.  If it was
 653     // externally JSONified, pass it via jsonified.
 654     service.setSessionItem = function(key, value, jsonified) {
 655         if (jsonified === undefined )
 656             jsonified = JSON.stringify(value);
 657         $window.sessionStorage.setItem(key, jsonified);
 658     }
 659
 660     // remove a stored item
 661     service.removeItem = function(key) {
 662
 663         if (!service.keyStoredInBrowser(key)) {
 664             return service.removeServerItem(key);
 665         }
 666
 667         var deferred = $q.defer();
 668         service.removeBrowserItem(key).then(
 669             function(response) {deferred.resolve(response);},
 670             function() { // Hatch error
 671
 672                 if (service.keyIsOnCall(key)) {
 673                     console.warn("Unable to removeItem from Hatch: " + key +
 674                         ". Removing item from local storage instead");
 675
 676                     deferred.resolve(service.removeLocalItem(key));
 677                 }
 678
 679                 deferred.reject("Unable to removeItem from Hatch: " + key);
 680             }
 681         );
 682
 683         return deferred.promise;
 684     }
 685
 686     service.removeBrowserItem = function(key) {
 687         if (service.useSettings()) {
 688             if (service.hatchAvailable) {
 689                 return service.removeRemoteItem(key);
 690             } else {
 691                 return $q.reject('error talking to Hatch');
 692             }
 693         } else {
 694             return $q.when(service.removeLocalItem(key));
 695         }
 696     }
 697
 698     service.removeServerItem = function(key) {
 699         return service.setServerItem(key, null);
 700     }
 701
 702     service.removeRemoteItem = function(key) {
 703         delete service.keyCache[key];
 704         return service.attemptHatchDelivery({
 705             key : key,
 706             action : 'remove'
 707         });
 708     }
 709
 710     service.removeLocalItem = function(key) {
 711         $window.localStorage.removeItem(key);
 712     }
 713
 714     service.removeLoginSessionItem = function(key) {
 715         service.removeLoginSessionKey(key);
 716         $cookies.remove(key);
 717     }
 718
 719     service.removeSessionItem = function(key) {
 720         $window.sessionStorage.removeItem(key);
 721     }
 722
 723     /**
 724      * Remove all "LoginSession" items.
 725      */
 726     service.clearLoginSessionItems = function() {
 727         angular.forEach(service.getLoginSessionKeys(), function(key) {
 728             service.removeLoginSessionItem(key);
 729         });
 730
 731         // remove the keys cache.
 732         service.removeLocalItem('eg.hatch.login_keys');
 733     }
 734
 735     // if set, prefix limits the return set to keys starting with 'prefix'
 736     service.getKeys = function(prefix) {
 737         var promise = service.getServerKeys(prefix);
 738         return service.getBrowserKeys(prefix).then(function(browserKeys) {
 739             return promise.then(function(serverKeys) {
 740                 return serverKeys.concat(browserKeys);
 741             });
 742         });
 743     }
 744
 745     service.getRemoteKeys = function(prefix) {
 746         return service.attemptHatchDelivery({
 747             key : prefix,
 748             action : 'keys'
 749         });
 750     }
 751
 752     service.getBrowserKeys = function(prefix) {
 753         if (service.useSettings())
 754             return service.getRemoteKeys(prefix);
 755         return $q.when(service.getLocalKeys(prefix));
 756     }
 757
 758     service.getServerKeys = function(prefix, options) {
 759         if (!service.auth) service.auth = $injector.get('egAuth');
 760         if (!service.auth.token()) return $q.when({});
 761         return egNet.request(
 762             'open-ils.actor',
 763             'open-ils.actor.settings.staff.applied.names.authoritative.atomic',
 764             service.auth.token(), prefix, options
 765         );
 766     }
 767
 768     service.getLocalKeys = function(prefix) {
 769         var keys = [];
 770         var idx = 0;
 771         while ( (k = $window.localStorage.key(idx++)) !== null) {
 772             // key prefix match test
 773             if (prefix && k.substr(0, prefix.length) != prefix) continue;
 774             keys.push(k);
 775         }
 776         return keys;
 777     }
 778
 779
 780     /**
 781      * Array of "LoginSession" keys.
 782      * Note we have to store these as "Local" items so browser tabs can
 783      * share them.  We could store them as cookies, but it's more data
 784      * that has to go back/forth to the server.  A "LoginSession" key name is
 785      * not private, though, so it's OK if they are left in localStorage
 786      * until the next login.
 787      */
 788     service.getLoginSessionKeys = function(prefix) {
 789         var keys = [];
 790         var idx = 0;
 791         var login_keys = service.getLocalItem('eg.hatch.login_keys') || [];
 792         angular.forEach(login_keys, function(k) {
 793             // key prefix match test
 794             if (prefix && k.substr(0, prefix.length) != prefix) return;
 795             keys.push(k);
 796         });
 797         return keys;
 798     }
 799
 800     service.addLoginSessionKey = function(key) {
 801         var keys = service.getLoginSessionKeys();
 802         if (keys.indexOf(key) < 0) {
 803             keys.push(key);
 804             service.setLocalItem('eg.hatch.login_keys', keys);
 805         }
 806     }
 807
 808     service.removeLoginSessionKey = function(key) {
 809         var keys = service.getLoginSessionKeys().filter(function(k) {
 810             return k != key;
 811         });
 812         service.setLocalItem('eg.hatch.login_keys', keys);
 813     }
 814
 815     // Copy all stored settings from localStorage to Hatch.
 816     // If 'move' is true, delete the local settings once cloned.
 817     service.copySettingsToHatch = function(move) {
 818         var deferred = $q.defer();
 819         var keys = service.getLocalKeys();
 820
 821         angular.forEach(keys, function(key) {
 822
 823             // Hatch keys are local-only
 824             if (key.match(/^eg.hatch/)) return;
 825
 826             console.debug("Copying to Hatch Storage: " + key);
 827             service.setRemoteItem(key, service.getLocalItem(key))
 828             .then(function() { // key successfully cloned.
 829
 830                 // delete the local copy if requested.
 831                 if (move) service.removeLocalItem(key);
 832
 833                 // resolve the promise after processing the last key.
 834                 if (key == keys[keys.length-1])
 835                     deferred.resolve();
 836             });
 837         });
 838
 839         return deferred.promise;
 840     }
 841
 842     // Copy all stored settings from Hatch to localStorage.
 843     // If 'move' is true, delete the Hatch settings once cloned.
 844     service.copySettingsToLocal = function(move) {
 845         var deferred = $q.defer();
 846
 847         service.getRemoteKeys().then(function(keys) {
 848             angular.forEach(keys, function(key) {
 849                 service.getRemoteItem(key).then(function(val) {
 850
 851                     console.debug("Copying to Local Storage: " + key);
 852                     service.setLocalItem(key, val);
 853
 854                     // delete the remote copy if requested.
 855                     if (move) service.removeRemoteItem(key);
 856
 857                     // resolve the promise after processing the last key.
 858                     if (key == keys[keys.length-1])
 859                         deferred.resolve();
 860                 });
 861             });
 862         });
 863
 864         return deferred.promise;
 865     }
 866
 867     // The only requirement for opening Hatch is that the DOM be loaded.
 868     // Open the connection now so its state will be immediately available.
 869     service.openHatch();
 870
 871     return service;
 872 }])
 873