A simple SAFE API wrapper written in Ruby
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
bin
lib
spec
.gitignore
.travis.yml
Gemfile
LICENSE
README.md
Rakefile
ruby-safenet.gemspec

README.md

Ruby-Safenet

A simple SAFE API wrapper written in Ruby.

Currently Outdated: It doesn't work with the new Authenticator paradigm

Installation

  $ gem install ruby-safenet

Usage

require "safenet"

safe = SafeNet::Client.new(permissions: ["SAFE_DRIVE_ACCESS"])
safe.nfs.create_public_directory("/mydir")
safe.nfs.create_file("/mydir/index.html", "Hello world!<br>I'm a webpage :D")
safe.dns.register_service("my-wonderful-app", "www", "/mydir")
safe.nfs.get_file("/mydir/index.html")

# Then, open safe://www.my-wonderful-app/

You can also set a more detailed App info:

safe = SafeNet::Client.new({
  name:      "Ruby Demo App",
  version:   "0.0.1",
  vendor:    "Vendor's Name",
  id:        "thevendor.demo",
})

File Upload / Download:

# upload
safe.nfs.create_file("/mydir/dog.jpg", File.read("/home/daniel/Pictures/dog.jpg"), content_type: "image/jpeg")

# download
File.open("/home/daniel/Pictures/dog-new.jpg", "w") do |file|
  file.write(safe.nfs.get_file("/mydir/dog.jpg")["body"])
end

Directory's file list:

safe.nfs.get_directory("/mydir")["files"].each do |file|
  puts file["name"]
end

Structured Data (SD) - With helpers:

safe = safenet_quick

safe.sd.create('my_sd', 'Hello SD!')
puts safe.sd.read('my_sd') # Hello SD!

safe.sd.update('my_sd', 'Hello SD 2!')
puts safe.sd.read('my_sd') # Hello SD 2!

Immutable Data - With helpers:

# client
safe = safenet_quick

# write / read
name = safe.immutable.create('Hello SD') # name = base64 encoded
puts safe.immutable.read(name)

# write from file
name = safe.immutable.create_from_file("#{Rails.root}/my_file.txt")
safe.immutable.dump(name, "#{Rails.root}/from_safenet.txt")

Structured Data (SD) - With safe primitives:

# client
safe = SafeNet::Client.new(permissions: ["LOW_LEVEL_API"])

# plain (not encrypted)
hnd_cipher = safe.cipher.get_handle

# create
name = SafeNet::s2b('my_sd')
hnd = safe.sd.create_sd(name, 500, hnd_cipher, IO.binread("#{Rails.root}/my_file.txt"))
safe.sd.put(hnd) # saves on the network
safe.sd.drop_handle(hnd) # release handler

# release cipher handler
safe.cipher.drop_handle(hnd_cipher)

# read
name = SafeNet::s2b('my_sd')
hnd_sd_data_id = safe.data_id.get_data_id_sd(name)
hnd_sd = safe.sd.get_handle(hnd_sd_data_id)['handleId']
contents = safe.sd.read_data(hnd_sd)
safe.sd.drop_handle(hnd_sd)
safe.data_id.drop_handle(hnd_sd_data_id)
puts contents # print SD contents on screen

Immutable Data - With safe primitives:

# client
safe = SafeNet::Client.new(permissions: ["LOW_LEVEL_API"])

# plain (not encrypted)
hnd_cipher = safe.cipher.get_handle

# write
hnd_w = safe.immutable.get_writer_handle
safe.immutable.write_data(hnd_w, 'Hello World')
hnd_data_id = safe.immutable.close_writer(hnd_w, hnd_cipher)
name = safe.data_id.serialize(hnd_data_id) # IMMUTABLE NAME
safe.immutable.drop_writer_handle(hnd_w)
safe.data_id.drop_handle(hnd_data_id)
puts "Immutable name:\n  * Binary: #{name}\n  * Hex...: #{name.unpack("H*").first}\n  * Base64: #{Base64.encode64(name)}"

# release cipher handler
safe.cipher.drop_handle(hnd_cipher)

# read
hnd_data_id = safe.data_id.deserialize(name)
hnd_r = safe.immutable.get_reader_handle(hnd_data_id)
contents = safe.immutable.read_data(hnd_r)
safe.immutable.drop_reader_handle(hnd_r)
safe.data_id.drop_handle(hnd_data_id)
puts contents

# read - seek position
chunk_pos = 0
max_chunk_size = 100_000

hnd_data_id = safe.data_id.deserialize(name)
hnd_r = safe.immutable.get_reader_handle(hnd_data_id)
contents = safe.immutable.read_data(hnd_r, "bytes=#{chunk_pos}-#{chunk_pos+max_chunk_size}")
safe.immutable.drop_reader_handle(hnd_r)
safe.data_id.drop_handle(hnd_data_id)
puts contents

Supported methods:

Module Method Arguments Optional Doc
nfs create_public_directory dir_path (string) root_path ("app" or "drive"), meta (string) * Alias to "create_directory"
nfs create_private_directory dir_path (string) root_path ("app" or "drive"), meta (string) * Alias to "create_directory"
nfs create_directory dir_path (string) is_private (bool), root_path ("app" or "drive"), meta (string) https://maidsafe.readme.io/docs/nfs-create-directory
nfs get_directory dir_path (string) root_path ("app" or "drive") https://maidsafe.readme.io/docs/nfs-get-directory
nfs rename_directory dir_path (string), new_name (string) root_path ("app" or "drive") * Alias to update_directory
nfs update_directory dir_path (string) root_path ("app" or "drive"), meta (string), name (string) https://maidsafe.readme.io/docs/nfs-update-directory
nfs delete_directory dir_path (string) root_path ("app" or "drive") https://maidsafe.readme.io/docs/nfs-create-directory
nfs create_file file_path (string), contents (string | binary) root_path ("app" or "drive"), meta (string), content_type (string) https://maidsafe.readme.io/docs/nfsfile
nfs get_file file_path (string) root_path ("app" or "drive"), offset (int), length (int), range (eg. "bytes 0-1000") https://maidsafe.readme.io/docs/nfs-get-file
nfs move_file https://api.safedev.org/nfs/file/move-file.html
nfs rename_file file_path (string), new_name (string) root_path ("app" or "drive"), meta (string) * Alias to "update_file_meta"
nfs update_file_meta file_path (string) root_path ("app" or "drive"), meta (string), name (string) https://maidsafe.readme.io/docs/nfs-update-file-metadata
nfs delete_file file_path (string) root_path ("app" or "drive") https://maidsafe.readme.io/docs/nfs-delete-file
dns create_long_name long_name (string) https://maidsafe.readme.io/docs/dns-create-long-name
dns register_service long_name (string), service_name (string), service_home_dir_path (string) https://maidsafe.readme.io/docs/dns-register-service
dns add_service long_name (string), service_name (string), service_home_dir_path (string) https://maidsafe.readme.io/docs/dns
dns list_long_names root_path ("app" or "drive") https://maidsafe.readme.io/docs/dns-list-long-names
dns list_services long_name (string) https://maidsafe.readme.io/docs/dns-list-services
dns get_home_dir long_name (string), service_name (string) https://maidsafe.readme.io/docs/dns-get-home-dir
dns get_file_unauth long_name (string), service_name (string), file_path (string) https://maidsafe.readme.io/docs/dns-get-file-unauth

TODO

  • Improve test suite;
  • Improve documentation;
  • Use FFI instead of REST;
  • Use the same interface (same method names) as safe_app_nodejs;
  • Each method should have 2 versions: a regular version that fails gracefully on errors, a "!" version that raises an exception on errors;