diff --git a/.gitignore b/.gitignore index 23f1c2c..cc9104e 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ node_modules dweb_transports_bundle.js +dweb-transports-bundle.js diff --git a/API.md b/API.md index 435463c..e5d4063 100644 --- a/API.md +++ b/API.md @@ -3,7 +3,7 @@ Mitra Ardron, Internet Archive, mitra@mitra.biz This doc provides a concise API specification for the Dweb Javascript Libraries. -It was last revised (to match the code) on 9 March 2018. +It was last revised (to match the code) on 23 April 2018. If you find any discrepancies please add an issue here. @@ -27,7 +27,7 @@ The Transport layer provides a layer that is intended to be independent of the u There are a set of classes: * *Transport*: superclass of each supported transport, * *TransportHTTP*: Connects to generic http servers, and handles contenthash: through a known gateway -* *TransportIPFS*: Connects to IPFS, currently via WebSocketsStar (WSS) +* *TransportIPFS*: Connects to IPFS, currently (April 2018) via WebSocketsStar (WSS) * *TransportYJS*: Implements shared lists, and dictionaries. Uses IPFS for transport * *TransportWEBTORRENT*: Integrates to Feross's WebTorrent library * *Transports*: manages the list of conencted transports, and directs api calls to them. @@ -47,7 +47,7 @@ Fields|  options | Holds options passed to constructor name|Short name of transport e.g. “HTTP”, “IPFS” supportURLs|Array of url prefixes supported e.g. [‘ipfs’,’http’] -supportFunctions|Array of functions supported on those urls, current full list would be: `['fetch', 'store', 'add', 'list', 'reverse', 'newlisturls', "get", "set", "keys", "getall", "delete", "newtable", "newdatabase", "listmonitor"]` +supportFunctions|Array of functions supported on those urls, current (April 2018) full list would be: `['fetch', 'store', 'add', 'list', 'reverse', 'newlisturls', "get", "set", "keys", "getall", "delete", "newtable", "newdatabase", "listmonitor"]` status|Numeric indication of transport status: Started(0); Failed(1); Starting(2); Loaded(3) ###Setup of a transport @@ -83,12 +83,22 @@ cb (t)=>void If set, will be called back as status changes (so could be multip Resolves to the Transport instance ``` -#####p_setup(options, verbose, cb) +#####async p_setup(options, verbose, cb) A deprecated utility to simply setup0 then p_setup1 then p_setup2 to allow a transport to be started in one step, normally `Transports.p_setup` should be called instead. -#####p_status (verbose) -Return a numeric code for the status of a transport. +####togglePaused(cb) +Switch the state of the transport between STATUS_CONNECTED and STATUS_PAUSED, +in the paused state it will not be used for transport but, in some cases, will still do background tasks like serving files. +``` +cb(transport)=>void a callback called after this is run, may be used for example to change the UI +``` + +#####async p_status (verbose) +Check the status of the underlying transport. This may update the "status" field from the underlying transport. +``` +returns: a numeric code for the status of a transport. +``` Code|Name|Means ---|---|--- @@ -119,7 +129,7 @@ timeoutMS Max time to wait on transports that support it (IPFS for fetch) start,end Inclusive byte range wanted (must be supported, uses a "slice" on output if transport ignores it. relay If first transport fails, try and retrieve on 2nd, then store on 1st, and so on. verbose boolean - True for debugging output -Resolves to string The object being fetched, (note currently returned as a string, may refactor to return Buffer) +Resolves to string The object being fetched, (note currently (April 2018) returned as a string, may refactor to return Buffer) throws: TransportError if url invalid - note this happens immediately, not as a catch in the promise ``` @@ -162,11 +172,12 @@ verbose boolean - True for debugging output Resolves to Array objects as stored on the list (see p_rawlist for format) ``` -#####listmonitor (url, cb) +#####listmonitor (url, cb, {verbose}) Setup a callback called whenever an item is added to a list, typically it would be called immediately after a p_rawlist to get any more items not returned by p_rawlist. ``` url Identifier of list (as used by p_rawlist and "signedby" parameter of p_rawadd cb(obj) function(obj) Callback for each new item added to the list +verbose boolean - True for debugging output obj is same format as p_rawlist or p_rawreverse ``` @@ -236,7 +247,7 @@ returns: Dictionary of Key:Value pairs, note take care if this could #####static async p_f_createReadStream(url, {wanturl, verbose}) Provide a function of the form needed by