freezr.info - Towards data freedom
Intro
Manifest
Core API
Storage API
App Info API
Technical Specs - Introduction
freezr is an open source personal server, built on node.js.
It acts as a thin layer providing identity and permissions management, to connect apps to the data owner's files and data.
Apps define their parameters and permissions via an App Manifest
Apps communicate with the server via a Core API which is CEPS-compatible.
Apps can be independent third party apps outside of the freezr server (eg a smart phone app that communicates with your freezr, or even a third party server that stores your data on your freezr.) But freezr also allows html apps to be served from your freezr server. Such a "freezr app" is just a collection of html, css and js files which you can "install" on your server. ie you just download the html/css/js files on your freezr, define how a page should be served in the manifest and then
Within freezr, all data is stored within a user's preferred storage medium - their personal data store, which can be on Google, or AWS or Dropbox, or any other storage medium that is connected to freezr via its Storage API. Here, data refers to actual data sitting in the freezr database, any files which you store there (eg pictures), as well as the freezr-app's actual program files (ie html/css/js files served.)
Details on all of this can be found in the sections below.
Technical Specs - The App Manifest
A manifest defines a JSON object with the attributes listed below. A freezr manifest is compatible with the manifest described by CEPS, with some additional features.
Metadata about the app (based on CEPS):
pages: Attributes of the web pages served by freezr. This is used for freezr-apps only.
Each web page's main html file serves as a key to an object with the attributes below. (eg index.html would have the key "index".)
Each web page's main html file serves as a key to an object with the attributes below. (eg index.html would have the key "index".)
app_tables: Defines the attributes of specific data tables (ie collections.)
should contain json objects with the name of the collection, and each collection name object can have the following attributes:
should contain json objects with the name of the collection, and each collection name object can have the following attributes:
"field_names" should contain json objects with the name of the key, and each key object can have the following attributes:
files: freezr can store files and it creates a database record for each file. File attrbutes are as follows:
permissions: Defines the permissions the app is asking for.
"permissions" are a list of json objects with the name of the permission. Each permission object has the following attributes:
"permissions" are a list of json objects with the name of the permission. Each permission object has the following attributes:
An object_delegate can have the following attributes:
An object_delegate can have the following attributes:
A db_query can have the following attributes:
A folder_delegate can have the following attributes:
A field_delegate can have the following attributes:
An outside_scripts can have the following attributes:
This is an example of a manifest file. (Key words in green):
{
"app_name":"info.freezr.demo.clickOnCheese.EveryOnesCheese",
app name is
"app_display_name":"Click On EVERY ONE's Cheese - File Sharing Demo"
"app_version": "01"
"only_use_collections_listed":true, // true means only accept field_names that are in the key list below
"index": {
"page_title":"Click on Cheese Game",
"html_file":"index.html",
"css_files": ["index.css"],
"script_files": ["index.js"]
},
"cheese_list": {
"page_title":"list of Cheeses to choose from",
"html_file":"cheese_list.html",
"css_files": "cheese_list.css",
"initial_query": {"type":"queryData", "permission_name":"cheese_share" }
"script_files": ["cheese_list.js"]
}
},
"scores": {
"strictly_Adhere_To_schema":true,
"make_data_id":{"manual":true},
"field_names": {
"score": {
"description":"Player Score",
"type":"integer",
"required":true,
}
}
},
},
"do_not_allow":false,
"strictly_Adhere_To_schema":false,
"donot_auto_enumerate_duplicates":false,
"allowed_file_types":["jpg","png","jpeg","JPG","PNG","JPEG"],
"field_names":{
"description":"Cheese Name",
"type":"string",
"required":false,
}
},
"top_scores": {
"type":"db_query",
"description":"Player Top Scores",
"requestee_app":null,
"collection":"scores",
"permitted_fields":null,
"sort_fields":{"score":-1},
"max_count":1,
"return_fields":"score","_owner","_date_Created"],
"sharable_groups":["logged_in"],
},
"cheese_share": {
"type":"object_delegate",
"description":"Share All Cheese Pictures",
"collection":"files",
"sharable_groups":["logged_in"],
"requestee_app":null,
}
}
}
Technical Specs - The Core API / Library for Apps
The freezr_core API is a set of javascript functions for accessing the database, accessing uploaded files, managing permissioning, and rendering pages.
freezr automatically includes this library (freezr_core.js) when a freezr-app is served. But this file can also be used in stand-alone apps, including any ceps-compatible app. The freezr core API with the functions below.
The main functions may be used either with a callback or as a promise. For example, you can write either
freezr.ceps.create({foo: 'bar'}, function(results) { console.log(results)})
or
results = await freepr.ceps.create({foo: 'bar'})
("freepr" is shorthand for "freezr.promise".)
The functions in the library are:
CEPS: CEPS compatible functions
Example: freezr.ceps.create({"score":score});
Example: freezr.promise.ceps.create({"score":score}). then(callFwdForScoreWrite);
Example: freezr.ceps.create({"score":score}, {collection: "scores"}, callbackForScoreWrite);
Example: freepr.ceps.create({"score":score}, {collection: "scores"}). then(callFwdForScoreWrite);
This POSTs to: /ceps/write/{table-identifier}
Parameters:
Example: freezr.ceps.getById('unique_id_of_db_record', null, callbackForGetById);
Example: freezr.ceps.getById('unique_id_of_db_record', null, callbackForGetById);
This GETs from: /ceps/read/{table-identifier}/{record-id}
Parameters:
Example: freezr.ceps.getquery( { 'collection':'scores', 'query_params': {'_owner':'slowJoeCrow' } }, callbackForTopScoreQuery );
Example: freezr.promise.ceps.getquery(). then(callFwdForAllScoresQuery);
This GETs from: /ceps/query/{table-identifier}[?{attribute}={ value}[&{attribute2}={value2} ...] ]
Parameters:
Example: freezr.ceps.update({ _id, score :newScore});
Example: freezr.promise.ceps.update({ _id, score :newScore}. then(callFwdForScoreWrite);
This PUTs to: /ceps/update/{table-identifier}/{record-id}
Parameters:
Example: freezr.ceps.delete('unique_id_of_db_record', callbackForGetById);
Example: freezr.ceps.delete('unique_id_of_db_record', null, callbackForGetById);
This DELETEs at: /ceps/delete/{table-identifier}/{record-id}
Parameters:
This POSTs to: /ceps/message/initiate
Parameters:
FEPS: freezr End-Points - like CEPS, but with advanced functionality...
Example: freezr.feps.create({"score":score});
Example: freezr.promise.feps.create({"score":score}). then(callFwdForScoreWrite);
Example: freezr.feps.create({"score":score}, {collection: "scores"}, callbackForScoreWrite);
Example: freepr.feps.create({"score":score}, {collection: "scores"}). then(callFwdForScoreWrite);
This POSTs to: /feps/write/{table-identifier}
Parameters:
Example: freezr.feps.getById('unique_id_of_db_record', null, callbackForGetById);
Example: freezr.feps.getById('unique_id_of_db_record', null, callbackForGetById);
This GETs from: /feps/read/{table-identifier}/{record-id}[/{user-id}]
Parameters:
Example: freezr.feps.postquery( { 'collection':'scores', 'query_params': {'_owner':'slowJoeCrow' } }, callbackForTopScoreQuery );
Example: freezr.promise.feps.postquery(). then(callFwdForAllScoresQuery);
This POSTs to: /feps/query/{table-identifier}[?{attribute}={ value}[&{attribute2}={value2} ...] ]
Parameters:
Example: freezr.feps.update({ _id, score: newScore});
Example: freezr.promise.feps.update({ _id, score: newScore}). then(callFwdForScoreWrite);
Example: freezr.feps.update({ score: artificiallyuInflatedScore }, {q: { name }}, callbackForScoreWrite, "scores");
This PUTs to: /ceps/update/{table-identifier}/{record-id}
Parameters:
Example: freezr.feps.upload(document.getElementById('picture_file').files[0]);
Example: freezr.feps.upload(document.getElementById('picture_file').files[0], {'caption':'savoie cheese','fileOverWrite':true}, callbackForPictureUpload);
Example: freezr.promise.feps.upload(document.getElementById('picture_file').files[0], {'caption':'savoie cheese','fileOverWrite':true}) .then( callFwdForPictureUpload);
Parameters:
Each file uploaded gets an associated record in the db in a collection named "files", and ad-hoc other data fields can be added to that record. The _id of the record is the relative file path plus file name, and this cannot be changed. Files can be accessed via url - see freezr.filePath below.
Example: freezr.feps.getByPublicId('unique_public_id_of_db_record', null, callbackForGetById);
This GETs from: /v1/pdb/{record-id}
Parameters:
Example: freezr.feps.publicquery( { 'collection':'scores', 'query_params': {'_owner':'slowJoeCrow' } }, callbackForTopScoreQuery );
Example: freezr.promise.feps.publicquery(). then(callFwdForAllScoresQuery);
This POSTs to: /v1/pdbq
Parameters:
Perms: Granting and reading permissions...
This is mainly called on my freezr_core, but can also be accessed by apps.
Example: freezr.perms.getAppPermissions(callbackForAppPerms);
Example: freezr.promise.perms.getAppPermissions() .then(callFwdForAppPerms);
Parameters:
This gives specific people access to a specific single objects. If the object is a file, then the user can access the file. (CEPS compatible)
Example: freezr.perms.shareRecords("aug2015photos/2015-08-21-0234.jpg", callbackForObjectAccess);
Example: freezr.promise.perms.shareRecords("aug2015photos/2015-08-21-0234.jpg") .then(callFwdForObjectAccess);
This POSTs to: /feps/perms/share_records or /ceps/perms/share_records
Parameters:
This is like shareRecords but has an additional fileStrcuture field showing the js and css files that need to be appended to the page.
This POSTs to: /feps/perms/share_records
Parameters (Same as share_records plus the option):
Utils: Functions for rendering html or referring to files from html
Example: freezr.utils.getConfig(callbackForGetConfig) ;
This is for the app development process mainly. It returns "{'app_config':app_config, 'collection_names':collection_names}", where collection_names are the collection_names actually used, whether they appear in the app_config or not.
Parameters:
Example: freezr.db.updateFileList(callbackForUpdatingFilelst) ;
This is for the app development process mainly. If files have been added to a folder manually, this function reads all the files and records them in the db.
Parameters:
Gets user_id, freezr_server_version and log in status on return.
Parameters:
This can be used to serve snippets of html via javascript (using mustache for example)
Parameters:
Creates the full freezr path to user file based on the file's name. Each file's id (and path) includes the app name, user name, folder name and file name - the combination of which is always unique.
Example: freezr.utils.filePathFromName('aug2015photos/2015-08-21-0234.jpg', 'donald', 'photoAccess');
Parameters:
Example: freezr.utils.freezrMenuOpen();
Example: freezr.utils.freezrMenuClose();
Note that this is actually closes the menu, while freezr.onFreezrMenuClose can be defined by the app, and will be called upon when the user closes te menu.
Other: Other miscellaneous utilies for freezr apps.
app: Functions and variables for creating stand-alone apps with the likes of phonegap or electron, which are not accessed online via a web browser.
initPageScripts: A special function, null by default that can be defined for each app, and whch is run after the app page has been created.
onFreezrMenuClose (hasChanged) : A special function, null by default that can be defined for each app, and is called when the freezr menu is closed. An app can define this to perform specific actions when a user grants or denies a new permission. ("hasChanged" indicates if the user has granted or denied a permission.)
Technical Specs - Data Storage API
Description coming soon
Technical Specs - App Info API