#firebase-glacier Specification and tools to document firebase projects

##Usage

###To use as command line utility npm install -g firebase-glacier

firebase-glacier in the terminal will read ./glacier.yml and output at ./firebase_spec/

firebase-glacier init in the terminal will create ./glacier.yml and output an initial build at ./firebase_spec/

###To use as module npm install --save-dev firebase-glacier

##Motivations This project was born from my necessity of a better way to design and write firebase's database rules

I based the main idea of the project on swagger, which is an open standard to define language-agnostic interfaces to REST APIs. With glacier, I adapted this concepts and ideas to fit a firebase project

The objective of glacier is to work on a single document that can be processed to generate useful output: database rules, storage rules and even html showing relevant formatted information in a visually pleasant way

The document to work with is called glacier document

##glacier document specification

The language to write a glacier document is yaml.

It contains five main fields at its root:

• glacier
• info
• auth
• database
• storage

glacier : Indicates the firebase-glacier version

info : Contains information relevant to the project users

auth : Contains the configuration options of the auth service

database : Contains the database rules design

storage : Contains the storage rules design

###Main fields breakdown

####glacier Indicates the firebase-glacier version

glacier: "0.2"

####info Contains information relevant to the project users

info:
    version: "0.0.0"
    title: MyApp API
    description: Reference to MyApp API
    termsOfService: terms
    license: Copyright 2016 MyApp
    config:
        web:
            apiKey: none
            authDomain: none
            databaseURL: none
            storageBucket: none
    glossary:
        User: A user that can be assigned one or more role
        Admin: A user with elevated privileges

####auth Contains the configuration options of the auth service

auth:
    methods:
        - email
        - google
        - facebook
        - anonymous
    oauthRedirectDomains:
        - localhost
    allowMultipleAccountsWithSameEmail: false

####database Contains the database rules design

database:
    /users:
        .read: true
        .indexOn:
            - email
            - name
            - lastname
            - birthdate
        /$uid:
            .write: "auth.uid === $uid"
            .validate: "newData.hasChildren(['email', 'name', 'lastname'])"
            /email:
                .validate: "newData.isString()"
            /name:
                .validate: "newData.isString()"
            /lastname:
                .validate: "newData.isString()"

####storage Contains the database rules design

Still to be defined

##Processors

At this point, the project counts with just the database rules processor. It'll read the glacier document and serialize the database field in json format and will be saved into a file ready to be imported to the firebase project.

To invoke all processors (database rules processor and storage rules processor, for now) just:

var glacier = require('firebase-glacier')
glacier.build()

It'll read the glacier document from ./firebase_spec/glacier.yml and output ./firebase_spec/database.rules.json and ./firebase_spec/storage.rules.json

###Database rules processor The database rules processor will ignore all metadata fields and remove the leading slashes from any child of the database root field and

var glacier = require('firebase-glacier')
glacier.buildDbRules()

###Storage rules processor Not implemented yet

###Html generator Not implemented yet

##Metadata The json document used to define rules in firebase says little about what they are meant for when you're not the one that designed those rules (unless you know how security rules work). For this reason, glacier reserves the $ character (at the start of the field) to define arbitrary metadata in the glacier document. A metadata field is meant to be used by a processor.

For example:

/messenger:
    $notes: Conversations messages record
    /$conversation:
        /members:
            $notes: Key sided object containing the uids of the conversation members
        /messages:
            /$key:
                /$uid:
                    $notes: Message owner
                /message:
                    .validate: "newData.isString()"

Here, we are defining $notes as a metadata field that explains what the parent field represents/does/etc. and can be used, say, by the html generator to show this notes to the reader in a stylized way.

Another one:

/users:
    /$uid:
	    /status:
		    $notes: Represent the current status of the user
		    $acceptedValues:
			    - Online
			    - Offline
			    - Suspended
			    - Banned

In this example we defined the $acceptedValues metadata field. This one can be used by the database rules processor to generate the .validate field using the array values instead of manually writing a cumbersome long string to accomplish that rule: (newData.val() === 'Online') || (newData.val() === 'Offline') || ... By the way, this feature is not implemented yet

##Middleware For the database rules processor, the registered middleware (can be more than one of course) is the first agent to handle the glacier document. Its input is an object representation of the glacier document. Its output must be the same object already processed. After every middleware is invoked, the database rules processor will continue its job

###Built-in middleware ####decorators This middleware allows to define arbitrary decorators that'll get replaced with the values they're associated. Decorators are defined as fields of a decorators field placed at the root of the glacier document. Currently, the use of decorators inside the definition of others decorators is not supported.

Example:

glacier: ...
info: ...
auth: ...
database: ...
storage: ...
decorators:
    owner: "auth.uid === $uid"
    client: "root.child('clients').hasChild(auth.uid)"
    admin: "root.child('admins').hasChild(auth.uid)"
    create: "(!data.exists() && newData.exists())"
    update: "(data.exists() && newData.exists())"
    delete: "(data.exists() && !newData.exists())"
    timestamp: "newData.val() === now"
    isString: "newData.isString()"
    starsRate: "(newData.val() === 1 || newData.val() === 2 || newData.val() === 3 || newData.val() === 4 || newData.val() === 5)"

Usage:

database:
    /users:
	    .read: true
	    /$uid:
		    .write: @owner
		    /email:
			    .validate: @isString
		    /name
			    .validate: @isString
		    /$other:
			    .validate: false
    /products:
	    .read: true
		/$key:
			.write: @admin
			/name:
				.validate: @isString
			/rating:
				/$uid:
					.write: @client
					/stars:
						.validate: @starsRate
					/$other:
						.validate: false
			/$other:
				.validate: false

####validate This middleware allows to define metadata that starts with "$validate" as a chunk of a ".validate" field. The ".validate" field gets generated by concatenating all "$validate..." fields. If defined, ".validate" is concatenated too. The OR operation is applied between the "$validate..." fields

Example:

database:
	/$something:
		/status:
			.write: true
			$validate_REQUESTING: "(!data.exists() && newData.val() === 'REQUESTING')"
			$validate_CANCELED: "(data.val() === 'REQUESTING' && newData.val() === 'CANCELED')"
			$validate_REJECTED: "(data.val() === 'REQUESTING' && newData.val() === 'REJECTED')"
			$validate_ACCEPTED: "(data.val() === 'REQUESTING' && newData.val() === 'ACCEPTED')"
			$validate_FINISHED: "(data.val() === 'ACCEPTED' && newData.val() === 'FINISHED')"

Example output:

database:
	/$something:
		/status:
			.write: true
			.validate: "(!data.exists() && newData.val() === 'REQUESTING') || (data.val() === 'REQUESTING' && newData.val() === 'CANCELED') || (data.val() === 'REQUESTING' && newData.val() === 'REJECTED') || (data.val() === 'REQUESTING' && newData.val() === 'ACCEPTED') || (data.val() === 'ACCEPTED' && newData.val() === 'FINISHED')"