Global

Methods

addContainerOfDoc(req, target, thingInsideopt)

database level helper function.
creates new -containerOf sister doc to target doc.

only for compability:
tries to add an empty and fresh -containerOf doc to already existing doc needed in case of problems while add and (main reason:) in case a doc was added to dingsda before -containerOf became it's own doc on creation of every doc could also be solved instead by a one time recursion over all docs in all userdbs but this way seemed less intrusive and hard to code
Parameters:
Name Type Attributes Default Description
req Object request object from express app
target string _id of doc whose -containerOf sister doc to be created
thingInside string <optional>
[] array of ids of docs which should be added into -containerOf
Source:

addHyperlink2Doc(req, doc) → {Object}

helper function.
uses request and doc to create valid .hyperlink field and add it to doc provided
Parameters:
Name Type Description
req Object request object from express app
doc Object doc to add .hyperlink to
Source:
Returns:
doc including new .hyperlink field
Type
Object

addItem(req, res) → {Object|string}

database level function.
adds item defined in requests payload to users Database.

assigns uuid as _id, adds timestamp .created and other default fields to doc
adds a second sister document named -containerOf to DB
adds itemCopies of new doc into public DBs if .other.visibility field of doc requires that.
Parameters:
Name Type Description
req Object request object from express app
res Object response object from express app
Source:
Returns:
sends response to client with either DBResponse or error
Type
Object | string

addToArrayIfNotExist(array, item) → {Array}

helper function
Parameters:
Name Type Description
array Array array to add item to
item Array item to be added to array
Source:
Returns:
array after operation
Type
Array

addToInMyPossession(db, itemHyperlink) → {Promise}

helper function.
adds doc ID into db Owners &inMyPossession doc (this is where all items not owned by possesed by a user a referenced)
sister function of deleteFromInMyPossession
Parameters:
Name Type Description
db Object nano database instance
itemHyperlink string .hyperlink field from item/doc to be written into inMyPossession
Source:
To Do:
  • change after &inMyPossession doc became databases
Returns:
returns nano promise to insert updated doc
Type
Promise

arrayItemfoundInArray(itemArray, array) → {boolean}

helper function
returns true if any of the items in itemArray are found in array
Parameters:
Name Type Description
itemArray Array array of objects of which every item should be checked
array Array array to be checked for matches with itemArray
Source:
Returns:
at least one match found
Type
boolean

borrow_request(req, res) → {Object|string}

database level function.
writes a borrow request notification into target user (defined by request url) database's ¬ifications doc.
includes infos from &config doc of user sending.
Parameters:
Name Type Description
req Object request object from express app
res Object response object from express app
Source:
Returns:
sends response to client with either "ok" or error
Type
Object | string

compareArrays(array1, array2) → {boolean}

helper function

compares two arrays and returns if identical
Parameters:
Name Type Description
array1 Array array to be tested
array2 Array array to be tested
Source:
Returns:
arrays are identical
Type
boolean

couch_getUserDB(req) → {Array}

helper to extract Auth cookie from request and return couchDB nano instance and a nano db instance of the same user

couchdb-nano: https://github.com/apache/couchdb-nano
Parameters:
Name Type Description
req Object request object from express app
Source:
Returns:
array [nanoUser, dbUser] containing nano User and UserDB instances
Type
Array

DBCommander(req, res)

request handler. manages all incoming requests on database level.
This means: all requests addressing a single database (most of the times a users DB)

checks for requests HTTP verb ( GET / POST ) as well as the requests JSON payload and forwards request and response object to the different database level functions.
Parameters:
Name Type Description
req object request object from express app
res object response object from express app
Source:

deleteContainerOf(req, targetID)

database level helper function.
deletes -containerOf sister document of targetID
Parameters:
Name Type Description
req Object request object from express app
targetID Object _id of doc whose -containerOf sister doc to be deleted
Source:

deleteFromInMyPossession(db, itemHyperlink) → {Promise}

helper function.
removes doc ID from db Owners &inMyPossession doc
sister function of addToInMyPossession
Parameters:
Name Type Description
db Object nano database instance
itemHyperlink string .hyperlink field from item/doc to be written into inMyPossession
Source:
To Do:
  • change after &inMyPossession doc became databases
Returns:
returns nano promise to insert updated doc
Type
Promise

deleteItemCopies(req, nanoUser, oldDocopt) → {Object|string}

database level helper function.
deletes all copies of doc defined in requests url from this instance's public DB

sister function of insertItemCopies
Parameters:
Name Type Attributes Default Description
req Object request object from express app
nanoUser Object nano instance for the user for whom we called this function
oldDoc Object <optional>
{other:{visibility:[]}} oldDoc PROBABLY NOT NEEDED
Source:
Returns:
sends response to client with either DBResponse or error
Type
Object | string

deleteItems(req, res) → {Object|string}

database level function.
deletes single item in Database defined by request url

after deletion of target doc, also attempts to delete all copies of this doc within publicDBs as well as docs sister doc -containerOf
Parameters:
Name Type Description
req Object request object from express app
res Object response object from express app
Source:
Returns:
sends response to client with either DBResponse or error
Type
Object | string

dingsCommander(req, res)

request handler. manages all incoming requests on thing level.
This means: all requests addressing only a single item/doc in the database

checks for requests HTTP verb ( GET / POST ) as well as the requests JSON payload and forwards request and response object to the different thinglevel document functions.
Parameters:
Name Type Description
req object request object from express app
res object response object from express app
Source:

fetch(req, res) → {Object}

thing level function.
gets item requested by request url target ID (https:xxx/api/v1/xxxx/ID/xxxxx) from database if an attachment is also requested via request url (https:xxx/api/v1/xxxxx/xxxx/ATTACHMENT) the attachment is added to the response payload instead of document
Parameters:
Name Type Description
req Object request object from express app
res Object response object from express app
Source:
Returns:
sends express response back to client with either requested doc or attachment
Type
Object

findItems(req, res) → {Object|string}

database level function.
searches for items in Database defined by request url and returns list of items with most relevant fields of found docs/items.
uses makeMango to build a mango style search query to couchDBs find API
expects a payload .data.doc with all fields that should be included in the search.
Parameters:
Name Type Description
req Object request object from express app
res Object response object from express app
Source:
Returns:
sends response to client with either DBResponse or error
Type
Object | string

fromHex(h)

helper function

turns Hex value to string
Parameters:
Name Type Description
h string hex value to be turned to string
Source:

getCarnet(req, res) → {string|Object}

database level function.
gets userDBs carnetATA view from couchDB which should return a csv formatted for the international customs form Carnet A.T.A and sends response including the csv string or an json prepared for client side conversion to pdf into responses payload.
Parameters:
Name Type Description
req Object request object from express app
res Object response object from express app
Source:
Returns:
couchDB carnetATA or couchDB carnetATAjson view response or error
Type
string | Object

getSessionAndAuthToken(req, res, next, username, password)

express middleware helper function.

requests _session from couchDB using username and password and adds AuthSession cookie from couchDB response to the response object so user will be able to authenticate with cookie next time.
Parameters:
Name Type Description
req Object request object from express app
res Object response object from express app
next function callback for express middleware functions
username string username
password string password
Source:

getTargetsFromUrl(target) → {Array}

helper function.
splits a request url into an array of "targets" defined by the url.
this is helpful to later quickly find out which database and/or thing and/or attachment is addressed by a request.
the order of the returned Array defines which level the target addresses:
  • targets[0] is database level
  • targets[1] is thing level
  • targets[2] is attachment level (atm handled in thinglevel as well)
  • Parameters:
    Name Type Description
    target string url to be split into targets of request
    Source:
    Returns:
    targets - Array of strings (names of targets in order of target)
    Type
    Array

    handover(req, res) → {Object|string}

    thing level function.
    confirms an announced handover set in handover_announce.
    deletes notification entries with item reference defined by request payload .data.ref from ¬ifications doc of user sending as well as user defined by request payload .data.from
    writes into &inMyPossession doc of user sending request
    writes username of new possessor into doc in questions field .inPossessionOf
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    Source:
    To Do:
    • change after ¬ifications and &inMyPossession docs became databases
    Returns:
    sends response to client with either "ok: handover success" or error
    Type
    Object | string

    handover_announce(req, res) → {Object}

    thing level function.
    announces the handover of a phyisical thing from the user sending the request to another user (defined in req payload .data.username).
    writes notifications into ¬ifications doc of user sending the request as well as into ¬ifications doc of user that is allegedely receiving the item defined by url path of request (target[1])
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    Source:
    To Do:
    • change after ¬ifications doc became ¬ifications database
    Returns:
    sends response to client with either couchDBs response after insert or error
    Type
    Object

    handover_cancel(req, res) → {Object}

    thing level function.
    cancels an announced handover set in handover_announce.
    deletes notification entries with item reference defined by request payload .data.ref from ¬ifications doc of user sending as well as user defined by request payload .data.to
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    Source:
    To Do:
    • change after ¬ifications doc became ¬ifications database
    Returns:
    sends response to client with either couchDBs response after notifications are deleted or error
    Type
    Object

    handover_deny(req, res) → {Object}

    thing level function.
    denies an announced handover set in handover_announce.
    deletes notification entries with item reference defined by request payload .data.ref from ¬ifications doc of user sending as well as user defined by request payload .data.from
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    Source:
    To Do:
    • change after ¬ifications doc became ¬ifications database
    Returns:
    sends response to client with either couchDBs response after notifications are deleted and a notification about the denial is inserted into database of the owner of the announcment or error
    Type
    Object

    insertItemCopies(req, nanoUser, oldDocopt) → {Object|string}

    database level helper function.
    inserts a copy of doc defined in requests url from this instance's public DB

    sister function of deleteItemCopies
    Parameters:
    Name Type Attributes Default Description
    req Object request object from express app
    nanoUser Object nano instance for the user for whom we called this function
    oldDoc Object <optional>
    {other:{visibility:[]}} oldDoc doc to compare changes with
    Source:
    Returns:
    sends response to client with either DBResponse or error
    Type
    Object | string

    instanceCommander(req, res)

    request handler. manages all incoming requests on instance level.
    This means: all requests the complete server instance (e.g. https://dingsda.org:3000/api/v1/)

    checks for requests HTTP verb ( GET / POST / DELETE ) as well as the requests JSON payload and forwards request and response object to the different functions.
    Parameters:
    Name Type Description
    req object request object from express app
    res object response object from express app
    Source:

    makeMango(input, ids2ignore) → {Object}

    helper function.
    creates a mango styled find request for couchDB (see https://github.com/cloudant/mango) from input and ids2ignore

    will make Mango using regex caseinsensitive for all provided input fields that are strings and search with mango "$in" operator for all provided input fields that are Arrays

    for more complex searches please check search
    Parameters:
    Name Type Description
    input Object object including all fields and values to be included in search.
    ids2ignore Array array of strings of doc ids to be added as to be ignored to the mango query
    Source:
    Returns:
    query object in style of couchDBs mango js queries
    Type
    Object

    move(req, res) → {Object|string}

    thing level function.
    updates doc.location in DB (both defined by request url) to new location defined in requests payload .data.location.
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    Source:
    Returns:
    sends response to client with either couchDB response or error
    Type
    Object | string
    instance level function
    not yet implemented.
    should become function to make more complex (completely client made?) search queries to database. either using map-reduce (meh) or mango queries

    for an already working and easier way to find items take a look at findItems
    Source:

    toHex(s)

    helper function

    turns string to Hex value
    Parameters:
    Name Type Description
    s string string to be transformed
    Source:

    trimFloatStringToNDecimalPlaces(num, decimals) → {string}

    helper function
    Parameters:
    Name Type Default Description
    num string float as string to be trimmed
    decimals number 3 number of decimals to cut num to.
    Source:
    Returns:
    trimmed float as string
    Type
    string

    trimTrailingSlashes(input) → {string}

    helper function
    Parameters:
    Name Type Description
    input string string to trim slashes from
    Source:
    Returns:
    trimmed string
    Type
    string

    update(req, res) → {Object|string}

    thing level function.
    updates doc in DB (both defined by request url)

    fetched oldDoc, compares and merges oldDoc and .data.doc (from request payload), calls updateContainerOf if locationInsideOf is present in .data.doc, updates publicDB(s) if .data.other.visibility indicates public Read Rights (via {@dlink eleteItemCopies} and insertItemCopies) and finally inserts new merged doc into DB.
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    Source:
    Returns:
    sends response to client with either couchDB response or error
    Type
    Object | string

    updateContainerOf(req, target, thingInside, authCookie, delete_it, callback)

    database level helper function.
    updates -containerOf sister doc of target by adding thingInside to its .containerOf field via addContainerOfDoc
    If delete_it flag is set true, will delete item instead of adding it.
    Parameters:
    Name Type Default Description
    req Object request object from express app
    target string _id of doc whose -containerOf sister doc to be updated
    thingInside string _id of doc which should be deleted or added to target-containerOf
    authCookie string AuthSessionToken to be used as Auth in communication with DB
    delete_it boolean false flag. if true thingInside will be removed from -containerOf
    callback callback callback. will get true or false depending on success or not
    Source:

    updatePublicDBIfPublic(req, doc)

    database level helper function.
    checks if .other.visibility of doc is public and if so deletes and inserts copies of the doc into this instance's public database via deleteItemCopies and insertItemCopies
    Parameters:
    Name Type Description
    req Object request object from express app
    doc Object document object including the document to be updated inside of public DB
    Source:

    validateReadRights(req, res, next)

    express middleware function.

    validates read permissions of a request.
    checks first how deep the request goes (meaning: if it is targeting the instance, userDatabase or a specific document/thing/item inside of the database) by checking the targets in request url.
    for requests to thinglevel or deeper it checks by going through the following steps:
  • 1.) is req.username trying to read her own DB? --> READ GRANTED
  • 2.) is req.username in thing.owners? --> READ GRANTED
  • 3.) is thing.visibility === "public"? --> READ GRANTED
  • 4.) is req.username in thing.inPossessionOf (because owner borrowed it out)? --> READ GRANTED
  • 5.) is thing.visibility !== "private" && userdb-._security. does contain req.username? --> READ GRANTED
  • 6.) (HARDEST maybe future science) (TO BE DONE): is thing.visibility === "friends2nd" && req.username is in friends of anybody who has in their userdb-._security.friends list? --> READ GRANTED (unclear how to approach. So better first 1.-4. and this later)
  • 7.) ELSE: --> NO READ GRANTED --> no such object.
  • Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    next function callback for express middleware functions
    Source:

    verifyAuthToken(req, res, next)

    express middleware function.

    verifies user Auth by using Cookie AuthSession provided in request.

    calls getSessionAndAuthToken
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    next function callback for express middleware functions
    Source:

    verifyByJsonPW(req, res, next)

    express middleware helper function.

    verifies user Auth by testing for username and password inside of request payload.

    calls getSessionAndAuthToken
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    next function callback for express middleware functions
    Source:

    verifyByUrlPW(req, res, next)

    express middleware helper function.

    verifies user Auth by testing for username and password inside of request query parameter.

    username and password can be query parameters or in json format inside of a query parameter calles json. e.g.: https://xxx.xxx/yyy?username=aaa&password=bbb or https://xxx.xxx/yyy?json='{"username":"aaa","password":"bbb"}'
    calls getSessionAndAuthToken
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    next function callback for express middleware functions
    Source:

    verifyUserCredibility(req, res, next)

    express middleware function.

    decides how to verify user Auth

    calls verifyAuthToken, verifyByJsonPW or verifyByUrlPW depending on request cookies, payload and/or HTTP method. sends error response in case none of possible verification methods are provided with request.
    Parameters:
    Name Type Description
    req Object request object from express app
    res Object response object from express app
    next function callback for express middleware functions
    Source: