reedb 0.10.rc1 → 0.11

data/lib/reedb.rb

@@ -1,44 +1,40 @@
 # ====================================================
 # Copyright 2015 Lonely Robot (see @author)
-# @author: Katharina Sabel | www.2rsoftworks.de
+# @author: Katharina Sabel | www.lonelyrobot.io
 #
 # Distributed under the GNU Lesser GPL Version 3
 # (See accompanying LICENSE file or get a copy at
 # 	https://www.gnu.org/licenses/lgpl.html)
 # ====================================================
 
+'' '
+This is the core file for the Reedb module. It consists of
+multiple sub-modules that handle different operations of the
+Reedb daemon/ toolkit (when developing with it as a Gem depenency.
+' ''
+
 # Internal requirements
 require_relative 'reedb/errors/daemon_errors'
+require_relative 'reedb/errors/reedb_errors'
+require_relative 'reedb/errors/exit_errors'
 
+# Meta information requirements
 require_relative 'reedb/utils/meta_vault'
 require_relative 'reedb/utils/utilities'
 require_relative 'reedb/utils/logger'
-require_relative 'reedb/utils/uuids'
+# require_relative 'reedb/utils/uuids'
 
+# Internals
 require_relative 'reedb/constants'
+require_relative 'reedb/debouncer'
 require_relative 'reedb/reevault'
 
 
 # System requirements
 require 'securerandom'
+require 'uuid'
 
 module Reedb
-	class << self
-		# Returns the platform/ architecture of the daemon and vault handler
-
-		def archos() (return @@archos) end
-
-		# Returns whether or not this is a daemon
-		def daemon?() (return @@daemon) end
-
-		# Returns the minimum passphrase length is
-		def passlength() (return @@pw_length) end
-
-		# Returns whether verbose mode is enabled
-		def verbose?() (return @@verbose) end			
-	end
-
-
 	def self.included(api)
 		class << api
 
@@ -46,15 +42,16 @@ module Reedb
 			@@started = false
 
 			# Some more runtime variables
-			@@path = Reedb::DEF_MASTER_PATH
-			@@config_path = Reedb::DEF_MASTER_PATH
+			@@path = Reedb::DEFAULT_PATH
+			@@config_path = Reedb::DEFAULT_PATH
 			@@no_token = false
 			@@verbose = false
 			@@pw_length = -1
 			@@cleanup = true
 			@@daemon = true
 			@@archos = nil
-			
+			@@lock_file = nil
+
 			# Stores the active vaults
 			@@active_vaults = {}
 
@@ -67,6 +64,34 @@ module Reedb
 			# PRIVATE FUNCTIONS BELOW
 			private
 
+			@@debouncer = nil
+			# @return [Object] Debouncer class to handle updates on vaults
+			def debouncer;
+				@@debouncer
+			end
+
+			@@debounce_thread = nil
+			# @return [Object] Debouncer THREAD! to handle updates on vaults
+			def debounce_thread;
+				@@debounce_thread
+			end
+
+			# Method that gets called whenever a change to the currently active vault set occurs.
+			# It will give change information to the debounce handler that then updates it's secondary vault set
+			# for debouncing.
+			# This can UNDER NO CIRCUMSTANCES (!) ever be called from an outside source!
+			#
+			# @param [String] uuid of the vault
+			# @param [String] token for the vault
+			# @param [Enum] marker to describe what to do
+			#
+			# @return nil
+			#
+			def mirror_debounce(uuid, token, marker)
+				return @@debouncer.add_vault(uuid, token) if marker == Reedb::DEB_ADD
+				return @@debouncer.remove_vault(uuid) if marker == Reedb::DEB_REM
+			end
+
 			# Generates an authentication token for vault access.
 			# The function also adds the token, bound to the vault name, to the
 			# @@tokens set.
@@ -74,15 +99,19 @@ module Reedb
 			# Params: 	'name' of the vault
 			# 					'path' of the vault
 			#
-			# => Base64 encoded token
+			# @return [String] Base64 encoded token
 			#
-			def generate_token(uuid, path)
+			def generate_token(uuid, path, permanent = false)
+				puts '[WARN] Not implemented!' if permanent
+
 				# Concatinates the token together and base64 encodes it
 				token = Base64.encode64("#{SecureRandom.base64(Reedb::TOKEN_BYTE_SIZE)}--#{uuid}--#{SecureRandom.base64(Reedb::TOKEN_BYTE_SIZE)}--#{path}--#{SecureRandom.base64(Reedb::TOKEN_BYTE_SIZE)}")
 				token.delete!("\n")
+
 				@@tokens[token] = [] unless @@tokens.include?(token)
 				@@tokens[token] << uuid
-				update_tracked_vault("#{uuid}", nil, nil, nil, token)
+
+				update_tracked_vault(uuid, nil, nil, nil, token)
 				return token
 			end
 
@@ -95,30 +124,31 @@ module Reedb
 			# 					tokens => Authentication token for applications
 			#
 			def track_vault(name, path, size, uuid)
-				@@config[:vaults]["#{uuid}"] = {} unless @@config[:vaults].include?(uuid)
+				@@config[:vaults][uuid] = {} unless @@config[:vaults].include?(uuid)
 
 				# Adds actual size as soon as the vault gets unlocked by an application
-				@@config[:vaults]["#{uuid}"][:meta] = MetaVault.new("#{name}", "#{path}", size, "#{uuid}")
-				@@config[:vaults]["#{uuid}"][:tokens] = [] unless @@config[:vaults]["#{uuid}"][:tokens]
-				@@config[:vaults]["#{uuid}"][:tokens] = []
+				@@config[:vaults][uuid][:meta] = MetaVault.new("#{name}", "#{path}", size, uuid)
+				@@config[:vaults][uuid][:tokens] = [] unless @@config[:vaults][uuid][:tokens]
+				@@config[:vaults][uuid][:tokens] = [] # Do I need this?
 
 				write_config
 			end
 
-			def untrack_vault uuid
-				@@config[:vaults]["#{uuid}"] = nil if @@config[:vaults].include?(uuid)
+			def untrack_vault(uuid)
+				@@config[:vaults].delete(uuid) if @@config[:vaults].include?(uuid)
+				write_config
 			end
 
 			def update_tracked_vault(uuid, name, path, size, token)
 				token.delete!("\n")
-				return nil unless @@config[:vaults].include?(uuid)
+				(puts 'ERROR! UUID not in config!'; return nil) unless @@config[:vaults].include?(uuid)
 
-				@@config[:vaults]["#{uuid}"][:meta].name = name if name
-				@@config[:vaults]["#{uuid}"][:meta].path = path if path
-				@@config[:vaults]["#{uuid}"][:meta].size = size if size
+				@@config[:vaults][uuid][:meta].name = name if name
+				@@config[:vaults][uuid][:meta].path = path if path
+				@@config[:vaults][uuid][:meta].size = size if size
 
-				@@config[:vaults]["#{uuid}"][:tokens] = [] unless @@config[:vaults]["#{uuid}"][:tokens]
-				@@config[:vaults]["#{uuid}"][:tokens] << token if token
+				@@config[:vaults][uuid][:tokens] = [] unless @@config[:vaults][uuid][:tokens]
+				@@config[:vaults][uuid][:tokens] << token if token
 
 				write_config
 			end
@@ -128,9 +158,9 @@ module Reedb
 			def remove_token(uuid, token)
 				token.delete!("\n")
 				return nil unless @@config[:vaults].include?(uuid)
-				return nil unless @@config[:vaults]["#{uuid}"][:tokens].include?(token)
-				
-				@@config[:vaults]["#{uuid}"][:tokens].delete(token)
+				return nil unless @@config[:vaults][uuid][:tokens].include?(token)
+
+				@@config[:vaults][uuid][:tokens].delete(token)
 				write_config
 			end
 
@@ -157,11 +187,11 @@ module Reedb
 
 				# At this point @@config has been loaded
 				vault_count = @@config[:vaults].size
-				DaemonLogger.write("Found #{vault_count} vault(s) on the system.", "debug")
+				DaemonLogger.write("Found #{vault_count} vault(s) on the system.", 'debug')
 			end
 
 			# Check vault integreties here!
-			# Will try every vault in the config and remove the ones that are no longer 
+			# Will try every vault in the config and remove the ones that are no longer
 			# available to avoid errors and access corruptions
 			#
 			def check_vault_integreties
@@ -178,6 +208,8 @@ module Reedb
 					DaemonLogger.write("Removing corrupted vault #{uuid}", 'warn')
 					@@config[:vaults].delete(uuid)
 				end
+
+				# Now save the mess you've made.
 				write_config
 			end
 
@@ -188,9 +220,38 @@ module Reedb
 			end
 
 			def read_config
-				data = File.open(@@config_path, "rb").read()
+				data = File.open(@@config_path, 'rb').read
 				@@config = Marshal.load(data)
 			end
+		end # Implicit required file, not inspected
+	end
+
+	class << self
+		# Returns
+
+		@@archos = nil
+		# @return [String] the platform/ architecture of the daemon and vault handler
+		def archos;
+			@@archos
+		end
+
+		@@pw_length = -1
+		# @return [Integer] the minimum passphrase length is
+		def passlength;
+			@@pw_length
+		end
+
+		@@verbose = false
+		# @return [Bool] whether verbose mode is enabled
+		def verbose?;
+			@@archos
+		end
+
+
+		@@daemon = true
+		# @return [Bool] whether Reedb is running as a daemon
+		def daemon?
+			@@archos
 		end
 	end
 
@@ -200,93 +261,197 @@ module Reedb
 
 		class << self
 
-			def init(options)
-				@@daemon = if options.include?(:daemon) then options[:daemon] else true end
+			# Initialise Reedb with a set of parameters passed into this method.
+			# Please check the wiki to find out what option parameters are
+			# available to use here.
+			#
+			# @param options [Hash] Parameters to run Reedb by sorted in a
+			# 							hash datastructure.
+			#
+			# @return nil
+			#
+			def init(options, &user_code)
+				unless options.include?(:os) && options.include?(:pw_length)
+					puts 'Missing :os (:linux|:osx) and/or :pw_length fields from options!'
+					exit Reedb::EXIT_OS_PARSE
+				end
+
+				# Checks if user code was provided and exits the entire application if not provided!
+				if user_code == nil && !options[:daemon]
+					puts 'No user function was provided to run! Reedb must run in daemon mode to do that!'
+					exit Reedb::EXIT_MISSING_USER_CODE
+				end
+
+				@@daemon = options.include?(:daemon) ? options[:daemon] : true
 				@@archos = options[:os]
 				@@pw_length = options[:pw_length]
-				@@verbose = if options.include?(:verbose) then options[:verbose] else false end
-				@@no_token = if options.include?(:no_token) then options[:no_token] else false end
+				@@verbose = options.include?(:verbose) ? options[:verbose] : false
+				@@no_token = options.include?(:no_token) ? options[:no_token] : false
+				override = options.include?(:force) ? options[:force] : false
 
 				if @@no_token
-					puts "NO_TOKEN mode has not been implemented yet! Please just use token authentication mode."
+					puts 'NO_TOKEN mode has not been implemented yet! Defaulting to token mode.'
 					@@no_token = false
 				end
-				
-				@@path = if options.include?(:path) then options[:path] else "&&HOME&&" end
+
+				# Now @@path is either a path OR a placeholder.
+				@@path = options.include?(:path) ? options[:path] : Reedb::DEFAULT_PATH
 
 				# Enable cleanup mode
 				# This means that the config will be cleaned and unused tokens removed
 				# instead of leaving them in the file and configurations.
 				# It is recommended to use cleanup mode.
 				#
-				@@cleanup = if options.include?(:cleanup) then options[:cleanup] else true end
+				@@cleanup = options.include?(:cleanup) ? options[:cleanup] : true
 
 				# Set of vaults that map a VaultBuffer to the vault itself.
 				# Never exposed outside the API
 				#
 				@@active_vaults = {}
-				
+
 				# List of tokens authorised for this daemon. Maps tokens to vault names.
 				# This is used for authentication and never exposed to the outside API
 				# NOTE! This is not used when the :no_token option is enabled
 				#
 				@@tokens = {} unless @@no_token
 
-				if @@archos == :linux
-					master_path = File.expand_path('~/.config/reedb/')
 
-					# Puts the folder in /etc if running as root
-					master_path = "/etc/reedb" if Utilities::parse_user == 'root'
+				# This is called when the default path applies
+				if @@path == Reedb::DEFAULT_PATH
+
+					# For good operating systems.
+					if @@archos == :linux
+						master_path = File.expand_path('~/.config/reedb/')
+						master_path = '/etc/reedb' if Utilities::parse_user == 'root'
+
+						log_path = File.expand_path('~/.config/reedb/logs/')
+
+						# For OSX
+					elsif @@archos == :osx
+						master_path = File.expand_path('~/Library/Application\ Support/reedb/')
+						master_path = '/Library/Application\ Support/reedb' if Utilities::parse_user == 'root'
 
-					log_path = File.expand_path('~/.config/reedb/logs/')
-					@@config_path = File.join("#{master_path}", "master.cfg")
+						log_path = File.expand_path('~/Library/Application\ Support/reedb/logs/')
 
-				elsif @@archos == :osx
-					master_path = File.expand_path('~/Library/Application\ Support/reedb/')
-					log_path = File.expand_path('~/Library/Application\ Support/reedb/logs/')
-					@@config_path = File.join("#{master_path}", "master.cfg")
+					elsif @@archos == :win
+						puts 'This is currently not supported :( Sorry.'
+						# Windows crap
+					elsif @@archos == :other
+						raise UnknownOSError.new, 'Operating system was not specified, yet an override path was not specified either. Can not continue without more information!'
+						exit(Reedb::EXIT_OS_PARSE)
+					else
+						raise UnknownOSError.new, "Could not recognise specified OS. What are you running? Why don't you go here:
+ getfedora.org :)"
+						exit(Reedb::EXIT_OS_PARSE)
+					end
 				else
-					# Windows crap
+					master_path = @@path
+					log_path = File.join("#{master_path}", 'logs')
 				end
 
-				# Changing file permissions. Does this do ANYTHING on windows?
-				FileUtils::mkdir_p("#{log_path}") # 744 (owned by $USER)
+				# Sets up the config path
+				@@config_path = File.join("#{master_path}", 'master.cfg')
+				@@lock_file = File.join("#{master_path}", 'lock')
+
+				# Now go create directories if they need to be created.
+				FileUtils::mkdir_p("#{log_path}") unless File.directory?("#{log_path}")
 				FileUtils::chmod_R(0744, "#{log_path}")
 				FileUtils::chmod_R(0744, "#{master_path}")
-				
+
+				# Now that pathing has been established, check if there is a lock file.
+				if File.exist?(@@lock_file) && !override
+					puts '[FATAL] Another instance of Reedb is already operating from this directory! Choose another directory or terminate the old instance first!'
+					exit(Reedb::EXIT_STILL_LOCKED)
+				elsif File.exist?(@@lock_file) && override
+					puts "There was another instance of Reedb running but you forced my hand. It's dead now..."
+				end
+
+				# Create a lock file
+				File.open(@@lock_file, 'w+') { |f| f.write('Hier koennte Ihre Werbung stehen.') }
+
+				# Start up the logging service.
 				Reedb::DaemonLogger.setup("#{log_path}")
+
+				# Now go and declare this daemon started and log it.
 				@@started = true
-				Reedb::DaemonLogger.write("Reedb was started successfully. Reading vault information now...", 'debug')
+				Reedb::DaemonLogger.write('Reedb was started successfully. Reading vault information now...', 'debug')
 
 				# Now cache the config
 				cache_config
 
-				# Open debounce tread and mirror current vault information onto it.
-				# debounce_handler
-			end
+				'' '
+				The bottom part initiates the main run look that bounces between debouncer thread and user code.
+				This function only returns after all the user code was handled.
+				' ''
+
+				# Open debounce object
+				@@debouncer = Reedb::Debouncer.new(self)
+
 
+				# Now actually run the code on two threads and hope that the scheduler does it's job!
+				@@debouncerThread = Thread.new { @@debouncer.main }
+				user = Thread.new(&user_code)
 
-			def terminate(reason = nil)
-				puts "Must start process first" unless @@started
+				# Wait for user code to terminate
+				user.join
+
+				# Then call terminate just in case they haven't yet
+				Reedb::Core::terminate('null', true)
+			end
+
+			# Terminate Reedb with a reason. After calling this function the
+			# core functionality (and depending interfaces on the stack)
+			# is no longer available.
+			#
+			# @param reason [String] Reason why Reedb is being terminated to
+			# 							be written into central logs.
+			#
+			# @return nil
+			#
+			def terminate(reason = nil, silent = false)
+				puts 'Must start process first' if !@@started && !silent
+				return unless @@started
 
-				new_reason = "unknown reason"
-				new_reason = "a user request" if reason == "user"
-				new_reason = "a system request" if reason == "root"
+				new_reason = 'unknown reason'
+				new_reason = 'a user request' if reason == 'user'
+				new_reason = 'a system request' if reason == 'root'
 
 				# My first easter-egg. Yay! :)
-				new_reason = "the illuminati" if reason == "aliens"
+				new_reason = 'the illuminati' if reason == 'aliens'
 
-				DaemonLogger.write("[TERMINATION]: Scheduling termination because of #{new_reason}.")
+				DaemonLogger.write("[TERM]: Scheduling termination because of #{new_reason}.")
 
-				# TODO: Close the debounce thread here.
+				# Let the debouncer thread time out
+				@@debouncer.running = false
+				sleep(Reedb::THREAD_TIMEOUT_TIME)
+
+				# Then join it and be done with it
+				@@debouncerThread.join
 
-				@@started = false
 				# Closing open vaults here
-				counter = 0 ; @@active_vaults.each { |k, v| v.close; counter += 1 }
-				DaemonLogger.write("[TERMINATION]: Closed #{counter} vaults. Done!")
+				counter = 0
+
+				# Iterate over active vaults
+				@@active_vaults.each do |uuid, vault|
+					vault.close
+
+					# Iterate over the token list and remove them until all are gone
+					# TODO: Search for a more Ruby-esk way to do this.
+					while !@@config[:vaults][uuid][:tokens].empty?
+						Reedb::Daemon::free_token(@@config[:vaults][uuid][:tokens][0])
+					end
+					counter += 1
+				end
+				write_config
+
+				# Then declare Reedb terminated and remove the lock file
+				@@started = false
+				File.delete(@@lock_file) if File.exist?(@@lock_file)
+				DaemonLogger.write("[TERM]: Closed #{counter} vaults. Done!")
+				return 0
 			end
 		end
-	end
+	end # module core end.
 
 	# Config submodule of the Interface stack
 	module Config
@@ -294,28 +459,39 @@ module Reedb
 			include Reedb
 			class << self
 
-				def dump_config
-					return @@config
-				end
-
 				# Set a global timeout time to all vaults. Determine when a vault will
 				# be unloaded or the daemon will lock itself.
 				# Time provided in seconds
 				#
-				def global_timeout dt
+				def global_timeout(dt)
+					Reedb::debouncer.set_custom_timeout(dt)
 				end
 
 				# Set the log state of the daemon. That determines what error calls will
 				# be logged and what will be ommited.
 				#
-				def logging_state state
+				def logging_state(state)
+					state << ''
 				end
 
 				# Define a minimal passphrase length for vaults to have. This can
 				# break access to vaults if they were created on a different system
 				# so be careful with this!
-				# 
-				def passphrase_length length
+				#
+				def passphrase_length(length)
+					length << ''
+				end
+
+				# Because Reedb can be operated out of different paths at runtime
+				# (or initiation) this function in the Config::Master interface
+				# returns the path that this Reedb instance is keeping it's config.
+				#
+				# Because of this, external applications can write their configs into
+				# $(OPERAND_PATH)/apps if they do not bring their own configs directory.
+				#
+				# @return op_path
+				#
+				def get_operation_path
 				end
 
 				# Cleans the config file of broken vaults and config items. This is
@@ -324,26 +500,31 @@ module Reedb
 				def clean_config
 
 				end
-			end
-		end
+			end # self class end
+		end # module Config::Master end
 
 		module Vault
 			include Reedb
 			class << self
-				def set_vault_timeout dt
+				def set_vault_timeout(dt)
+					dt << ''
 				end
 
 				def add_header_field(field, type)
+					field << ''
+					type << field
 				end
 
 				def change_passphrase(old_phrase, new_phrase)
+					old_phrase << ''
+					new_phrase << '\n'
 				end
 
 				def read_config
 				end
-			end
-		end
-	end
+			end # self class end
+		end # module Config::Vault end
+	end # module config end
 
 	# Vault submodule of the Interface stack
 	module Vault
@@ -355,42 +536,42 @@ module Reedb
 			# Vaults are ordered in a dictionary under their UUID that's used by the
 			# Reedb daemon.
 			#
-			# => A compiled JSON of vaults with uuid, name, path and size
+			#
+			# @return available_vaults [Hash]
 			#
 			def available_vaults
 				available = {}
 
 				@@config[:vaults].each do |uuid, value|
-					# puts @@config[:vaults]["#{uuid}"]
-					available["#{uuid}"] = {}
-					available["#{uuid}"][:name] = value[:meta].name
-					available["#{uuid}"][:path] = value[:meta].path
-					available["#{uuid}"][:size] = value[:meta].size
+					# puts @@config[:vaults][uuid]
+					available[uuid] = {}
+					available[uuid][:name] = value[:meta].name
+					available[uuid][:path] = value[:meta].path
+					available[uuid][:size] = value[:meta].size
 				end
 				return available
 			end
 
-			# Creates a new vault on the current system. Returns nil if vault already existed at
-			# location. Returns a token if the creation and authentication was successful on the
-			# user side.
-			# Also adds that token to the @@tokens list
+			# Creates a new vault on the current system. Returns nil if vault
+			# already existed at location. Returns a token if the creation
+			# and authentication was successful on the user side.
 			#
-			# THROWS A LOT OF EXCEPTIONS!
+			# Also adds that token to the @@tokens list.
 			#
+			# ! THROWS A LOT OF EXCEPTIONS !
 			#
-			# Params: 	
-			# 				'name' of the vault
-			# 				'path' of the vault
-			# 				user 'passphrase'
-			# 				'encryption' method (:aes, :twofish, :auto)
+			# @param name [String] Name of the vault
+			# @param path [String] Path of the vault
+			# @param passphrase [String] User passphrase for decryption
+			# @param encryption [enum] Encryption method (:aes, :twofish, :auto)
 			#
-			# => Base64 encoded token | nil if errors occured.
+			# @return token [Base64 String]
 			#
 			def create_vault(name, path, passphrase, encryption = :auto)
 				# Creates new UUIDs until one is found that doesn't already exist in the scope
-				uuid = nil
+				uuid = UUID.new
 				loop do
-					uuid = UUID::create_v1
+					uuid = uuid.generate
 					(break) unless @@config[:vaults].include?(uuid)
 				end
 
@@ -399,48 +580,57 @@ module Reedb
 				tmp_vault = ReeVault.new("#{name}", "#{path}", encryption).create("#{passphrase}")
 
 				# Creates a metavault with name, path, size and uuid to be tracked on the system
-				# metavault = MetaVault.new("#{name}", "#{path}", 0, "#{uuid}")
+				# metavault = MetaVault.new("#{name}", "#{path}", 0, uuid)
 
 				# Adds vault to the active set of vaults
 				@@active_vaults[uuid] = tmp_vault
 
-				# Generates a token
-				unless @@no_token
-					token = generate_token(uuid, path)
-					track_vault(name, path, 0, uuid)
-					return token.delete!("\n")
-				end
+				# Track the vault in the config
+				track_vault(name, path, 0, uuid)
 
-				# In case token authentication was disabled
-				track_vault(uuid, nil)
-				return nil
-			end
+				# Generate a token
+				token = generate_token(uuid, path)
 
+				# Generate a token for the debouncer and remove it if the vault was already accessable
+				debouncer_token = generate_token(uuid, path)
+				check = mirror_debounce(uuid, debouncer_token, Reedb::DEB_ADD)
+				Reedb::remove_token(uuid, debouncer_token) unless check
 
-			# ONLY PERMITTED WHEN IN NO_TOKEN MODE! WILL BE DISABLED AUTOMATICALLY WHEN
-			# USING THE HTTP MODULE!
+				# Then return the token for the user
+				token.delete!("\n")
+				return token
+			end
+
+			# !!! NOT IMPLEMENTED YET !!!
 			#
+			# ONLY PERMITTED WHEN IN NO_TOKEN MODE!
 			# Loads a vault with a UUID and passphrase into the current vault set.
 			# Ignores the token set (as not applicable when in token mode) and simply
 			# returns a confirmation that vault access was granted.
 			#
 			def access_vault(uuid, passphrase)
-				raise FunctionNotImplementedError.new, "This has not been implemented yet! Use token authentication via the DAEMON module."
+				raise MissingTokenError.new, 'Reedb is running in token mode. Please specify a token via the DAEMON module
+access handler' unless @@no_token
+
+				raise FunctionNotImplementedError.new, 'This has not been implemented yet! Use token authentication via the DAEMON module.'
 				return false
-			end
 
+				# debouncer_token = generate_token(uuid, path)
+				# check = Reedb::mirror_debounce(uuid, debouncer_token, Reedb::DEB_ADD)
+				# Reedb::remove_token(uuid, debouncer_token) unless check
+
+			end
 
-			# Removes a vault from the file system. This requires special privileges 
-			# to do via this interface to prevent deleting vaults without the users 
-			# permission. Will also fire a user interrupt to alert them of this 
+			# Removes a vault from the file system. This requires special privileges
+			# to do via this interface to prevent deleting vaults without the users
+			# permission. Will also fire a user interrupt to alert them of this
 			# behaviour depending on platform.
 			#
-			# Params:   
-			#       		'uuid' of the vault
-			#       		'passphrase' of the vault
-			#       		'token' of an application that needs to be authorised
+			# @param uuid [String] UUID of a vault (as an ID)
+			# @param passphrase [String] User passphrase for decryption
+			# @param token [String] Authentication token for validation
 			#
-			# => Returns boolean describing success
+			# @return success [Boolean]
 			#
 			def remove_vault(uuid, passphrase, token)
 				token.delete!("\n")
@@ -452,22 +642,24 @@ module Reedb
 
 				# Return false if vault is currently locked
 				return false if @@active_vaults[uuid].locked?
-	 
+
 				# Mark a vault for removal and only actually
 				raise FunctionNotImplementedError.new, "This has not been implemented yet! Don't do this."
 				return false
 			end
 
-			# Adds a new vault to the tracking scope of this Reedb daemon. Does not grant access
-			# or generate a new token for application interaction.
+			# Adds a new vault to the tracking scope of this Reedb daemon.
+			# Does not grant access or generate a new token for application interaction.
 			# On a new install usually called just before requesting a token
-			# 
-			# Params: 		'name' of the vault
-			# 				'path' on the systen
+			#
+			# @param name [String] Name of the vault
+			# @param path [String] Path of the vault
+			#
+			# @return success [Boolean]
 			#
 			def scope_vault(name, path)
 				# Checks if that specific vault was already scoped
-				@@config[:vaults].each do |key, value|
+				@@config[:vaults].each do |_, value|
 					if value[:meta].name == "#{name}" && value[:meta].path == "#{path}"
 						DaemonLogger.write("Vault already scoped at #{path}", 'info')
 						raise VaultAlreadyScopedError.new, "Vault #{name} already scoped!"
@@ -477,14 +669,14 @@ module Reedb
 				vault = ReeVault.new("#{name}", "#{path}", :auto)
 				# If it hasn't, proceed here
 				if vault.try?
-					uuid = nil
+					uuid = UUID.new
 					loop do
-						uuid = UUID::create_v1
+						uuid = uuid.generate
 						(break) unless @@config[:vaults].include?(uuid)
 					end
 
 					# At this point a vault has been confirmed and a UUID generated
-					track_vault(name, path, vault.count, "#{uuid}")
+					track_vault(name, path, vault.count, uuid)
 					DaemonLogger.write("Vault successfully scoped at #{path}", 'info')
 					cache_config
 					return true
@@ -495,131 +687,162 @@ module Reedb
 				end
 			end
 
+
 			# Removes a vault from the application scope with a uuid.
 			# Closes the vault from the active vault set.
 			#
-			# Returns nil if no such vault was scoped before.
+			# @param uuid [String] UUID of a vault (as an ID)
+			#
+			# @return success [Boolean]
 			#
 			def unscope_vault(uuid)
-				unless @@config[:vaults]["#{uuid}"]
+				unless @@config[:vaults][uuid]
 					raise VaultNotScopedError.new, "Vault #{name} not scoped!"
-					return nilp
+					return nil
 				end
 
-				path = @@config[:vaults]["#{uuid}"][:path]
+				path = @@config[:vaults][uuid][:path]
 				DaemonLogger.write("Unscoping vault #{uuid} at #{path}")
-				@@active_vaults["#{uuid}"].close if @@active_vaults["#{uuid}"]
-				@@config[:vaults].delete("#{uuid}")
+				@@active_vaults[uuid].close if @@active_vaults[uuid]
+				@@config[:vaults].delete(uuid)
 				cache_config
 			end
 
-			# Request token for a vault permanently.
-			# Only used if @@no_token == false. Unlocks a vault as well
-			# with the user passphrase
+			# List headers from a vault with a search qeury (nil by default).
+			# Can only be used with a token on vaults that authentication has
+			# been successful before.
 			#
-			# Params: 		'uuid' of the vault
-			#       		'search' search queury as described in the wiki
+			# @param uuid [String] UUID of a vault (as an ID)
+			# @param token [String] Authentication token for access
+			# @param search [String] Search qeury as described in the wiki
 			#
-			# => Returns list of headers present in the vault
-			#   according to the search queury
+			# @return headers [List]
 			#
 			def access_headers(uuid, token, search = nil)
 				token.delete!("\n")
-				raise VaultNotAvailableError.new, "The vault you have requested data from is not currently active on this system." unless @@active_vaults["#{uuid}"]
 
-				raise UnknownTokenError.new, "The token you provided is unknown to this system. Access denied!" unless @@tokens[token]
+				raise VaultNotAvailableError.new, 'The vault you have requested data from is not currently active on this system.' unless @@active_vaults[uuid]
+				raise UnknownTokenError.new, 'The token you provided is unknown to this system. Access denied!' unless @@tokens[token]
+				raise UnautherisedTokenError.new, 'The token you provided currently has no access to the desired vault. Access denied!' unless @@tokens[token].include?(uuid)
 
-				raise UnautherisedTokenError.new, "The token you provided currently has no access to the desired vault. Access denied!" unless @@tokens[token].include?(uuid)
+				debouncer.debounce_vault(uuid)
 
-
-				return @@active_vaults["#{uuid}"].list_headers(search)
+				return @@active_vaults[uuid].list_headers(search)
 			end
 
-
-			# Request token for a vault permanently.
-			# Only used if @@no_token == false. Unlocks a vault as well
-			# with the user passphrase
+			# Access file contents with a file ID in a vault that a token has already
+			# been authenticated on.
+			#
+			# Depending on the history flag (false by default) the history or only
+			# current dataset will be returned.
 			#
-			# Params:   'uuid' of the vault
-			#       		'file_name' file identifier to access
+			# @param uuid [String] UUID of a vault (as an ID)
+			# @param token [String] Authentication token for access
+			# @param file_name [String] File identifier
+			# @param history [Boolean] history idenfitier
 			#
-			# => Returns contents (including headers) of a file either
-			#   as it's current version or it's edit history.
+			# @return file [Hash]
 			#
 			def access_file(uuid, token, file_name, history = false)
 				token.delete!("\n")
-				raise VaultNotAvailableError.new, "The vault you have requested data from is not currently active on this system." unless @@active_vaults["#{uuid}"]
 
-				raise UnknownTokenError.new, "The token you provided is unknown to this system. Access denied!" unless @@tokens[token]
+				raise VaultNotAvailableError.new, 'The vault you have requested data from is not currently active on this system.' unless @@active_vaults[uuid]
+				raise UnknownTokenError.new, 'The token you provided is unknown to this system. Access denied!' unless @@tokens[token]
+				raise UnautherisedTokenError.new, 'The token you provided currently has no access to the desired vault. Access denied!' unless @@tokens[token].include?(uuid)
 
-				raise UnautherisedTokenError.new, "The token you provided currently has no access to the desired vault. Access denied!" unless @@tokens[token].include?(uuid)
-				return @@active_vaults["#{uuid}"].read_file(file_name, history)
+				debouncer.debounce_vault(uuid)
+
+				return @@active_vaults[uuid].read_file(file_name, history)
 			end
 
-			# Request token for a vault permanently.
-			# Only used if @@no_token == false. Unlocks a vault as well
-			# with the user passphrase
+
+			# Access file contents with a file ID in a vault that a token has already
+			# been authenticated on.
+			#
+			# Inserts data into a vault. Depending on parameters and runtime settings
+			# this function has different effects. It can be used to create a new file
+			# if it doesn't already exists.
+			#
+			# Please refer to the wiki for details on how to use this function as it
+			# (! MAY !) have unwanted side-effects if it is used wrong!
 			#
-			# Params:   'uuid' of the vault
-			#       		'file_name' file identifier to access
+			# @param uuid [String] UUID of a vault (as an ID)
+			# @param token [String] Authentication token for access
+			# @param file_name [String] File identifier
+			# @param data [Hash] Data that should be written to the vault.
 			#
-			# => Returns contents of a file either as it's current
-			#   version or it's edit history
+			# @return file [Hash]
 			#
 			def insert(uuid, token, file_name, data)
 				token.delete!("\n")
-				raise VaultNotAvailableError.new, "The vault you wish to insert data to is not currently active on this system." unless @@active_vaults["#{uuid}"]
 
-				raise UnknownTokenError.new, "The token you provided is unknown to this system. Access denied!" unless @@tokens[token]
+				raise VaultNotAvailableError.new, 'The vault you have requested data from is not currently active on this system.' unless @@active_vaults[uuid]
+				raise UnknownTokenError.new, 'The token you provided is unknown to this system. Access denied!' unless @@tokens[token]
+				raise UnautherisedTokenError.new, 'The token you provided currently has no access to the desired vault. Access denied!' unless @@tokens[token].include?(uuid)
 
-				raise UnautherisedTokenError.new, "The token you provided currently has no access to the desired vault. Access denied!" unless @@tokens[token].include?(uuid)
 
 				DaemonLogger.write("Writing data to #{uuid}", 'debug')
+				@@debouncer.debounce_vault(uuid)
+				@@active_vaults[uuid].update(file_name, data)
 
-				@@active_vaults["#{uuid}"].update(file_name, data)
+				update_tracked_vault(uuid, nil, nil, @@active_vaults[uuid].count, token)
+				return nil
 			end
 
-			# Request token for a vault permanently.
-			# Only used if @@no_token == false. Unlocks a vault as well
-			# with the user passphrase
+			# Removes a file from a vault that a token was authorised to
+			# access. File is identified via an ID handle. This operation
+			# is dangerous as it can NOT be reverted!
 			#
-			# Params:   'uuid' of the vault
-			#       		'file_name' file identifier to access
+			# @param uuid [String] UUID of a vault (as an ID)
+			# @param token [String] Authentication token for access
+			# @param file_name [String] File identifier
 			#
-			# => Returns contents of a file either as it's current
-			#   version or it's edit history
+			# @return nil
 			#
 			def remove(uuid, token, file_name)
 				token.delete!("\n")
-				raise VaultNotAvailableError.new, "The vault you wish to insert data to is not currently active on this system." unless @@active_vaults["#{uuid}"]
-
-				raise UnknownTokenError.new, "The token you provided is unknown to this system. Access denied!" unless @@tokens[token]
 
-				raise UnautherisedTokenError.new, "The token you provided currently has no access to the desired vault. Access denied!" unless @@tokens[token].include?(uuid)
+				raise VaultNotAvailableError.new, 'The vault you have requested data from is not currently active on this system.' unless @@active_vaults[uuid]
+				raise UnknownTokenError.new, 'The token you provided is unknown to this system. Access denied!' unless @@tokens[token]
+				raise UnautherisedTokenError.new, 'The token you provided currently has no access to the desired vault. Access denied!' unless @@tokens[token].include?(uuid)
 
 				DaemonLogger.write("Writing data to #{uuid}", 'debug')
+				Reedb::debouncer.debounce_vault(uuid)
 
-				@@active_vaults["#{uuid}"].remove_file(file_name)
+
+				@@active_vaults[uuid].remove_file(file_name)
+				update_tracked_vault(uuid, nil, nil, @@active_vaults[uuid].count, token)
+				return nil
 			end
 
 
-			# Ends the exchange with a vault. Removes token from active vault record
+			# Closes a vault to end the file transaction between you and the vault.
+			# The encryption key will be unloaded and scrubbed from memory which means
+			# you will have to unlock a vault again
+			# (which usually means more user interaction).
+			#
+			# @param uuid [String] UUID of a vault (as an ID)
+			# @param token [String] Authentication token for access
+			#
+			# @return nil
 			#
 			def close_vault(uuid, token)
 				token.delete!("\n")
-				raise VaultNotAvailableError.new, "The vault you have requested data from is not currently active on this system." unless @@active_vaults["#{uuid}"]
 
-				raise UnknownTokenError.new, "The token you provided is unknown to this system. Access denied!" unless @@tokens[token]
+				raise VaultNotAvailableError.new, 'The vault you have requested data from is not currently active on this system.' unless @@active_vaults[uuid]
+				raise UnknownTokenError.new, 'The token you provided is unknown to this system. Access denied!' unless @@tokens[token]
+				raise UnautherisedTokenError.new, 'The token you provided currently has no access to the desired vault. Access denied!' unless @@tokens[token].include?(uuid)
 
-				raise UnautherisedTokenError.new, "The token you provided currently has no access to the desired vault. Access denied!" unless @@tokens[token].include?(uuid)
+				DaemonLogger.write("Closing vault with #{uuid}.", 'debug')
 
-				DaemonLogger.write("Closing vault with #{uuid}.", "debug")
+				# Remove the vault from the debouncer
+				@@debouncer.remove_vault(uuid)
 
 				# Close the vault
-				@@active_vaults["#{uuid}"].close
+				@@active_vaults[uuid].close
 
 				# Delete the vault from the active_vault record with UUID
-				@@active_vaults.delete("#{uuid}")
+				@@active_vaults.delete(uuid)
 
 				# TODO: Alert other applications
 				# TODO: Don't delete the token if it is being used to access
@@ -627,39 +850,49 @@ module Reedb
 				@@tokens.delete(token)
 
 				# Removes token from config
-				# TODO: FIX ME?!
-				@@config[:vaults]["#{uuid}"][:tokens].delete(token)
+				@@config[:vaults][uuid][:tokens].delete(token)
 				write_config
 			end
-		end
-	end
+		end # self class end
+	end # module vault end
 
 	module Daemon
 		include Reedb
 
 		class << self
+
 			# Request token for a vault permanently.
 			# Only used if @@no_token == false. Unlocks a vault as well
 			# with the user passphrase
 			#
-			# Params: 		'name' of the vault
-			# 				'passphrase' to unlock
+			# @param uuid [String] Internal UUID of the vault
+			# @param passphrase [String] Passphrase of the vault.
+			# @param permanent [Boolean] Indicates whether or not the app intends to come back
 			#
-			# => Returns token for vault
+			# @return token [Base64 String]
 			#
-			def request_token(uuid, passphrase, parmanent = false)
+			def request_token(uuid, passphrase, permanent = false)
 				# If the vault is not currently open
 				unless @@active_vaults.include?(uuid)
 					unless @@config[:vaults][uuid]
-						DaemonLogger.write("The requested vault is unknown to this system. Aborting operation!", 'error')
+						DaemonLogger.write('The requested vault is unknown to this system. Aborting operation!', 'error')
 						raise VaultNotScopedError.new, "Requested vault #{uuid} is unknown to reedb. Has it been scoped before?"
 					end
-					# Continue
+
+					# Continue by initialising the vault according to saved information
 					name = @@config[:vaults][uuid][:meta].name
 					path = @@config[:vaults][uuid][:meta].path
-					@@active_vaults[uuid] = ReeVault.new("#{name}", "#{path}", :auto).load(passphrase)
+					@@active_vaults[uuid] = ReeVault.new("#{name}", "#{path}", :auto).load("#{passphrase}")
 				end
-				token = generate_token(uuid, path)
+
+				token = generate_token(uuid, path, permanent)
+
+				# Adds a token to the debouncer if it needs one, removes it again if it already knows and tracks the vault.
+				debouncer_token = generate_token(uuid, path)
+				check = mirror_debounce(uuid, debouncer_token, Reedb::DEB_ADD)
+				remove_token(uuid, debouncer_token) unless check
+
+				# puts "Tokens: #{@@tokens}"
 				return token
 			end
 
@@ -667,73 +900,86 @@ module Reedb
 			# an authentication token for a vault.
 			#
 			def access_with_token(uuid, token, passphrase)
-				token.delete!("\n")
+				token.delete!('\n')
+				raise UnknownTokenError.new, 'Unknown Token!' unless @@config['tokens'][uuid]
 			end
+
 			# Call this function to free a token and remove it from the access
 			# tree. This means that the vault it used to access are not removed or
 			# unloaded for other applications to use. But the token can no longer
 			# be used for file access.
 			#
-			def free_token(token)
+			# @param token [String] Token to be freed
+			#
+			def free_token(token, batch = false)
 				token.delete!("\n")
 
 				# Throw a warning if the token isn't valid in the first place.
-				raise UnknownTokenError.new, "The token you provided is unknown to this system" unless @@tokens.include?(token)
+				raise UnknownTokenError.new, 'The token you provided is unknown to this system' unless @@tokens.include?(token)
 
 				@@tokens[token].each do |uuid|
-					@@config[:vaults]["#{uuid}"][:tokens].delete(token)
+					@@config[:vaults][uuid][:tokens].delete(token)
 				end
 
-				write_config
+				write_config unless batch
 			end
-		end #self class end
+		end # self class end
 	end # module Daemon end
 end # Module Reedb end
 
-passphrase = "1234567890123"
-name = "default"
-path = "/home/spacekookie/Desktop"
-
-
-
-# name = "mega2"
-# path = "/home/spacekookie"
-# passphrase = "omg_awesome_sauce"
-
-# Reedb::Core::init({:os=>:linux, :pw_length=>12})
-#token = Reedb::Vault::create_vault(name, path, passphrase, :auto)
-#puts token
-# puts Reedb::generate_token("something", "blob")
-
-# Reedb::Vault::scope_vault(name, path)
-
-# puts Reedb::Vault::available_vaults
-# Reedb::Vault::create_vault(name, path, user_pw)
-
-# available = Reedb::Vault::available_vaults
-# # puts "Available vaults: #{available}\n"
-
-# puts Reedb::Config::Master::dump_config
-# puts ""
-# target = nil ; available.each { |uuid, meta| (target = uuid) if meta[:name] == "default" }
-
-# puts "Target: #{target}"
-
-# my_token = Reedb::Daemon::request_token(target, passphrase)
-# puts "#{my_token}\n"
-# search_qeuery = "tags=awsome#urls=www.lonelyrobot.io"
-
-# headers = Reedb::Vault::access_headers(target, my_token, nil)
-# print "#{headers}\n"
-
-# Reedb::Vault::insert(target, my_token, "Lonely Robot", data1)
-# Reedb::Vault::insert(target, my_token, "Lonely Robot", data2)
-# Reedb::Vault::insert(target, my_token, "Lonely Robot", data3)
-
-# puts Reedb::Vault::access_file(target, my_token, "Lonely Robot", true)
-
-#headers = Reedb::Vault::access_headers(target, my_token)
-#puts "Vault headers: #{headers}\n\n"
-
-# Reedb::Vault::close_vault(target, my_token)
-# Reedb::Core::terminate("aliens")
+# These options should be set when using Reedb as a normal dependency
+# options = {
+# 	 :daemon => false, # !!! IMPORTANT !!!
+# 	 :os => :linux, # Pick whichever one applies (:linux, :osx, :win, :other)
+# 	 :pw_length => 16, # Is mandatory anyways
+# 	 :force => true, # Overwrites old instances of Reedb that might still be running
+# 	 # :no_token => true, # Doesn't actually do anything yet right now.
+# 	 # :path => "/some/path/here" # !!! IMPORTANT !!!
+# }
+#
+# def test_script
+# 	userpw = 'peterpanistderheld'
+#
+# 	begin
+# 		Reedb::Vault::create_vault('default', '/home/spacekookie/Desktop', userpw)
+# 	rescue
+# 		puts 'Vault already exists...'
+# 	end
+#
+# 	all = Reedb::Vault::available_vaults
+# 	tuuid = nil
+# 	all.each { |uuid, data| tuuid = uuid if data[:name] == 'default' && data[:path] == '/home/spacekookie/Desktop' }
+#
+# 	token = Reedb::Daemon::request_token(tuuid, userpw)
+#
+# 	data = {
+# 		 'body' => {
+# 				'password' => 'mega_secure_password',
+# 				'username' => 'spacekookie'
+# 		 },
+# 		 'header' => {
+# 				'urls' => 'www.lonelyrobot.io',
+# 				'tags' => %w(website games awesome)
+# 		 }
+# 	}
+# 	Reedb::Vault::insert(tuuid, token, 'My Face', data)
+#
+# 	file = Reedb::Vault::access_file(tuuid, token, 'My Face')
+# 	puts file
+#
+# 	Reedb::Daemon::free_token(token)
+#
+# 	new_token = Reedb::Daemon::request_token(tuuid, userpw)
+#
+# 	begin
+# 		Reedb::Vault::insert(tuuid, token, 'MegaBlast', data)
+# 	rescue
+# 		puts 'This token is no longer valid!'
+# 	end
+#
+# 	Reedb::Vault::insert(tuuid, new_token, 'MegaBlast', data)
+# 	sleep(15)
+# end
+#
+# # Running Reedb with custom user code
+# Reedb::Core::init(options) { test_script }