blackhole

README

Black Hole DB (WIP)

BlackHoleDB (or only HoleDB) is a conceptual Key-Value distributed Database. HoleDB uses IPFS as decentralized filesystem, and BadgerDB as store for local key value pairs.

Warning: BlackHole is work in progress, please don't use it in production.

How it Works

BlackHoleDB creates an encrypted file into IPFS filesystem and this return an Qm name (the decentralized path), this Qm path is saved into BadgerDB instance as value where the key is the initial key choose. When you want get your value from the distributed web BlackHoleDB get the Qm linked your key (from BadgerDB) and with this Qm path HoleDB gets the encrypted file from IPFS and finally it decrypted it.

Example code:

options := blackhole.DefaultOptions
db, err := blackhole.Open(options)
if err != nil {
	panic(err)
}

key := "answer"

err = db.Set(key, []byte("Hello World, from BlackHoleDB"))
if err != nil {
	panic(err)
}

data, err := db.Get(key)
if err != nil {
	panic(err)
}

fmt.Println("Answer: ", string(data))
// Answer: Hello World, from BlackHoleDB

About Options Configuration

You can configure the params of your blackhole instance, you can see the struct related above.

type Options struct {
	PrivateKey         []byte // Your encoding key
	EndPointConnection string // Your IPFS Node endpoint
	PrincipalNode      string // Useless now (WIP)

	LocalDBDir      string // Your Local Badger DB
	LocalDBValueDir string // Your Local Badger DB
}

The default configuration is:

var DefaultOptions *Options = &Options{
	LocalDBDir:         "/tmp/badger",
	LocalDBValueDir:    "/tmp/badger",
	EndPointConnection: "localhost:5001",
}
// Note: You need to define your privateKey like this:
// opts.PrivateKey, _ = hex.DecodeString("44667768254d593b7ea48c3327c18a651f6031554ca4f5e3e641f6ff1ea72e98")

Basic Usage Example

package main

import (
	"fmt"
	"github.com/bregydoc/blackholeDB"
)

func main() {
	db, err := blackhole.Open(blackhole.DefaultOptions)
	if err != nil {
		panic(err)
	}

	defer db.Close()

	err = db.Set("answer", []byte("42"))
	if err != nil {
		panic(err)
	}

	answer, err := db.Get("answer")
	if err != nil {
		panic(err)
	}

	fmt.Println("The answer of the life is: ", string(answer))
	// The answer of the life is:  42
}

TODO

• Improve the security
• Make Blackhole a metaDB. Save all param configurations on Distributed web (IPFS)
• Use MsgPack to serialize the data
• Create an ORM layer to save complex structs

Contributing to BlackHoleDB

BlackHoleDB is an open source project and contributors are welcome!

Documentation

Index

• Constants
• Variables
• func UnixTimePrefixedRandomNonce(size int) []byte
• func ValidateKey(k []byte) error
• type DB
  • func Open(options *Options) (*DB, error)
  • func (db *DB) Close()
  • func (db *DB) Get(key string) ([]byte, error)
  • func (db *DB) GetQmFromKey(key string) (string, error)
  • func (db *DB) Set(key string, value []byte) error
  • func (db *DB) Update(key string, value []byte) error
• type MetaDB
• type Options

Constants

const (
	// RequiredKeyLength determinate the exact length of the encrypt key
	RequiredKeyLength = 32
)

Variables

var DefaultOptions = &Options{
	LocalDBDir:         "/tmp/badger",
	EndPointConnection: "localhost:5001",
}

DefaultOptions is used with any options passed, this config saves your db file into your temporal computer files (UNIX) TODO: Improve to another SO

Functions

func UnixTimePrefixedRandomNonce

func UnixTimePrefixedRandomNonce(size int) []byte

UnixTimePrefixedRandomNonce takes an int for the nonce size and returns a byte slice of length size. A byte slice is created for the nonce and filled with random data from `crypto/rand`, then the first 4 bytes of the nonce are overwritten with LittleEndian encoding of `time.Now().Unix()` The purpose of this function is to avoid an unlikely collision in randomly generating nonces by prefixing the nonce with time series data.

func ValidateKey

func ValidateKey(k []byte) error

ValidateKey takes a byte slice and checks that minimum requirements are met for the key. It returns an error if the requirements are not met.

Types

type DB

type DB struct {
	// contains filtered or unexported fields
}

DB represents a blackhole db instance, this struct is the real db when it's sync with the ipfs files

func Open

func Open(options *Options) (*DB, error)

Open opens a new instance of blackholedb

func (*DB) Close

func (db *DB) Close()

Close ... TODO

func (*DB) Get

func (db *DB) Get(key string) ([]byte, error)

Get performs a get action of your Blachole db, it works in two stages (like set function), firs read the relation between your key and a one cid, second, collect this cid from ipfs and finally tries to decrypt and return the value of your key

func (*DB) GetQmFromKey

func (db *DB) GetQmFromKey(key string) (string, error)

GetQmFromKey returns your cid related to your key, if exist, of course

func (*DB) Set

func (db *DB) Set(key string, value []byte) error

Set acts in two stages, first encode your <value> and put into distributed IPFS. second, save (locally) a relation between your <key> and the cid generated from your save performed by ipfs

func (*DB) Update

func (db *DB) Update(key string, value []byte) error

Update takes your value, encode and save the relation, it is exactly equal to set action

type MetaDB

type MetaDB struct {
	// contains filtered or unexported fields
}

MetaDB is a db by reference, a way you can to create a very distrubuted DB

type Options

type Options struct {
	PrivateKey         []byte
	EndPointConnection string
	PrincipalNode      string
	LocalDBDir         string
}

Options is the options configuration of blackholole DB TODO: Define better options and a new paradigm to set it