https://github.com/mozilla/gecko-dev
Tip revision: 5d66f4aa3d6a03913329c1f4cd8275f7369a00e1 authored by Stephen Horlander on 29 July 2013, 22:06:06 UTC
Bug 889417 - Make Firefox 32 x 32 icon fill slightly more space. r=dolske, a=lsblakk
Bug 889417 - Make Firefox 32 x 32 icon fill slightly more space. r=dolske, a=lsblakk
Tip revision: 5d66f4a
storageservice.js
/* This Source Code Form is subject to the terms of the Mozilla Public
* License, v. 2.0. If a copy of the MPL was not distributed with this file,
* You can obtain one at http://mozilla.org/MPL/2.0/. */
/**
* This file contains APIs for interacting with the Storage Service API.
*
* The specification for the service is available at.
* http://docs.services.mozilla.com/storage/index.html
*
* Nothing about the spec or the service is Sync-specific. And, that is how
* these APIs are implemented. Instead, it is expected that consumers will
* create a new type inheriting or wrapping those provided by this file.
*
* STORAGE SERVICE OVERVIEW
*
* The storage service is effectively a key-value store where each value is a
* well-defined envelope that stores specific metadata along with a payload.
* These values are called Basic Storage Objects, or BSOs. BSOs are organized
* into named groups called collections.
*
* The service also provides ancillary APIs not related to storage, such as
* looking up the set of stored collections, current quota usage, etc.
*/
"use strict";
this.EXPORTED_SYMBOLS = [
"BasicStorageObject",
"StorageServiceClient",
"StorageServiceRequestError",
];
const {classes: Cc, interfaces: Ci, results: Cr, utils: Cu} = Components;
Cu.import("resource://gre/modules/Preferences.jsm");
Cu.import("resource://services-common/async.js");
Cu.import("resource://services-common/log4moz.js");
Cu.import("resource://services-common/rest.js");
Cu.import("resource://services-common/utils.js");
const Prefs = new Preferences("services.common.storageservice.");
/**
* The data type stored in the storage service.
*
* A Basic Storage Object (BSO) is the primitive type stored in the storage
* service. BSO's are simply maps with a well-defined set of keys.
*
* BSOs belong to named collections.
*
* A single BSO consists of the following fields:
*
* id - An identifying string. This is how a BSO is uniquely identified within
* a single collection.
* modified - Integer milliseconds since Unix epoch BSO was modified.
* payload - String contents of BSO. The format of the string is undefined
* (although JSON is typically used).
* ttl - The number of seconds to keep this record.
* sortindex - Integer indicating relative importance of record within the
* collection.
*
* The constructor simply creates an empty BSO having the specified ID (which
* can be null or undefined). It also takes an optional collection. This is
* purely for convenience.
*
* This type is meant to be a dumb container and little more.
*
* @param id
* (string) ID of BSO. Can be null.
* (string) Collection BSO belongs to. Can be null;
*/
this.BasicStorageObject =
function BasicStorageObject(id=null, collection=null) {
this.data = {};
this.id = id;
this.collection = collection;
}
BasicStorageObject.prototype = {
id: null,
collection: null,
data: null,
// At the time this was written, the convention for constructor arguments
// was not adopted by Harmony. It could break in the future. We have test
// coverage that will break if SpiderMonkey changes, just in case.
_validKeys: new Set(["id", "payload", "modified", "sortindex", "ttl"]),
/**
* Get the string payload as-is.
*/
get payload() {
return this.data.payload;
},
/**
* Set the string payload to a new value.
*/
set payload(value) {
this.data.payload = value;
},
/**
* Get the modified time of the BSO in milliseconds since Unix epoch.
*
* You can convert this to a native JS Date instance easily:
*
* let date = new Date(bso.modified);
*/
get modified() {
return this.data.modified;
},
/**
* Sets the modified time of the BSO in milliseconds since Unix epoch.
*
* Please note that if this value is sent to the server it will be ignored.
* The server will use its time at the time of the operation when storing the
* BSO.
*/
set modified(value) {
this.data.modified = value;
},
get sortindex() {
if (this.data.sortindex) {
return this.data.sortindex || 0;
}
return 0;
},
set sortindex(value) {
if (!value && value !== 0) {
delete this.data.sortindex;
return;
}
this.data.sortindex = value;
},
get ttl() {
return this.data.ttl;
},
set ttl(value) {
if (!value && value !== 0) {
delete this.data.ttl;
return;
}
this.data.ttl = value;
},
/**
* Deserialize JSON or another object into this instance.
*
* The argument can be a string containing serialized JSON or an object.
*
* If the JSON is invalid or if the object contains unknown fields, an
* exception will be thrown.
*
* @param json
* (string|object) Value to construct BSO from.
*/
deserialize: function deserialize(input) {
let data;
if (typeof(input) == "string") {
data = JSON.parse(input);
if (typeof(data) != "object") {
throw new Error("Supplied JSON is valid but is not a JS-Object.");
}
}
else if (typeof(input) == "object") {
data = input;
} else {
throw new Error("Argument must be a JSON string or object: " +
typeof(input));
}
for each (let key in Object.keys(data)) {
if (key == "id") {
this.id = data.id;
continue;
}
if (!this._validKeys.has(key)) {
throw new Error("Invalid key in object: " + key);
}
this.data[key] = data[key];
}
},
/**
* Serialize the current BSO to JSON.
*
* @return string
* The JSON representation of this BSO.
*/
toJSON: function toJSON() {
let obj = {};
for (let [k, v] in Iterator(this.data)) {
obj[k] = v;
}
if (this.id) {
obj.id = this.id;
}
return obj;
},
toString: function toString() {
return "{ " +
"id: " + this.id + " " +
"modified: " + this.modified + " " +
"ttl: " + this.ttl + " " +
"index: " + this.sortindex + " " +
"payload: " + this.payload +
" }";
},
};
/**
* Represents an error encountered during a StorageServiceRequest request.
*
* Instances of this will be passed to the onComplete callback for any request
* that did not succeed.
*
* This type effectively wraps other error conditions. It is up to the client
* to determine the appropriate course of action for each error type
* encountered.
*
* The following error "classes" are defined by properties on each instance:
*
* serverModified - True if the request to modify data was conditional and
* the server rejected the request because it has newer data than the
* client.
*
* notFound - True if the requested URI or resource does not exist.
*
* conflict - True if the server reported that a resource being operated on
* was in conflict. If this occurs, the client should typically wait a
* little and try the request again.
*
* requestTooLarge - True if the request was too large for the server. If
* this happens on batch requests, the client should retry the request with
* smaller batches.
*
* network - A network error prevented this request from succeeding. If set,
* it will be an Error thrown by the Gecko network stack. If set, it could
* mean that the request could not be performed or that an error occurred
* when the request was in flight. It is also possible the request
* succeeded on the server but the response was lost in transit.
*
* authentication - If defined, an authentication error has occurred. If
* defined, it will be an Error instance. If seen, the client should not
* retry the request without first correcting the authentication issue.
*
* client - An error occurred which was the client's fault. This typically
* means the code in this file is buggy.
*
* server - An error occurred on the server. In the ideal world, this should
* never happen. But, it does. If set, this will be an Error which
* describes the error as reported by the server.
*/
this.StorageServiceRequestError = function StorageServiceRequestError() {
this.serverModified = false;
this.notFound = false;
this.conflict = false;
this.requestToolarge = false;
this.network = null;
this.authentication = null;
this.client = null;
this.server = null;
}
/**
* Represents a single request to the storage service.
*
* Instances of this type are returned by the APIs on StorageServiceClient.
* They should not be created outside of StorageServiceClient.
*
* This type encapsulates common storage API request and response handling.
* Metadata required to perform the request is stored inside each instance and
* should be treated as invisible by consumers.
*
* A number of "public" properties are exposed to allow clients to further
* customize behavior. These are documented below.
*
* Some APIs in StorageServiceClient define their own types which inherit from
* this one. Read the API documentation to see which types those are and when
* they apply.
*
* This type wraps RESTRequest rather than extending it. The reason is mainly
* to avoid the fragile base class problem. We implement considerable extra
* functionality on top of RESTRequest and don't want this to accidentally
* trample on RESTRequest's members.
*
* If this were a C++ class, it and StorageServiceClient would be friend
* classes. Each touches "protected" APIs of the other. Thus, each should be
* considered when making changes to the other.
*
* Usage
* =====
*
* When you obtain a request instance, it is waiting to be dispatched. It may
* have additional settings available for tuning. See the documentation in
* StorageServiceClient for more.
*
* There are essentially two types of requests: "basic" and "streaming."
* "Basic" requests encapsulate the traditional request-response paradigm:
* a request is issued and we get a response later once the full response
* is available. Most of the APIs in StorageServiceClient issue these "basic"
* requests. Streaming requests typically involve the transport of multiple
* BasicStorageObject instances. When a new BSO instance is available, a
* callback is fired.
*
* For basic requests, the general flow looks something like:
*
* // Obtain a new request instance.
* let request = client.getCollectionInfo();
*
* // Install a handler which provides callbacks for request events. The most
* // important is `onComplete`, which is called when the request has
* // finished and the response is completely received.
* request.handler = {
* onComplete: function onComplete(error, request) {
* // Do something.
* }
* };
*
* // Send the request.
* request.dispatch();
*
* Alternatively, we can install the onComplete handler when calling dispatch:
*
* let request = client.getCollectionInfo();
* request.dispatch(function onComplete(error, request) {
* // Handle response.
* });
*
* Please note that installing an `onComplete` handler as the argument to
* `dispatch()` will overwrite an existing `handler`.
*
* In both of the above example, the two `request` variables are identical. The
* original `StorageServiceRequest` is passed into the callback so callers
* don't need to rely on closures.
*
* Most of the complexity for onComplete handlers is error checking.
*
* The first thing you do in your onComplete handler is ensure no error was
* seen:
*
* function onComplete(error, request) {
* if (error) {
* // Handle error.
* }
* }
*
* If `error` is defined, it will be an instance of
* `StorageServiceRequestError`. An error will be set if the request didn't
* complete successfully. This means the transport layer must have succeeded
* and the application protocol (HTTP) must have returned a successful status
* code (2xx and some 3xx). Please see the documentation for
* `StorageServiceRequestError` for more.
*
* A robust error handler would look something like:
*
* function onComplete(error, request) {
* if (error) {
* if (error.network) {
* // Network error encountered!
* } else if (error.server) {
* // Something went wrong on the server (HTTP 5xx).
* } else if (error.authentication) {
* // Server rejected request due to bad credentials.
* } else if (error.serverModified) {
* // The conditional request was rejected because the server has newer
* // data than what the client reported.
* } else if (error.conflict) {
* // The server reported that the operation could not be completed
* // because another client is also updating it.
* } else if (error.requestTooLarge) {
* // The server rejected the request because it was too large.
* } else if (error.notFound) {
* // The requested resource was not found.
* } else if (error.client) {
* // Something is wrong with the client's request. You should *never*
* // see this, as it means this client is likely buggy. It could also
* // mean the server is buggy or misconfigured. Either way, something
* // is buggy.
* }
*
* return;
* }
*
* // Handle successful case.
* }
*
* If `error` is null, the request completed successfully. There may or may not
* be additional data available on the request instance.
*
* For requests that obtain data, this data is typically made available through
* the `resultObj` property on the request instance. The API that was called
* will install its own response hander and ensure this property is decoded to
* what you expect.
*
* Conditional Requests
* --------------------
*
* Many of the APIs on `StorageServiceClient` support conditional requests.
* That is, the client defines the last version of data it has (the version
* comes from a previous response from the server) and sends this as part of
* the request.
*
* For query requests, if the server hasn't changed, no new data will be
* returned. If issuing a conditional query request, the caller should check
* the `notModified` property on the request in the response callback. If this
* property is true, the server has no new data and there is obviously no data
* on the response.
*
* For example:
*
* let request = client.getCollectionInfo();
* request.locallyModifiedVersion = Date.now() - 60000;
* request.dispatch(function onComplete(error, request) {
* if (error) {
* // Handle error.
* return;
* }
*
* if (request.notModified) {
* return;
* }
*
* let info = request.resultObj;
* // Do stuff.
* });
*
* For modification requests, if the server has changed, the request will be
* rejected. When this happens, `error`will be defined and the `serverModified`
* property on it will be true.
*
* For example:
*
* let request = client.setBSO(bso);
* request.locallyModifiedVersion = bso.modified;
* request.dispatch(function onComplete(error, request) {
* if (error) {
* if (error.serverModified) {
* // Server data is newer! We should probably fetch it and apply
* // locally.
* }
*
* return;
* }
*
* // Handle success.
* });
*
* Future Features
* ---------------
*
* The current implementation does not support true streaming for things like
* multi-BSO retrieval. However, the API supports it, so we should be able
* to implement it transparently.
*/
function StorageServiceRequest() {
this._log = Log4Moz.repository.getLogger("Sync.StorageService.Request");
this._log.level = Log4Moz.Level[Prefs.get("log.level")];
this.notModified = false;
this._client = null;
this._request = null;
this._method = null;
this._handler = {};
this._data = null;
this._error = null;
this._resultObj = null;
this._locallyModifiedVersion = null;
this._allowIfModified = false;
this._allowIfUnmodified = false;
}
StorageServiceRequest.prototype = {
/**
* The StorageServiceClient this request came from.
*/
get client() {
return this._client;
},
/**
* The underlying RESTRequest instance.
*
* This should be treated as read only and should not be modified
* directly by external callers. While modification would probably work, this
* would defeat the purpose of the API and the abstractions it is meant to
* provide.
*
* If a consumer needs to modify the underlying request object, it is
* recommended for them to implement a new type that inherits from
* StorageServiceClient and override the necessary APIs to modify the request
* there.
*
* This accessor may disappear in future versions.
*/
get request() {
return this._request;
},
/**
* The RESTResponse that resulted from the RESTRequest.
*/
get response() {
return this._request.response;
},
/**
* HTTP status code from response.
*/
get statusCode() {
let response = this.response;
return response ? response.status : null;
},
/**
* Holds any error that has occurred.
*
* If a network error occurred, that will be returned. If no network error
* occurred, the client error will be returned. If no error occurred (yet),
* null will be returned.
*/
get error() {
return this._error;
},
/**
* The result from the request.
*
* This stores the object returned from the server. The type of object depends
* on the request type. See the per-API documentation in StorageServiceClient
* for details.
*/
get resultObj() {
return this._resultObj;
},
/**
* Define the local version of the entity the client has.
*
* This is used to enable conditional requests. Depending on the request
* type, the value set here could be reflected in the X-If-Modified-Since or
* X-If-Unmodified-Since headers.
*
* This attribute is not honoured on every request. See the documentation
* in the client API to learn where it is valid.
*/
set locallyModifiedVersion(value) {
// Will eventually become a header, so coerce to string.
this._locallyModifiedVersion = "" + value;
},
/**
* Object which holds callbacks and state for this request.
*
* The handler is installed by users of this request. It is simply an object
* containing 0 or more of the following properties:
*
* onComplete - A function called when the request has completed and all
* data has been received from the server. The function receives the
* following arguments:
*
* (StorageServiceRequestError) Error encountered during request. null
* if no error was encountered.
* (StorageServiceRequest) The request that was sent (this instance).
* Response information is available via properties and functions.
*
* Unless the call to dispatch() throws before returning, this callback
* is guaranteed to be invoked.
*
* Every client almost certainly wants to install this handler.
*
* onDispatch - A function called immediately before the request is
* dispatched. This hook can be used to inspect or modify the request
* before it is issued.
*
* The called function receives the following arguments:
*
* (StorageServiceRequest) The request being issued (this request).
*
* onBSORecord - When retrieving multiple BSOs from the server, this
* function is invoked when a new BSO record has been read. This function
* will be invoked 0 to N times before onComplete is invoked. onComplete
* signals that the last BSO has been processed or that an error
* occurred. The function receives the following arguments:
*
* (StorageServiceRequest) The request that was sent (this instance).
* (BasicStorageObject|string) The received BSO instance (when in full
* mode) or the string ID of the BSO (when not in full mode).
*
* Callers are free to (and encouraged) to store extra state in the supplied
* handler.
*/
set handler(value) {
if (typeof(value) != "object") {
throw new Error("Invalid handler. Must be an Object.");
}
this._handler = value;
if (!value.onComplete) {
this._log.warn("Handler does not contain an onComplete callback!");
}
},
get handler() {
return this._handler;
},
//---------------
// General APIs |
//---------------
/**
* Start the request.
*
* The request is dispatched asynchronously. The installed handler will have
* one or more of its callbacks invoked as the state of the request changes.
*
* The `onComplete` argument is optional. If provided, the supplied function
* will be installed on a *new* handler before the request is dispatched. This
* is equivalent to calling:
*
* request.handler = {onComplete: value};
* request.dispatch();
*
* Please note that any existing handler will be replaced if onComplete is
* provided.
*
* @param onComplete
* (function) Callback to be invoked when request has completed.
*/
dispatch: function dispatch(onComplete) {
if (onComplete) {
this.handler = {onComplete: onComplete};
}
// Installing the dummy callback makes implementation easier in _onComplete
// because we can then blindly call.
this._dispatch(function _internalOnComplete(error) {
this._onComplete(error);
this.completed = true;
}.bind(this));
},
/**
* This is a synchronous version of dispatch().
*
* THIS IS AN EVIL FUNCTION AND SHOULD NOT BE CALLED. It is provided for
* legacy reasons to support evil, synchronous clients.
*
* Please note that onComplete callbacks are executed from this JS thread.
* We dispatch the request, spin the event loop until it comes back. Then,
* we execute callbacks ourselves then return. In other words, there is no
* potential for spinning between callback execution and this function
* returning.
*
* The `onComplete` argument has the same behavior as for `dispatch()`.
*
* @param onComplete
* (function) Callback to be invoked when request has completed.
*/
dispatchSynchronous: function dispatchSynchronous(onComplete) {
if (onComplete) {
this.handler = {onComplete: onComplete};
}
let cb = Async.makeSyncCallback();
this._dispatch(cb);
let error = Async.waitForSyncCallback(cb);
this._onComplete(error);
this.completed = true;
},
//-------------------------------------------------------------------------
// HIDDEN APIS. DO NOT CHANGE ANYTHING UNDER HERE FROM OUTSIDE THIS TYPE. |
//-------------------------------------------------------------------------
/**
* Data to include in HTTP request body.
*/
_data: null,
/**
* StorageServiceRequestError encountered during dispatchy.
*/
_error: null,
/**
* Handler to parse response body into another object.
*
* This is installed by the client API. It should return the value the body
* parses to on success. If a failure is encountered, an exception should be
* thrown.
*/
_completeParser: null,
/**
* Dispatch the request.
*
* This contains common functionality for dispatching requests. It should
* ideally be part of dispatch, but since dispatchSynchronous exists, we
* factor out common code.
*/
_dispatch: function _dispatch(onComplete) {
// RESTRequest throws if the request has already been dispatched, so we
// need not bother checking.
// Inject conditional headers into request if they are allowed and if a
// value is set. Note that _locallyModifiedVersion is always a string and
// if("0") is true.
if (this._allowIfModified && this._locallyModifiedVersion) {
this._log.trace("Making request conditional.");
this._request.setHeader("X-If-Modified-Since",
this._locallyModifiedVersion);
} else if (this._allowIfUnmodified && this._locallyModifiedVersion) {
this._log.trace("Making request conditional.");
this._request.setHeader("X-If-Unmodified-Since",
this._locallyModifiedVersion);
}
// We have both an internal and public hook.
// If these throw, it is OK since we are not in a callback.
if (this._onDispatch) {
this._onDispatch();
}
if (this._handler.onDispatch) {
this._handler.onDispatch(this);
}
this._client.runListeners("onDispatch", this);
this._log.info("Dispatching request: " + this._method + " " +
this._request.uri.asciiSpec);
this._request.dispatch(this._method, this._data, onComplete);
},
/**
* RESTRequest onComplete handler for all requests.
*
* This provides common logic for all response handling.
*/
_onComplete: function(error) {
let onCompleteCalled = false;
let callOnComplete = function callOnComplete() {
onCompleteCalled = true;
if (!this._handler.onComplete) {
this._log.warn("No onComplete installed in handler!");
return;
}
try {
this._handler.onComplete(this._error, this);
} catch (ex) {
this._log.warn("Exception when invoking handler's onComplete: " +
CommonUtils.exceptionStr(ex));
throw ex;
}
}.bind(this);
try {
if (error) {
this._error = new StorageServiceRequestError();
this._error.network = error;
this._log.info("Network error during request: " + error);
this._client.runListeners("onNetworkError", this._client, this, error);
callOnComplete();
return;
}
let response = this._request.response;
this._log.info(response.status + " " + this._request.uri.asciiSpec);
this._processHeaders();
if (response.status == 200) {
this._resultObj = this._completeParser(response);
callOnComplete();
return;
}
if (response.status == 201) {
callOnComplete();
return;
}
if (response.status == 204) {
callOnComplete();
return;
}
if (response.status == 304) {
this.notModified = true;
callOnComplete();
return;
}
// TODO handle numeric response code from server.
if (response.status == 400) {
this._error = new StorageServiceRequestError();
this._error.client = new Error("Client error!");
callOnComplete();
return;
}
if (response.status == 401) {
this._error = new StorageServiceRequestError();
this._error.authentication = new Error("401 Received.");
this._client.runListeners("onAuthFailure", this._error.authentication,
this);
callOnComplete();
return;
}
if (response.status == 404) {
this._error = new StorageServiceRequestError();
this._error.notFound = true;
callOnComplete();
return;
}
if (response.status == 409) {
this._error = new StorageServiceRequestError();
this._error.conflict = true;
callOnComplete();
return;
}
if (response.status == 412) {
this._error = new StorageServiceRequestError();
this._error.serverModified = true;
callOnComplete();
return;
}
if (response.status == 413) {
this._error = new StorageServiceRequestError();
this._error.requestTooLarge = true;
callOnComplete();
return;
}
// If we see this, either the client or the server is buggy. We should
// never see this.
if (response.status == 415) {
this._log.error("415 HTTP response seen from server! This should " +
"never happen!");
this._error = new StorageServiceRequestError();
this._error.client = new Error("415 Unsupported Media Type received!");
callOnComplete();
return;
}
if (response.status >= 500 && response.status <= 599) {
this._log.error(response.status + " seen from server!");
this._error = new StorageServiceRequestError();
this._error.server = new Error(response.status + " status code.");
callOnComplete();
return;
}
callOnComplete();
} catch (ex) {
this._clientError = ex;
this._log.info("Exception when processing _onComplete: " + ex);
if (!onCompleteCalled) {
this._log.warn("Exception in internal response handling logic!");
try {
callOnComplete();
} catch (ex) {
this._log.warn("An additional exception was encountered when " +
"calling the handler's onComplete: " + ex);
}
}
}
},
_processHeaders: function _processHeaders() {
let headers = this._request.response.headers;
if (headers["x-timestamp"]) {
this.serverTime = parseFloat(headers["x-timestamp"]);
}
if (headers["x-backoff"]) {
this.backoffInterval = 1000 * parseInt(headers["x-backoff"], 10);
}
if (headers["retry-after"]) {
this.backoffInterval = 1000 * parseInt(headers["retry-after"], 10);
}
if (this.backoffInterval) {
let failure = this._request.response.status == 503;
this._client.runListeners("onBackoffReceived", this._client, this,
this.backoffInterval, !failure);
}
if (headers["x-quota-remaining"]) {
this.quotaRemaining = parseInt(headers["x-quota-remaining"], 10);
this._client.runListeners("onQuotaRemaining", this._client, this,
this.quotaRemaining);
}
},
};
/**
* Represents a request to fetch from a collection.
*
* These requests are highly configurable so they are given their own type.
* This type inherits from StorageServiceRequest and provides additional
* controllable parameters.
*
* By default, requests are issued in "streaming" mode. As the client receives
* data from the server, it will invoke the caller-supplied onBSORecord
* callback for each record as it is ready. When all records have been received,
* it will invoke onComplete as normal. To change this behavior, modify the
* "streaming" property before the request is dispatched.
*/
function StorageCollectionGetRequest() {
StorageServiceRequest.call(this);
}
StorageCollectionGetRequest.prototype = {
__proto__: StorageServiceRequest.prototype,
_namedArgs: {},
_streaming: true,
/**
* Control whether streaming mode is in effect.
*
* Read the type documentation above for more details.
*/
set streaming(value) {
this._streaming = !!value;
},
/**
* Define the set of IDs to fetch from the server.
*/
set ids(value) {
this._namedArgs.ids = value.join(",");
},
/**
* Only retrieve BSOs that were modified strictly before this time.
*
* Defined in milliseconds since UNIX epoch.
*/
set older(value) {
this._namedArgs.older = value;
},
/**
* Only retrieve BSOs that were modified strictly after this time.
*
* Defined in milliseconds since UNIX epoch.
*/
set newer(value) {
this._namedArgs.newer = value;
},
/**
* If set to a truthy value, return full BSO information.
*
* If not set (the default), the request will only return the set of BSO
* ids.
*/
set full(value) {
if (value) {
this._namedArgs.full = "1";
} else {
delete this._namedArgs["full"];
}
},
/**
* Limit the max number of returned BSOs to this integer number.
*/
set limit(value) {
this._namedArgs.limit = value;
},
/**
* If set with any value, sort the results based on modification time, oldest
* first.
*/
set sortOldest(value) {
this._namedArgs.sort = "oldest";
},
/**
* If set with any value, sort the results based on modification time, newest
* first.
*/
set sortNewest(value) {
this._namedArgs.sort = "newest";
},
/**
* If set with any value, sort the results based on sortindex value, highest
* first.
*/
set sortIndex(value) {
this._namedArgs.sort = "index";
},
_onDispatch: function _onDispatch() {
let qs = this._getQueryString();
if (!qs.length) {
return;
}
this._request.uri = CommonUtils.makeURI(this._request.uri.asciiSpec + "?" +
qs);
},
_getQueryString: function _getQueryString() {
let args = [];
for (let [k, v] in Iterator(this._namedArgs)) {
args.push(encodeURIComponent(k) + "=" + encodeURIComponent(v));
}
return args.join("&");
},
_completeParser: function _completeParser(response) {
let obj = JSON.parse(response.body);
let items = obj.items;
if (!Array.isArray(items)) {
throw new Error("Unexpected JSON response. items is missing or not an " +
"array!");
}
if (!this.handler.onBSORecord) {
return;
}
for (let bso of items) {
this.handler.onBSORecord(this, bso);
}
},
};
/**
* Represents a request that sets data in a collection
*
* Instances of this type are returned by StorageServiceClient.setBSOs().
*/
function StorageCollectionSetRequest() {
StorageServiceRequest.call(this);
this.size = 0;
// TODO Bug 775781 convert to Set and Map once iterable.
this.successfulIDs = [];
this.failures = {};
this._lines = [];
}
StorageCollectionSetRequest.prototype = {
__proto__: StorageServiceRequest.prototype,
get count() {
return this._lines.length;
},
/**
* Add a BasicStorageObject to this request.
*
* Please note that the BSO content is retrieved when the BSO is added to
* the request. If the BSO changes after it is added to a request, those
* changes will not be reflected in the request.
*
* @param bso
* (BasicStorageObject) BSO to add to the request.
*/
addBSO: function addBSO(bso) {
if (!bso instanceof BasicStorageObject) {
throw new Error("argument must be a BasicStorageObject instance.");
}
if (!bso.id) {
throw new Error("Passed BSO must have id defined.");
}
this.addLine(JSON.stringify(bso));
},
/**
* Add a BSO (represented by its serialized newline-delimited form).
*
* You probably shouldn't use this. It is used for batching.
*/
addLine: function addLine(line) {
// This is off by 1 in the larger direction. We don't care.
this.size += line.length + 1;
this._lines.push(line);
},
_onDispatch: function _onDispatch() {
this._data = this._lines.join("\n");
this.size = this._data.length;
},
_completeParser: function _completeParser(response) {
let result = JSON.parse(response.body);
for (let id of result.success) {
this.successfulIDs.push(id);
}
this.allSucceeded = true;
for (let [id, reasons] in Iterator(result.failed)) {
this.failures[id] = reasons;
this.allSucceeded = false;
}
},
};
/**
* Represents a batch upload of BSOs to an individual collection.
*
* This is a more intelligent way to upload may BSOs to the server. It will
* split the uploaded data into multiple requests so size limits, etc aren't
* exceeded.
*
* Once a client obtains an instance of this type, it calls `addBSO` for each
* BSO to be uploaded. When the client is done providing BSOs to be uploaded,
* it calls `finish`. When `finish` is called, no more BSOs can be added to the
* batch. When all requests created from this batch have finished, the callback
* provided to `finish` will be invoked.
*
* Clients can also explicitly flush pending outgoing BSOs via `flush`. This
* allows callers to control their own batching/chunking.
*
* Interally, this maintains a queue of StorageCollectionSetRequest to be
* issued. At most one request is allowed to be in-flight at once. This is to
* avoid potential conflicts on the server. And, in the case of conditional
* requests, it prevents requests from being declined due to the server being
* updated by another request issued by us.
*
* If a request errors for any reason, all queued uploads are abandoned and the
* `finish` callback is invoked as soon as possible. The `successfulIDs` and
* `failures` properties will contain data from all requests that had this
* response data. In other words, the IDs have BSOs that were never sent to the
* server are not lumped in to either property.
*
* Requests can be made conditional by setting `locallyModifiedVersion` to the
* most recent version of server data. As responses from the server are seen,
* the last server version is carried forward to subsequent requests.
*
* The server version from the last request is available in the
* `serverModifiedVersion` property. It should only be accessed during or
* after the callback passed to `finish`.
*
* @param client
* (StorageServiceClient) Client instance to use for uploading.
*
* @param collection
* (string) Collection the batch operation will upload to.
*/
function StorageCollectionBatchedSet(client, collection) {
this.client = client;
this.collection = collection;
this._log = client._log;
this.locallyModifiedVersion = null;
this.serverModifiedVersion = null;
// TODO Bug 775781 convert to Set and Map once iterable.
this.successfulIDs = [];
this.failures = {};
// Request currently being populated.
this._stagingRequest = client.setBSOs(this.collection);
// Requests ready to be sent over the wire.
this._outgoingRequests = [];
// Whether we are waiting for a response.
this._requestInFlight = false;
this._onFinishCallback = null;
this._finished = false;
this._errorEncountered = false;
}
StorageCollectionBatchedSet.prototype = {
/**
* Add a BSO to be uploaded as part of this batch.
*/
addBSO: function addBSO(bso) {
if (this._errorEncountered) {
return;
}
let line = JSON.stringify(bso);
if (line.length > this.client.REQUEST_SIZE_LIMIT) {
throw new Error("BSO is larger than allowed limit: " + line.length +
" > " + this.client.REQUEST_SIZE_LIMIT);
}
if (this._stagingRequest.size + line.length > this.client.REQUEST_SIZE_LIMIT) {
this._log.debug("Sending request because payload size would be exceeded");
this._finishStagedRequest();
this._stagingRequest.addLine(line);
return;
}
// We are guaranteed to fit within size limits.
this._stagingRequest.addLine(line);
if (this._stagingRequest.count >= this.client.REQUEST_BSO_COUNT_LIMIT) {
this._log.debug("Sending request because BSO count threshold reached.");
this._finishStagedRequest();
return;
}
},
finish: function finish(cb) {
if (this._finished) {
throw new Error("Batch request has already been finished.");
}
this.flush();
this._onFinishCallback = cb;
this._finished = true;
this._stagingRequest = null;
},
flush: function flush() {
if (this._finished) {
throw new Error("Batch request has been finished.");
}
if (!this._stagingRequest.count) {
return;
}
this._finishStagedRequest();
},
_finishStagedRequest: function _finishStagedRequest() {
this._outgoingRequests.push(this._stagingRequest);
this._sendOutgoingRequest();
this._stagingRequest = this.client.setBSOs(this.collection);
},
_sendOutgoingRequest: function _sendOutgoingRequest() {
if (this._requestInFlight || this._errorEncountered) {
return;
}
if (!this._outgoingRequests.length) {
return;
}
let request = this._outgoingRequests.shift();
if (this.locallyModifiedVersion) {
request.locallyModifiedVersion = this.locallyModifiedVersion;
}
request.dispatch(this._onBatchComplete.bind(this));
this._requestInFlight = true;
},
_onBatchComplete: function _onBatchComplete(error, request) {
this._requestInFlight = false;
this.serverModifiedVersion = request.serverTime;
// Only update if we had a value before. Otherwise, this breaks
// unconditional requests!
if (this.locallyModifiedVersion) {
this.locallyModifiedVersion = request.serverTime;
}
for (let id of request.successfulIDs) {
this.successfulIDs.push(id);
}
for (let [id, reason] in Iterator(request.failures)) {
this.failures[id] = reason;
}
if (request.error) {
this._errorEncountered = true;
}
this._checkFinish();
},
_checkFinish: function _checkFinish() {
if (this._outgoingRequests.length && !this._errorEncountered) {
this._sendOutgoingRequest();
return;
}
if (!this._onFinishCallback) {
return;
}
try {
this._onFinishCallback(this);
} catch (ex) {
this._log.warn("Exception when calling finished callback: " +
CommonUtils.exceptionStr(ex));
}
},
};
Object.freeze(StorageCollectionBatchedSet.prototype);
/**
* Manages a batch of BSO deletion requests.
*
* A single instance of this virtual request allows deletion of many individual
* BSOs without having to worry about server limits.
*
* Instances are obtained by calling `deleteBSOsBatching` on
* StorageServiceClient.
*
* Usage is roughly the same as StorageCollectionBatchedSet. Callers obtain
* an instance and select individual BSOs for deletion by calling `addID`.
* When the caller is finished marking BSOs for deletion, they call `finish`
* with a callback which will be invoked when all deletion requests finish.
*
* When the finished callback is invoked, any encountered errors will be stored
* in the `errors` property of this instance (which is passed to the callback).
* This will be an empty array if no errors were encountered. Else, it will
* contain the errors from the `onComplete` handler of request instances. The
* set of succeeded and failed IDs is not currently available.
*
* Deletes can be made conditional by setting `locallyModifiedVersion`. The
* behavior is the same as request types. The only difference is that the
* updated version from the server as a result of requests is carried forward
* to subsequent requests.
*
* The server version from the last request is stored in the
* `serverModifiedVersion` property. It is not safe to access this until the
* callback from `finish`.
*
* Like StorageCollectionBatchedSet, requests are issued serially to avoid
* race conditions on the server.
*
* @param client
* (StorageServiceClient) Client request is associated with.
* @param collection
* (string) Collection being operated on.
*/
function StorageCollectionBatchedDelete(client, collection) {
this.client = client;
this.collection = collection;
this._log = client._log;
this.locallyModifiedVersion = null;
this.serverModifiedVersion = null;
this.errors = [];
this._pendingIDs = [];
this._requestInFlight = false;
this._finished = false;
this._finishedCallback = null;
}
StorageCollectionBatchedDelete.prototype = {
addID: function addID(id) {
if (this._finished) {
throw new Error("Cannot add IDs to a finished instance.");
}
// If we saw errors already, don't do any work. This is an optimization
// and isn't strictly required, as _sendRequest() should no-op.
if (this.errors.length) {
return;
}
this._pendingIDs.push(id);
if (this._pendingIDs.length >= this.client.REQUEST_BSO_DELETE_LIMIT) {
this._sendRequest();
}
},
/**
* Finish this batch operation.
*
* No more IDs can be added to this operation. Existing IDs are flushed as
* a request. The passed callback will be called when all requests have
* finished.
*/
finish: function finish(cb) {
if (this._finished) {
throw new Error("Batch delete instance has already been finished.");
}
this._finished = true;
this._finishedCallback = cb;
if (this._pendingIDs.length) {
this._sendRequest();
}
},
_sendRequest: function _sendRequest() {
// Only allow 1 active request at a time and don't send additional
// requests if one has failed.
if (this._requestInFlight || this.errors.length) {
return;
}
let ids = this._pendingIDs.splice(0, this.client.REQUEST_BSO_DELETE_LIMIT);
let request = this.client.deleteBSOs(this.collection, ids);
if (this.locallyModifiedVersion) {
request.locallyModifiedVersion = this.locallyModifiedVersion;
}
request.dispatch(this._onRequestComplete.bind(this));
this._requestInFlight = true;
},
_onRequestComplete: function _onRequestComplete(error, request) {
this._requestInFlight = false;
if (error) {
// We don't currently track metadata of what failed. This is an obvious
// feature that could be added.
this._log.warn("Error received from server: " + error);
this.errors.push(error);
}
this.serverModifiedVersion = request.serverTime;
// If performing conditional requests, carry forward the new server version
// so subsequent conditional requests work.
if (this.locallyModifiedVersion) {
this.locallyModifiedVersion = request.serverTime;
}
if (this._pendingIDs.length && !this.errors.length) {
this._sendRequest();
return;
}
if (!this._finishedCallback) {
return;
}
try {
this._finishedCallback(this);
} catch (ex) {
this._log.warn("Exception when invoking finished callback: " +
CommonUtils.exceptionStr(ex));
}
},
};
Object.freeze(StorageCollectionBatchedDelete.prototype);
/**
* Construct a new client for the SyncStorage API, version 2.0.
*
* Clients are constructed against a base URI. This URI is typically obtained
* from the token server via the endpoint component of a successful token
* response.
*
* The purpose of this type is to serve as a middleware between a client's core
* logic and the HTTP API. It hides the details of how the storage API is
* implemented but exposes important events, such as when auth goes bad or the
* server requests the client to back off.
*
* All request APIs operate by returning a StorageServiceRequest instance. The
* caller then installs the appropriate callbacks on each instance and then
* dispatches the request.
*
* Each client instance also serves as a controller and coordinator for
* associated requests. Callers can install listeners for common events on the
* client and take the appropriate action whenever any associated request
* observes them. For example, you will only need to register one listener for
* backoff observation as opposed to one on each request.
*
* While not currently supported, a future goal of this type is to support
* more advanced transport channels - such as SPDY - to allow for faster and
* more efficient API calls. The API is thus designed to abstract transport
* specifics away from the caller.
*
* Storage API consumers almost certainly have added functionality on top of the
* storage service. It is encouraged to create a child type which adds
* functionality to this layer.
*
* @param baseURI
* (string) Base URI for all requests.
*/
this.StorageServiceClient = function StorageServiceClient(baseURI) {
this._log = Log4Moz.repository.getLogger("Services.Common.StorageServiceClient");
this._log.level = Log4Moz.Level[Prefs.get("log.level")];
this._baseURI = baseURI;
if (this._baseURI[this._baseURI.length-1] != "/") {
this._baseURI += "/";
}
this._log.info("Creating new StorageServiceClient under " + this._baseURI);
this._listeners = [];
}
StorageServiceClient.prototype = {
/**
* The user agent sent with every request.
*
* You probably want to change this.
*/
userAgent: "StorageServiceClient",
/**
* Maximum size of entity bodies.
*
* TODO this should come from the server somehow. See bug 769759.
*/
REQUEST_SIZE_LIMIT: 512000,
/**
* Maximum number of BSOs in requests.
*
* TODO this should come from the server somehow. See bug 769759.
*/
REQUEST_BSO_COUNT_LIMIT: 100,
/**
* Maximum number of BSOs that can be deleted in a single DELETE.
*
* TODO this should come from the server. See bug 769759.
*/
REQUEST_BSO_DELETE_LIMIT: 100,
_baseURI: null,
_log: null,
_listeners: null,
//----------------------------
// Event Listener Management |
//----------------------------
/**
* Adds a listener to this client instance.
*
* Listeners allow other parties to react to and influence execution of the
* client instance.
*
* An event listener is simply an object that exposes functions which get
* executed during client execution. Objects can expose 0 or more of the
* following keys:
*
* onDispatch - Callback notified immediately before a request is
* dispatched. This gets called for every outgoing request. The function
* receives as its arguments the client instance and the outgoing
* StorageServiceRequest. This listener is useful for global
* authentication handlers, which can modify the request before it is
* sent.
*
* onAuthFailure - This is called when any request has experienced an
* authentication failure.
*
* This callback receives the following arguments:
*
* (StorageServiceClient) Client that encountered the auth failure.
* (StorageServiceRequest) Request that encountered the auth failure.
*
* onBackoffReceived - This is called when a backoff request is issued by
* the server. Backoffs are issued either when the service is completely
* unavailable (and the client should abort all activity) or if the server
* is under heavy load (and has completed the current request but is
* asking clients to be kind and stop issuing requests for a while).
*
* This callback receives the following arguments:
*
* (StorageServiceClient) Client that encountered the backoff.
* (StorageServiceRequest) Request that received the backoff.
* (number) Integer milliseconds the server is requesting us to back off
* for.
* (bool) Whether the request completed successfully. If false, the
* client should cease sending additional requests immediately, as
* they will likely fail. If true, the client is allowed to continue
* to put the server in a proper state. But, it should stop and heed
* the backoff as soon as possible.
*
* onNetworkError - This is called for every network error that is
* encountered.
*
* This callback receives the following arguments:
*
* (StorageServiceClient) Client that encountered the network error.
* (StorageServiceRequest) Request that encountered the error.
* (Error) Error passed in to RESTRequest's onComplete handler. It has
* a result property, which is a Components.Results enumeration.
*
* onQuotaRemaining - This is called if any request sees updated quota
* information from the server. This provides an update mechanism so
* listeners can immediately find out quota changes as soon as they
* are made.
*
* This callback receives the following arguments:
*
* (StorageServiceClient) Client that encountered the quota change.
* (StorageServiceRequest) Request that received the quota change.
* (number) Integer number of kilobytes remaining for the user.
*/
addListener: function addListener(listener) {
if (!listener) {
throw new Error("listener argument must be an object.");
}
if (this._listeners.indexOf(listener) != -1) {
return;
}
this._listeners.push(listener);
},
/**
* Remove a previously-installed listener.
*/
removeListener: function removeListener(listener) {
this._listeners = this._listeners.filter(function(a) {
return a != listener;
});
},
/**
* Invoke listeners for a specific event.
*
* @param name
* (string) The name of the listener to invoke.
* @param args
* (array) Arguments to pass to listener functions.
*/
runListeners: function runListeners(name, ...args) {
for (let listener of this._listeners) {
try {
if (name in listener) {
listener[name].apply(listener, args);
}
} catch (ex) {
this._log.warn("Listener threw an exception during " + name + ": "
+ ex);
}
}
},
//-----------------------------
// Information/Metadata APIs |
//-----------------------------
/**
* Obtain a request that fetches collection info.
*
* On successful response, the result is placed in the resultObj property
* of the request object.
*
* The result value is a map of strings to numbers. The string keys represent
* collection names. The number values are integer milliseconds since Unix
* epoch that hte collection was last modified.
*
* This request can be made conditional by defining `locallyModifiedVersion`
* on the returned object to the last known version on the client.
*
* Example Usage:
*
* let request = client.getCollectionInfo();
* request.dispatch(function onComplete(error, request) {
* if (!error) {
* return;
* }
*
* for (let [collection, milliseconds] in Iterator(this.resultObj)) {
* // ...
* }
* });
*/
getCollectionInfo: function getCollectionInfo() {
return this._getJSONGETRequest("info/collections");
},
/**
* Fetch quota information.
*
* The result in the callback upon success is a map containing quota
* metadata. It will have the following keys:
*
* usage - Number of bytes currently utilized.
* quota - Number of bytes available to account.
*
* The request can be made conditional by populating `locallyModifiedVersion`
* on the returned request instance with the most recently known version of
* server data.
*/
getQuota: function getQuota() {
return this._getJSONGETRequest("info/quota");
},
/**
* Fetch information on how much data each collection uses.
*
* The result on success is a map of strings to numbers. The string keys
* are collection names. The values are numbers corresponding to the number
* of kilobytes used by that collection.
*/
getCollectionUsage: function getCollectionUsage() {
return this._getJSONGETRequest("info/collection_usage");
},
/**
* Fetch the number of records in each collection.
*
* The result on success is a map of strings to numbers. The string keys are
* collection names. The values are numbers corresponding to the integer
* number of items in that collection.
*/
getCollectionCounts: function getCollectionCounts() {
return this._getJSONGETRequest("info/collection_counts");
},
//--------------------------
// Collection Interaction |
// -------------------------
/**
* Obtain a request to fetch collection information.
*
* The returned request instance is a StorageCollectionGetRequest instance.
* This is a sub-type of StorageServiceRequest and offers a number of setters
* to control how the request is performed. See the documentation for that
* type for more.
*
* The request can be made conditional by setting `locallyModifiedVersion`
* on the returned request instance.
*
* Example usage:
*
* let request = client.getCollection("testcoll");
*
* // Obtain full BSOs rather than just IDs.
* request.full = true;
*
* // Only obtain BSOs modified in the last minute.
* request.newer = Date.now() - 60000;
*
* // Install handler.
* request.handler = {
* onBSORecord: function onBSORecord(request, bso) {
* let id = bso.id;
* let payload = bso.payload;
*
* // Do something with BSO.
* },
*
* onComplete: function onComplete(error, req) {
* if (error) {
* // Handle error.
* return;
* }
*
* // Your onBSORecord handler has processed everything. Now is where
* // you typically signal that everything has been processed and to move
* // on.
* }
* };
*
* request.dispatch();
*
* @param collection
* (string) Name of collection to operate on.
*/
getCollection: function getCollection(collection) {
if (!collection) {
throw new Error("collection argument must be defined.");
}
let uri = this._baseURI + "storage/" + collection;
let request = this._getRequest(uri, "GET", {
accept: "application/json",
allowIfModified: true,
requestType: StorageCollectionGetRequest
});
return request;
},
/**
* Fetch a single Basic Storage Object (BSO).
*
* On success, the BSO may be available in the resultObj property of the
* request as a BasicStorageObject instance.
*
* The request can be made conditional by setting `locallyModifiedVersion`
* on the returned request instance.*
*
* Example usage:
*
* let request = client.getBSO("meta", "global");
* request.dispatch(function onComplete(error, request) {
* if (!error) {
* return;
* }
*
* if (request.notModified) {
* return;
* }
*
* let bso = request.bso;
* let payload = bso.payload;
*
* ...
* };
*
* @param collection
* (string) Collection to fetch from
* @param id
* (string) ID of BSO to retrieve.
* @param type
* (constructor) Constructor to call to create returned object. This
* is optional and defaults to BasicStorageObject.
*/
getBSO: function fetchBSO(collection, id, type=BasicStorageObject) {
if (!collection) {
throw new Error("collection argument must be defined.");
}
if (!id) {
throw new Error("id argument must be defined.");
}
let uri = this._baseURI + "storage/" + collection + "/" + id;
return this._getRequest(uri, "GET", {
accept: "application/json",
allowIfModified: true,
completeParser: function completeParser(response) {
let record = new type(id, collection);
record.deserialize(response.body);
return record;
},
});
},
/**
* Add or update a BSO in a collection.
*
* To make the request conditional (i.e. don't allow server changes if the
* server has a newer version), set request.locallyModifiedVersion to the
* last known version of the BSO. While this could be done automatically by
* this API, it is intentionally omitted because there are valid conditions
* where a client may wish to forcefully update the server.
*
* If a conditional request fails because the server has newer data, the
* StorageServiceRequestError passed to the callback will have the
* `serverModified` property set to true.
*
* Example usage:
*
* let bso = new BasicStorageObject("foo", "coll");
* bso.payload = "payload";
* bso.modified = Date.now();
*
* let request = client.setBSO(bso);
* request.locallyModifiedVersion = bso.modified;
*
* request.dispatch(function onComplete(error, req) {
* if (error) {
* if (error.serverModified) {
* // Handle conditional set failure.
* return;
* }
*
* // Handle other errors.
* return;
* }
*
* // Record that set worked.
* });
*
* @param bso
* (BasicStorageObject) BSO to upload. The BSO instance must have the
* `collection` and `id` properties defined.
*/
setBSO: function setBSO(bso) {
if (!bso) {
throw new Error("bso argument must be defined.");
}
if (!bso.collection) {
throw new Error("BSO instance does not have collection defined.");
}
if (!bso.id) {
throw new Error("BSO instance does not have ID defined.");
}
let uri = this._baseURI + "storage/" + bso.collection + "/" + bso.id;
let request = this._getRequest(uri, "PUT", {
contentType: "application/json",
allowIfUnmodified: true,
data: JSON.stringify(bso),
});
return request;
},
/**
* Add or update multiple BSOs.
*
* This is roughly equivalent to calling setBSO multiple times except it is
* much more effecient because there is only 1 round trip to the server.
*
* The request can be made conditional by setting `locallyModifiedVersion`
* on the returned request instance.
*
* This function returns a StorageCollectionSetRequest instance. This type
* has additional functions and properties specific to this operation. See
* its documentation for more.
*
* Most consumers interested in submitting multiple BSOs to the server will
* want to use `setBSOsBatching` instead. That API intelligently splits up
* requests as necessary, etc.
*
* Example usage:
*
* let request = client.setBSOs("collection0");
* let bso0 = new BasicStorageObject("id0");
* bso0.payload = "payload0";
*
* let bso1 = new BasicStorageObject("id1");
* bso1.payload = "payload1";
*
* request.addBSO(bso0);
* request.addBSO(bso1);
*
* request.dispatch(function onComplete(error, req) {
* if (error) {
* // Handle error.
* return;
* }
*
* let successful = req.successfulIDs;
* let failed = req.failed;
*
* // Do additional processing.
* });
*
* @param collection
* (string) Collection to operate on.
* @return
* (StorageCollectionSetRequest) Request instance.
*/
setBSOs: function setBSOs(collection) {
if (!collection) {
throw new Error("collection argument must be defined.");
}
let uri = this._baseURI + "storage/" + collection;
let request = this._getRequest(uri, "POST", {
requestType: StorageCollectionSetRequest,
contentType: "application/newlines",
accept: "application/json",
allowIfUnmodified: true,
});
return request;
},
/**
* This is a batching variant of setBSOs.
*
* Whereas `setBSOs` is a 1:1 mapping between function calls and HTTP
* requests issued, this one is a 1:N mapping. It will intelligently break
* up outgoing BSOs into multiple requests so size limits, etc aren't
* exceeded.
*
* Please see the documentation for `StorageCollectionBatchedSet` for
* usage info.
*
* @param collection
* (string) Collection to operate on.
* @return
* (StorageCollectionBatchedSet) Batched set instance.
*/
setBSOsBatching: function setBSOsBatching(collection) {
if (!collection) {
throw new Error("collection argument must be defined.");
}
return new StorageCollectionBatchedSet(this, collection);
},
/**
* Deletes a single BSO from a collection.
*
* The request can be made conditional by setting `locallyModifiedVersion`
* on the returned request instance.
*
* @param collection
* (string) Collection to operate on.
* @param id
* (string) ID of BSO to delete.
*/
deleteBSO: function deleteBSO(collection, id) {
if (!collection) {
throw new Error("collection argument must be defined.");
}
if (!id) {
throw new Error("id argument must be defined.");
}
let uri = this._baseURI + "storage/" + collection + "/" + id;
return this._getRequest(uri, "DELETE", {
allowIfUnmodified: true,
});
},
/**
* Delete multiple BSOs from a specific collection.
*
* This is functional equivalent to calling deleteBSO() for every ID but
* much more efficient because it only results in 1 round trip to the server.
*
* The request can be made conditional by setting `locallyModifiedVersion`
* on the returned request instance.
*
* If the number of BSOs to delete is potentially large, it is preferred to
* use `deleteBSOsBatching`. That API automatically splits the operation into
* multiple requests so server limits aren't exceeded.
*
* @param collection
* (string) Name of collection to delete BSOs from.
* @param ids
* (iterable of strings) Set of BSO IDs to delete.
*/
deleteBSOs: function deleteBSOs(collection, ids) {
// In theory we should URL encode. However, IDs are supposed to be URL
// safe. If we get garbage in, we'll get garbage out and the server will
// reject it.
let s = ids.join(",");
let uri = this._baseURI + "storage/" + collection + "?ids=" + s;
return this._getRequest(uri, "DELETE", {
allowIfUnmodified: true,
});
},
/**
* Bulk deletion of BSOs with no size limit.
*
* This allows a large amount of BSOs to be deleted easily. It will formulate
* multiple `deleteBSOs` queries so the client does not exceed server limits.
*
* @param collection
* (string) Name of collection to delete BSOs from.
* @return StorageCollectionBatchedDelete
*/
deleteBSOsBatching: function deleteBSOsBatching(collection) {
if (!collection) {
throw new Error("collection argument must be defined.");
}
return new StorageCollectionBatchedDelete(this, collection);
},
/**
* Deletes a single collection from the server.
*
* The request can be made conditional by setting `locallyModifiedVersion`
* on the returned request instance.
*
* @param collection
* (string) Name of collection to delete.
*/
deleteCollection: function deleteCollection(collection) {
let uri = this._baseURI + "storage/" + collection;
return this._getRequest(uri, "DELETE", {
allowIfUnmodified: true
});
},
/**
* Deletes all collections data from the server.
*/
deleteCollections: function deleteCollections() {
let uri = this._baseURI + "storage";
return this._getRequest(uri, "DELETE", {});
},
/**
* Helper that wraps _getRequest for GET requests that return JSON.
*/
_getJSONGETRequest: function _getJSONGETRequest(path) {
let uri = this._baseURI + path;
return this._getRequest(uri, "GET", {
accept: "application/json",
allowIfModified: true,
completeParser: this._jsonResponseParser,
});
},
/**
* Common logic for obtaining an HTTP request instance.
*
* @param uri
* (string) URI to request.
* @param method
* (string) HTTP method to issue.
* @param options
* (object) Additional options to control request and response
* handling. Keys influencing behavior are:
*
* completeParser - Function that parses a HTTP response body into a
* value. This function receives the RESTResponse object and
* returns a value that is added to a StorageResponse instance.
* If the response cannot be parsed or is invalid, this function
* should throw an exception.
*
* data - Data to be sent in HTTP request body.
*
* accept - Value for Accept request header.
*
* contentType - Value for Content-Type request header.
*
* requestType - Function constructor for request type to initialize.
* Defaults to StorageServiceRequest.
*
* allowIfModified - Whether to populate X-If-Modified-Since if the
* request contains a locallyModifiedVersion.
*
* allowIfUnmodified - Whether to populate X-If-Unmodified-Since if
* the request contains a locallyModifiedVersion.
*/
_getRequest: function _getRequest(uri, method, options) {
if (!options.requestType) {
options.requestType = StorageServiceRequest;
}
let request = new RESTRequest(uri);
if (Prefs.get("sendVersionInfo", true)) {
let ua = this.userAgent + Prefs.get("client.type", "desktop");
request.setHeader("user-agent", ua);
}
if (options.accept) {
request.setHeader("accept", options.accept);
}
if (options.contentType) {
request.setHeader("content-type", options.contentType);
}
let result = new options.requestType();
result._request = request;
result._method = method;
result._client = this;
result._data = options.data;
if (options.completeParser) {
result._completeParser = options.completeParser;
}
result._allowIfModified = !!options.allowIfModified;
result._allowIfUnmodified = !!options.allowIfUnmodified;
return result;
},
_jsonResponseParser: function _jsonResponseParser(response) {
let ct = response.headers["content-type"];
if (!ct) {
throw new Error("No Content-Type response header! Misbehaving server!");
}
if (ct != "application/json" && ct.indexOf("application/json;") != 0) {
throw new Error("Non-JSON media type: " + ct);
}
return JSON.parse(response.body);
},
};
