bdsstore.txt

    BDS data store category.
    Implements a database with an API and defines behaviour of
    clients and bots using the commands.
    
    Commands must be used in a LINK.
    
    Should probably provide a way to notify users of changes to the data store.
    
    CATEGORY: BDS:STORE
    
    Models and Objects:
        
        The BDS:STORE category provides an API for creating models and objects
        to be stored in a data store, such as a database. Models define the
        structure of a given object in the data store.
        
        By default, every object should have a `modified` attribute. This
        attribute should be a unix-style timestamp detailing the last time the
        object was modified. Objects should also have a unique ID associated
        with them.
    
    COMMANDS:
    
        <user> BDS:STORE:INIT:name,read_privileges,write_privileges,model
            
            Defines a new model in the data store.
            
            name defines the name of the model.
            
            read_privileges determines the privileges required to read a given
            object stored in the database using this model.
                
                0 - Anyone can read every object
                1 - Model creater and object owner can read each object
                2 - Only the object owner can read each object
            
            write_privileges are the same, but for writing instead of reading.
            
            Botdom-recognised service bots supersede all privileges on data
            access.
            
            model must be a JSON object defining the structure of the objects
            for the data store. The object should define the keys, and the
            default values and types for those keys. If no default value is
            provided, then a value must be given when creating new objects
            for the model, unless it is a special type (eg: timestamp).
            
            Example:
            
                <user> BDS:STORE:INIT:user_colors,0,2,{"username": {"type": "string"}, "user": {"type": "string":, "default": ""}, "message": {"type": "string", "default": ""}}
            
            Types:
                string
                int
                bool
                timestamp - UNIX timestamp taken when the object was created
                fromNow; default: (int) 0 - record a UNIX timestamp n seconds from when the object was created
                counter - indicates the field is a counter. autoincrement whenever a new object is created
            
            Each model created should have a username associated with it indicating who
            owns the object. There should also be a timestamp associated with each
            object indicating when the object was last modified.
        
        <bot> BDS:STORE:MODEL:from,name,creater,read_privileges,write_privileges,model
        
            Provides details of an existing model.
            
            Used in response to an INIT command, and also LIST commands, maybe.
            
            Should be used to verify whether or not the model was initialised
            as expected.
            
            Example:
            
                <Botdom> BDS:STORE:MODEL:user,user_colors,user,0,2,{"username": {"type": "string"}, "user": {"type": "string":, "default": ""}, "message": {"type": "string", "default": ""}}
            
        <user> BDS:STORE:NEW:model_name,user,partial
        
            Create a new object in the data store.
            
            model_name defines the name of the model to use for the new object.
            
            partial defines the data for the new object. This object must be in
            JSON format. Not all values are required. Default values will be
            used for attributes that are not provided.
            
            Example:
                
                <user> BDS:STORE:NEW:user_colors,user,{"username": "user", "message": "green"}
            
        <bot> BDS:STORE:OBJECT:from,object_id,owner,modified,object
            
            Defines an object as requested by `from`.
            
            Used in response to FIND and NEW commands.
            
            `from` defines the user who made the request provoking the response.
            
            `object_id` defines the ID of the object.
            
            `owner` defines the owner of the object.
            
            `object` is a JSON object containing the data for the given object.
            
            `modified` is a UNIX timestamp indicating when the object was last updated
            
            If a service bot sees a copy of an object that has been more recently modified
            than a copy that it is currently holding, then it should update its own copy
            with the more recently updated copy.
            
            Example:
            
                <Botdom> BDS:STORE:OBJECT:user,0,user,#######,{"username": "user", "user": "", "message": "green"}
            
        <user> BDS:STORE:FIND:model_name,from,[,conditions[,cursor]]
        <user> BDS:STORE:FIND:model_name,from,[, conditions || cursor ]
            
            Search for objects stored in a given model.
            
            `conditions` must be a JSON object defining values to match in the
            stored objects.
            
            A service bot should respond with 0 or more OBJECT commands,
            followed by an END command.
            
            Maybe have an optional `cursor` parameter that allows the service
            bot to only provide newly modified data. This would require extra
            programming, but would involve sending less data on each
            transaction. Cursors could maybe remember certain search conditions,
            so possibly have a cursor parameter in place of the `conditions`
            argument when a cursor is available.
            
            Examples:
            
                <user> BDS:STORE:FIND:user_colors,user
                <user> BDS:STORE:FIND:user_colors,user,{"username": "user"}
                <user> BDS:STORE:FIND:user_colors,user,{},dsXSrvfSWrgv--efsefl
            
        <bot> BDS:STORE:END:from,model_name[,cursor]
        
            Indicate the end of a search result listing in response to a FIND
            command.
            
            Respond with the conditions used for the search.
            
            Maybe provide a cursor ID as discussed in the FIND command.
            
            Example:
                
                <Botdom> BDS:STORE:END:user,user_colors,dsXSrvfSWrgv--efsefl
        
        <user> BDS:STORE:UPDATE:from,model_name,object_id,partial
            
            Update a given object in the data store using the data provided.
            
            `from` is provided as service bots should be able to perform these
            commands on a user's behalf.
            
            `partial` must be a JSON object defining data to update the stored
            object with.
            
            Service bot should respond with an OBJECT command.
            
            Example:
            
                <user> BDS:STORE:UPDATE:user,user_colors,0,{"user": "red"}
        
        <user> BDS:STORE:UNIQUE:from,model_name,field_name
        
            Query the data store for a set of unique values for the given object
            field/attribute.
            
            Example:
                <user> BDS:STORE:UNIQUE:user,ignores,listing
            
            Bots should respond with a RESULT command.
            
        <bot> BDS:STORE:RESULT:from,object
        
            Should be used in response to queries.

            `object` is a representation of the query results. The object should contain
            a `status` field, and a `data` field.
            
            `status` should be an integer representing the status of the response,
            0 meaning there were no errors. If there was an error, the object returned
            should contain an `error` attribute detailing the nature of the error.
            
            `data` should be an Array containing the items that match the query.

            As an example response to the command in the section above:
                <bot> BDS:STORE:RESULT:user,{"status": 0, "data": ["global", "botdom", "datashare"]}