s3db 0.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3458f2b36ed8c03cf0a51b7974f6404f64d15207
+  data.tar.gz: c140dda6f8ee3f73ff1e0331fedaae242c8da6dc
+SHA512:
+  metadata.gz: 6c53ba31f46f5fcfcb5a4e5282aa7a0981c52f24e137028ac7c3e425aa01c3aa4b24e1d3de9c270e8df521289894caba2b44ce6bf06ea04afaf71a3a1d36f429
+  data.tar.gz: 4816697a89e02e03ee9942c28392581e9cedc36dd6d401f7eeade1837cd395b25e2fba98a7f8f17c4f277fa22ff6371a374ca2476af875bc9ae18fdc14d5fb10

data/Gemfile

@@ -0,0 +1,10 @@
+source 'https://rubygems.org'
+
+gem 'uuidtools'
+gem 'json'
+
+group :development do
+  gem 'rspec'
+  gem 'simplecov', require: false
+  gem 'guard-rspec', require: false
+end

data/Gemfile.lock

@@ -0,0 +1,74 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    coderay (1.1.0)
+    diff-lcs (1.2.5)
+    docile (1.1.5)
+    ffi (1.9.10)
+    formatador (0.2.5)
+    guard (2.13.0)
+      formatador (>= 0.2.4)
+      listen (>= 2.7, <= 4.0)
+      lumberjack (~> 1.0)
+      nenv (~> 0.1)
+      notiffany (~> 0.0)
+      pry (>= 0.9.12)
+      shellany (~> 0.0)
+      thor (>= 0.18.1)
+    guard-compat (1.2.1)
+    guard-rspec (4.6.4)
+      guard (~> 2.1)
+      guard-compat (~> 1.1)
+      rspec (>= 2.99.0, < 4.0)
+    json (1.8.3)
+    listen (3.0.3)
+      rb-fsevent (>= 0.9.3)
+      rb-inotify (>= 0.9)
+    lumberjack (1.0.9)
+    method_source (0.8.2)
+    nenv (0.2.0)
+    notiffany (0.0.8)
+      nenv (~> 0.1)
+      shellany (~> 0.0)
+    pry (0.10.2)
+      coderay (~> 1.1.0)
+      method_source (~> 0.8.1)
+      slop (~> 3.4)
+    rb-fsevent (0.9.6)
+    rb-inotify (0.9.5)
+      ffi (>= 0.5.0)
+    rspec (3.3.0)
+      rspec-core (~> 3.3.0)
+      rspec-expectations (~> 3.3.0)
+      rspec-mocks (~> 3.3.0)
+    rspec-core (3.3.2)
+      rspec-support (~> 3.3.0)
+    rspec-expectations (3.3.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-mocks (3.3.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.3.0)
+    rspec-support (3.3.0)
+    shellany (0.0.1)
+    simplecov (0.10.0)
+      docile (~> 1.1.0)
+      json (~> 1.8)
+      simplecov-html (~> 0.10.0)
+    simplecov-html (0.10.0)
+    slop (3.6.0)
+    thor (0.19.1)
+    uuidtools (2.1.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  guard-rspec
+  json
+  rspec
+  simplecov
+  uuidtools
+
+BUNDLED WITH
+   1.10.6

data/bin/s3db

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+puts 'success'
+

data/lib/s3db.rb

@@ -0,0 +1,16 @@
+require 'rubygems'
+require 'bundler/setup'
+Bundler.require(:default)
+
+require_relative 's3db/utils'
+require_relative 's3db/collection'
+require_relative 's3db/database'
+require_relative 's3db/record'
+require_relative 's3db/backend'
+require_relative 's3db/file_backend'
+
+module S3DB
+  class << self
+    attr_accessor :backend
+  end
+end

data/lib/s3db/backend.rb

@@ -0,0 +1,4 @@
+module S3DB
+  class Backend
+  end
+end

data/lib/s3db/collection.rb

@@ -0,0 +1,70 @@
+module S3DB
+  class Collection
+    attr_reader :database, :name
+
+    class << self
+      # Create a new collection.
+      #
+      # database  - Database attached to collection. Required.
+      # name      - String name of the collection. Required.
+      #
+      # returns a new Collection.
+      def create(database, name)
+        collection = new(database, name)
+        collection.save
+
+        collection
+      end
+    end
+
+    # Instantiate a new collection, without writing it to disk.
+    #
+    # database  - Database attached to collection. Required.
+    # name      - String name of the collection. Required.
+    #
+    # returns a new Collection, validated but unwritten.
+    def initialize(database, name)
+
+      # Store the database and collection name
+      @database = database
+      @name = Utils.sanitize(name)
+
+      # Sanity check the database and collection name
+      validate!
+
+      # Yield self for configs, if people want to.
+      yield self if block_given?
+    end
+
+    # Validate a collection to ensure that it's sane.
+    #
+    # returns nil on success; raises an error on failure.
+    def validate!
+      unless @database.is_a?(S3DB::Database)
+        raise ArgumentError, 'database must be an S3DB::Database!'
+      end
+
+      unless @name.is_a?(String)
+        raise ArgumentError, 'name must be a String!'
+      end
+
+      nil
+    end
+
+    def list_records
+      @database.backend.list_records(@database.name, @name).map do |file|
+        @database.backend.read_record(@database.name, @name, file)
+      end
+    end
+
+    # Write the collection skeleton to disk.
+    #
+    # Returns nil.
+    def save
+      @database.backend.write_collection(@database.name, @name)
+      @database.backend.write_schema(@database.name, @name, @schema.to_json)
+
+      nil
+    end
+  end
+end

data/lib/s3db/database.rb

@@ -0,0 +1,100 @@
+module S3DB
+  class Database
+    attr_reader :backend, :name
+
+    class << self
+      # Create a new database.
+      #
+      # backend   - S3DB::Backend subclass. Required.
+      # db_name   - String name of the database to create. Required.
+      #
+      # returns a new S3DB::Database on success, raises an error on failure.
+      def create(backend, db_name)
+        begin
+          backend.write_db(db_name)
+        rescue Errno::EEXIST
+          raise ArgumentError, 'database exists!'
+        end
+
+        new(backend, db_name)
+      end
+
+      # Drop a database.
+      #
+      # backend   - S3DB::Backend subclass. Required.
+      # db_name   - String name of database to drop. Required.
+      #
+      # returns the String database name on success, raises an error on failure.
+      def drop(backend, db_name)
+        backend.delete_db(db_name)
+      end
+    end
+
+    # Create a new DB instance.
+    #
+    # backend   - S3DB::Backend subclass. Required.
+    # db_name   - String name of database. Will be used in the storage path,
+    #             so make sure it's something sane. Required.
+    #
+    # returns a new Database instance.
+    def initialize(backend, db_name)
+      @backend = backend
+      @name = db_name
+
+      yield self if block_given?
+    end
+
+    # Save a DB instance to disk.
+    #
+    # Returns a Database instance.
+    def save
+      @backend.write_db(@name)
+
+      self
+    end
+
+    # List all available collections in the database.
+    #
+    # returns sorted Array of Strings.
+    def show_collections
+      @backend.list_collections(@name).sort
+    end
+
+    # Create a collection under this database.
+    #
+    # collection  - String name of collection to create. Will also be used as
+    #               its filesystem path, so use something sane. Required.
+    # schema      - Hash schema for this collection. Default: {}.
+    #
+    # returns true on success.
+    def create_collection(collection, schema = {})
+      Collection.create(self, collection)
+    end
+
+    # Drop a collection from this database.
+    #
+    # collection  - String name of collection to drop.
+    #
+    # returns the name of the collection on success.
+    def drop_collection(collection)
+      @backend.delete_collection(@name, collection)
+    end
+
+    # Locate the storage location for the database.
+    #
+    # returns a String path of the database path. Will vary by backend adapter.
+    def path
+      @backend.db_path(@name)
+    end
+
+    private
+
+    # Check to ensure that the database name is valid, from the perspective of
+    # the storage engine.
+    #
+    # returns a Bool.
+    def valid?
+      @backend.db_exist?(@name)
+    end
+  end
+end

data/lib/s3db/file_backend.rb

@@ -0,0 +1,492 @@
+require 'fileutils'
+
+module S3DB
+  class FileBackend < Backend
+    attr_reader :path, :errors
+
+    PATH_BLACKLIST = [
+      'bin',
+      'boot',
+      'cdrom',
+      'data',
+      'dev',
+      'docker',
+      'etc',
+      'home',
+      'lib',
+      'lib64',
+      'media',
+      'mnt',
+      'opt',
+      'proc',
+      'root',
+      'run',
+      'sbin',
+      'srv',
+      'sys',
+      'usr',
+      'var',
+      'badpath', #this is just to be VERY sure we don't trash a real dir in tests
+    ]
+
+    class << self
+      # Create a new base path for a file backend storage location. This method
+      # will create the basepath if it doesn't exist, but also use an existing
+      # path if it does exest.
+      #
+      # path  - String base path. Required.
+      #
+      # returns a new FileBackend.
+      def create(path)
+        be = new(path)
+        be.save
+
+        be
+      end
+
+      # Create a new base path for a file backend storage location. This method
+      # will throw an error if the path already exists. This is safer.
+      #
+      # path  - String base path. Required.
+      #
+      # returns a new FileBackend.
+      def create!(path)
+        be = new(path)
+        be.save!
+
+        be
+      end
+
+      # Destroy a base path for data storage. This method will raise an error
+      # if the directory is not empty.
+      #
+      # path  - String base path. Required.
+      #
+      # returns the String path that was removed.
+      def destroy(path)
+        be = new(path).destroy
+
+        be
+      end
+
+      # Destroy a base path, whether or not it's empty. This is dangerous, and
+      # should be used with great care.
+      #
+      # path  - String path to delete. Required.
+      #
+      # returns itself on success, and raises an error on failure.
+      def delete(path)
+        be = new(path)
+
+        if be.valid!
+          FileUtils.rm_rf(path)
+        end
+
+        self
+      end
+    end
+
+    # Create a new FileBackend.
+    #
+    # path  - String path to use as the base storage location.
+    #
+    # returns a new FileBackend.
+    def initialize(path)
+      @errors = []
+
+      @path = path.strip
+    end
+
+    # Check a path to ensure it does not violate basic sanity rules, such as
+    # being a linux system path, or having weird characters in the name.
+    #
+    # path  - String path to check. Required.
+    #
+    # returns true if it checks out, false otherwise. It will raise an error
+    # for dangerous exceptions.
+    def validate_path
+      PATH_BLACKLIST.each do |p|
+        @errors << "`#{p}` is insane to use as a base path!" if @path =~ /#{p}/i
+      end
+
+      if @path !~ /^(\w|\/)+$/
+        @errors << "path does not match /^(\w|\/)+$/"
+      end
+    end
+
+    # Check to see whether the backend is in a valid state.
+    #
+    # returns Bool.
+    def valid?
+      @errors = []
+
+      validate_path
+
+      !@errors.any?
+    end
+
+    # Confirm that the backend is in a consistent state. Raises an error on
+    # failure.
+    #
+    # returns true on success, raises an error on failure.
+    def valid!
+      if !valid?
+        raise ArgumentError, @errors.join(', ')
+      end
+
+      true
+    end
+
+    # Save a FileBackend, which means writing its root path directory to the
+    # filesystem.
+    #
+    # returns itself on success, returns false on failure.
+    def save
+      return false unless valid?
+
+      FileUtils.mkdir_p(@path)
+
+      self
+    end
+
+    # Save a FileBackend, which means writing its root path directory to the
+    # filesystem.
+    #
+    # returns itself on success, raises an error on failure.
+    def save!
+      valid!
+
+      begin
+        Dir.mkdir(@path)
+      rescue Errno::EEXIST
+        raise ArgumentError, 'base path exists!'
+      end
+
+      self
+    end
+
+
+    # Destroy a FileBackend basepath. The directory must be empty (which means
+    # you must destroy all collections/dbs in the basepath first).
+    #
+    # returns itself on success, false on failure.
+    def destroy
+      return false unless valid?
+
+      begin
+        Dir.rmdir(@path)
+      rescue Errno::ENOTEMPTY, Errno::ENOENT
+        return false
+      end
+
+      self
+    end
+
+    # Destroy a FileBackend basepath. The directory must be empty (which means
+    # you must destroy all collections/dbs in the basepath first).
+    #
+    # returns itself on success, raises an error on failure.
+    def destroy!
+      valid!
+
+      begin
+        Dir.rmdir(@path)
+      rescue Errno::ENOENT
+        raise ArgumentError, 'basepath does not exist!'
+      rescue Errno::ENOTEMPTY
+        raise ArgumentError, 'basepath not empty!'
+      end
+
+      self
+    end
+
+    # Build a full path from the base path and database name.
+    #
+    # db_name   - String name of database. Required.
+    #
+    # returns a String path.
+    def db_path(db_name)
+      File.join(@path, db_name)
+    end
+
+    # Build a full path to a collection from the base path, database name and
+    # collection name.
+    #
+    # db_name           - String name of database. Required.
+    # collection_name   - String name of collection. Required.
+    #
+    # returns a String path.
+    def collection_path(db_name, collection_name)
+      File.join(@path, db_name, collection_name)
+    end
+
+    # Build a full path to a scema from the base path, database name and
+    # collection name.
+    #
+    # db_name           - String name of database. Required.
+    # collection_name   - String name of collection. Required.
+    #
+    # returns a String path.
+    def schema_path(db_name, collection_name)
+      File.join(@path, db_name, collection_name, 'schema.json')
+    end
+
+    # Build a full path to the data dir from the base path, database name and
+    # collection name.
+    #
+    # db_name           - String name of database. Required.
+    # collection_name   - String name of collection. Required.
+    #
+    # returns a String path.
+    def data_path(db_name, collection_name)
+      File.join(@path, db_name, collection_name, 'data')
+    end
+
+    # Build a full path to a record from the base path, database name,
+    # collection name, and filename.
+    #
+    # db_name           - String name of database. Required.
+    # collection_name   - String name of collection. Required.
+    #
+    # returns a String path.
+    def record_path(db_name, collection_name, filename)
+      File.join(@path, db_name, collection_name, 'data', filename)
+    end
+
+    # Write a directory to disk for the name of the database. Will fail if the
+    # database already exists.
+    #
+    # db_name   - String name of database. Required.
+    #
+    # returns db_name on success; raises an error on failure.
+    def write_db(db_name)
+      FileUtils.mkdir_p(db_path(db_name))
+
+      db_name
+    end
+
+    # Write a directory to disk for the name of the collection. Will ignore the
+    # write if the directory exists.
+    #
+    # db_name           - String name of database. Required.
+    # collection_name   - String name of collection. Required.
+    #
+    # returns collection_name on success; raises an error on failure.
+    def write_collection(db_name, collection_name)
+      dir = collection_path(db_name, collection_name)
+
+      unless Dir.exist?(dir)
+        Dir.mkdir(dir)
+      end
+
+      dir = data_path(db_name, collection_name)
+
+      unless Dir.exist?(dir)
+        Dir.mkdir(dir)
+      end
+
+      collection_name
+    end
+
+    # Write a file to disk for the schema for a database/collection.
+    #
+    # db_name           - String name of database. Required.
+    # collection_name   - String name of collection. Required.
+    # schema            - String schema contents. Required.
+    #
+    # returns the schema on success; raises an error on failure.
+    def write_schema(db_name, collection_name, schema)
+      File.open(schema_path(db_name, collection_name), 'w') do |f|
+        f.puts schema
+      end
+
+      schema
+    end
+
+    # Write a record to a database/collection. The record can be in any format.
+    # No parsing of the file is performed. Data must be sent as a string.
+    #
+    # db_name           - String name of database. Required.
+    # collection_name   - String name of collection. Required.
+    # filename          - String name of file to write, w/extension. Required.
+    # data              - String data to write to the file. Required.
+    #
+    # returns the data written.
+    def write_record(db_name, coll_name, filename, data)
+      raise ArgumentError, 'data must be a string!' unless data.is_a?(String)
+
+      File.open(record_path(db_name, coll_name, filename), 'w') do |f|
+        f.puts data
+      end
+
+      data
+    end
+
+    # List all available collections in a database.
+    #
+    # db_name   - String name of database to look in. Required.
+    #
+    # returns an Array of String collection names.
+    def list_collections(db_name)
+      Dir.entries(db_path(db_name)).select do |dir|
+        !File.directory?(dir)
+      end
+    end
+
+    # List all available records for a database/collection.
+    #
+    # db_name           - String name of database to look in. Required.
+    # collection_name   - String name of collection to look in. Required.
+    #
+    # returns an Array of String record file names.
+    def list_records(db_name, coll_name)
+      output = []
+
+      Dir.open(data_path(db_name, coll_name)) do |dir|
+        dir.each do |file|
+          output << file unless File.directory?(file)
+        end
+      end
+
+      output
+    end
+
+    # Read the contents of the schema file.
+    #
+    # db_name           - String name of database to look in. Required.
+    # collection_name   - String name of collection to look in. Required.
+    #
+    # returns the String contents of the schema file. Raises an error if the
+    # file is missing.
+    def read_schema(db_name, collection_name)
+      file = schema_path(db_name, collection_name)
+
+      begin
+        File.read(file)
+      rescue Errno::ENOENT
+        raise ArgumentError, 'schema does not exist!'
+      end
+    end
+
+    # Read the contents of a record in a database/collection
+    #
+    # db_name           - String name of database to look in. Required.
+    # collection_name   - String name of collection to look in. Required.
+    # filename          - String name of the file to read w/extension. Required.
+    #
+    # returns the String contents of the record file. Raises an error if the
+    # file is missing.
+    def read_record(db_name, coll_name, filename)
+      file = record_path(db_name, coll_name, filename)
+
+      begin
+        File.read(file)
+      rescue Errno::ENOENT
+        raise ArgumentError, 'record does not exist!'
+      end
+    end
+
+    # Delete a database directory from disk. Will only succed if the database is
+    # empty.
+    #
+    # db_name           - String name of database to remove. Required.
+    #
+    # returns an Array of the databases deleted, or empty if the database did
+    # not exist.
+    def delete_db(db_name)
+      path = db_path(db_name)
+
+      if Dir.exist?(path)
+        begin
+          Dir.rmdir(path)
+        rescue Errno::ENOTEMPTY
+          raise ArgumentError, 'database is not empty!'
+        end
+
+        return [db_name]
+      end
+
+      []
+    end
+
+    # Delete a collection directory from disk. Will only succed if the
+    # collection is empty.
+    #
+    # db_name           - String name of database to remove. Required.
+    # collection_name   - String name of collection to remove. Required.
+    #
+    # returns an Array of the databases deleted, or empty if the database did
+    # not exist.
+    def delete_collection(db_name, collection_name)
+      path = collection_path(db_name, collection_name)
+
+      if File.exist?(schema_path(db_name, collection_name))
+        File.delete(schema_path(db_name, collection_name))
+      end
+
+      if Dir.exist?(data_path(db_name, collection_name))
+        begin
+          Dir.rmdir(data_path(db_name, collection_name))
+        rescue Errno::ENOTEMPTY
+          raise ArgumentError, 'collection/data is not empty!'
+        end
+      end
+
+      if Dir.exist?(path)
+        begin
+          Dir.rmdir(path)
+        rescue Errno::ENOTEMPTY
+          raise ArgumentError, 'collection is not empty!'
+        end
+
+        return [collection_name]
+      end
+
+      []
+    end
+
+    # Delete a collection directory from disk. Will only succed if the
+    # collection is empty.
+    #
+    # db_name           - String name of database to remove. Required.
+    # collection_name   - String name of collection to remove. Required.
+    #
+    # returns an Array of the databases deleted, or empty if the database did
+    # not exist.
+    def delete_record(db_name, collection_name, filename)
+      path = record_path(db_name, collection_name, filename)
+
+      begin
+        File.delete(path)
+      rescue Errno::ENOENT
+        return ''
+      end
+
+      filename
+    end
+
+    # Delete a collection directory from disk. Will only succed if the
+    # collection is empty.
+    #
+    # db_name           - String name of database to remove. Required.
+    # collection_name   - String name of collection to remove. Required.
+    #
+    # returns an Array of the databases deleted, or empty if the database did
+    # not exist.
+    def delete_record!(db_name, collection_name, filename)
+      path = record_path(db_name, collection_name, filename)
+
+      begin
+        File.delete(path)
+      rescue Errno::ENOENT
+        raise ArgumentError, 'record does not exist!'
+      end
+
+      filename
+    end
+
+    def db_exist?(db_name)
+      Dir.exist?(db_path(db_name))
+    end
+  end
+end