freezr.info - Towards data freedom
Intro
Manifest
Core API
Microservices
Resource API
App Info API
Technical Specs - Introduction 1
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, data and even compute resources.
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.
Of course, this would mean that, for security reasons, freezr apps can't directly run any code on the back end. However, back end code can either be run on serverless instances or on the server if it is trusted. See here for more details.
Within freezr, all data is stored within a user's preferred storage medium - their personal data store, which can be on AWS, Azure or even Dropbox, or any other storage medium that is connected to freezr via its Resource APIs. 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 - Microservices for running code on the server
Obviously it would be inherently unsafe to run untrusted third party code on any server. Unfortunately this also means that apps cannot run any back end code on freezr directly, not can they install any additional npm modules on the freezr backend end. So, to run server code and associated npm modules on the backend of freezr you can create microservices which can either bee run on a serverless instance, or if the service is trusted, on the freezr server itself.
To do this, apps can include a zip file of the microservice code in their app bundle (along with the app html/js/css files), and request the microservice permission. If users grant this permission, then the app can run the microservice zip file in one of two ways.
1. Serverless microservice
For users to take advantage of this serverless functionality, they need to have added a servlerless token for “compute” on their profile under “/account/settings”. Then, when they grant the use_microservice permission to an app, the app can run it as a backend process, using the token provided by that specific user. Currently the only choice is an AWS serverless instance but other cloud services will be added in the future.
2. Local microservice
If the server admin trusts the microservice’s code, then the admin can upload the same zip file here: /admin/addsystemextension and freezr will run the microservice locally. This is particularly useful for developers who would want to iterate on the microservice code without calling a serverless instance every time.
This simple microservices architecture makes freezr backend functionality infinitely extensible.
Note that when a user updates an app and they have given the use_microservice permission, the new microservices version is uploaded to their host (eg aws). However, only admins can install local extensions, as such the admin on the server needs to update the microservice for usage directly. Also note that local microservices are available to all users, and they are not restricted to any particular user, so they should be used cautiously, and preferrably mainly for development.
The Permission request
The permission for microservices is as follows:
Example:
{
"name": "com_anthropic_apitester",
"type": "use_micorservice",
"description": "testing serverless... "
}
Calling the function
The app can call the microservices function by using freezr.feps.microservice. As an example:
const serviceReturns = await freepr.feps.microservice(parameters)
Here are the parameters that can be passed to the function.
The following keys are used to populate invokeserverless & invokeextension with parameters to run the function on.
Additionally, in the future, the microservice will add additional parameters:
Example:
{
task: invokeextenstion,
inputParams: { args: ‘what is freezr?’, action: 'chat' },
permission_name: 'ai_open_tester_writeOpenai',
read_collection_name: 'openAIKeys',
read_query: { _id: 'openAIKey' },
read_name: 'openAiKeyQuery',
}
task: invokeextenstion,
inputParams: { args: ‘what is freezr?’, action: 'chat' },
permission_name: 'ai_open_tester_writeOpenai',
read_collection_name: 'openAIKeys',
read_query: { _id: 'openAIKey' },
read_name: 'openAiKeyQuery',
}
When this is sent to the freezr server, the server reads the database to get the openAIKey and then sends it to the microservice in an 'event' parameter set which look like this:
{
inputParams: { args: ‘what is freezr?’, action: 'chat' },
dbResults: { llmKeyQuery: [{ openAIKey: ‘secretKeyHere’, _id: ‘sdsdsd’, _date_modified: 34343433433}] }
}
Creating the microservices function
The function can be thought of s compatible with any aws function, packed up in a zip. In fact it could probably be written in any language, but here we are assuming it is a node js function. So it would have a package.json (and package-lock.json) with only the dependencies, and it needs to have a file called index.mjs that has a function called handler. All the parameters noted above will be passed to the handler….
For example:
export const handler = async (event, context) => {
DO WHATEVER YOU WANT HERE, knowing that the event variable may have a dbResults and a inputParams key…
const apiResponse = { success: ‘send whatever you like’}
the value of the apiResponse object will be returned to the app.
const error = null
return { apiResponse, error }
})
DO WHATEVER YOU WANT HERE, knowing that the event variable may have a dbResults and a inputParams key…
const apiResponse = { success: ‘send whatever you like’}
the value of the apiResponse object will be returned to the app.
const error = null
return { apiResponse, error }
Technical Specs - Resources API - Files Databases and Compute
freezr is purposefully targetting a lowest common denominator of files, databases and compute so that any file system, database and serverless compute resource can be plugged into it.
For the moment, mongo db compatible databases are supported, but it would be possible to design an interface for a sql database to be connected to it.
More details to be added
Technical Specs - App Info API