chore: Create workspace for developing uplink crate

ifraixedes · ifraixedes · commit ed7579a5f8ca · 2021-11-15T19:51:56.000+01:00
Create a Cargo workspace for developing the `uplink` crate in this same
repository.

The `uplink` crate is the idiomatic and safe Rust binding for Storj
uplink wrapping the existing `uplink-sys` crate.

The commit

* moves some files or content from the root of the repository to the
  "uplink-sys" directory, which is where the crate with the same name
  is implemented.
* initializes the `uplink` crate under a subdirectory with the same
  name, for implementing it.
* creates a workspace including these two creates as members.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+/target
+Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -0,0 +1,2 @@
+[workspace]
+members = ["uplink", "uplink-sys"]
diff --git a/README.md b/README.md
@@ -1,108 +1,16 @@
 # uplink-rust
 
-[![Actions Status](https://github.com/storj-thirdparty/uplink-rust/workflows/uplink-sys/badge.svg)](https://github.com/storj-thirdparty/uplink-rust/actions)
-[![Crates.io](https://img.shields.io/crates/v/uplink-sys)](https://crates.io/crates/uplink-sys)
+Storj Uplink Rust bindings for the Rust programming language.
 
+__NOTE__ [`uplink` crate](tree/main/uplink) is __work in progress__.
 
-Originally developed and tested using:
-`Ubuntu 20.04`
-`Rust 1.51.0`
-`Go 1.16.2`
-`uplink-c v1.2.3`
+## Repository layout
 
-Should work with other versions but has not been extensively tested.
+Following the conventions used for creating Rust bindings through [bindgen][bindgen], this repository contains two crates:
 
-See [uplink-sys README](https://github.com/storj-thirdparty/uplink-rust/tree/main/uplink-sys) for build instructions.
+* The [`uplink-sys`](tree/main/uplink-sys) which is the unsafe Rust bindings auto-generated by [bindgen][bindgen].
+* The [`uplink`](tree/main/uplink) which is the safe and idiomatic Rust binding build on top of the `uplink-sys`.
 
-# uplink-sys
-The [uplink-sys](https://github.com/storj-thirdparty/uplink-rust/tree/main/uplink-sys) crate provides Rust bindings to [uplink-c](https://github.com/storj/uplink-c).
+[bindgen]: https://github.com/rust-lang/rust-bindgen/
 
-This crate provides direct unsafe bindings to the C functions provided by uplink-c.
-
-## Usage
-See [uplink-sys/examples](https://github.com/storj-thirdparty/uplink-rust/tree/main/uplink-sys/examples) for example projects using the uplink-sys crate.  Below is an example showing how to list buckets using the crate's unsafe C bindings.
-```rust
-// Access parameters
-let satellite_address = CString::new("SATELLITE ADDRESS HERE").expect("CString::new failed");
-let api_key = CString::new("API KEY HERE").expect("CString::new failed");
-let passphrase = CString::new("PASSPHRASE HERE").expect("CString::new failed");
-
-unsafe {
-    // Request access
-    let access_result = uplink_sys::uplink_request_access_with_passphrase(
-        satellite_address.as_ptr() as *mut uplink_sys::uplink_const_char,
-        api_key.as_ptr() as *mut uplink_sys::uplink_const_char,
-        passphrase.as_ptr() as *mut uplink_sys::uplink_const_char,
-    );
-    if access_result.error != std::ptr::null_mut() {
-        println!("Error requesting access: {:?}", *(access_result.error));
-    }
-
-    // Access project
-    let project_result = uplink_sys::uplink_open_project(access_result.access);
-    if project_result.error != std::ptr::null_mut() {
-        println!("Error accessing project: {:?}", *(project_result.error));
-    }
-
-    // Create empty string for bucket option struct
-    let bucket_options_str = CString::new("").expect("CString::new failed");
-    let mut bucket_options = uplink_sys::UplinkListBucketsOptions {
-        cursor: bucket_options_str.as_ptr(),
-    };
-
-    // Request bucket iterator
-    let p_bucket_iterator =
-        uplink_sys::uplink_list_buckets(project_result.project, &mut bucket_options);
-
-    // Check for valid bucket iterator
-    let p_bucket_iterator_err = uplink_sys::uplink_bucket_iterator_err(p_bucket_iterator);
-    if p_bucket_iterator_err == std::ptr::null_mut() {
-        println!("Valid bucket iterator.");
-    } else {
-        println!(
-            "Invalid bucket iterator. Error: {:?}.",
-            *p_bucket_iterator_err
-        );
-    }
-
-    // Iterate through all buckets
-    let mut bucket_count = 0;
-    while uplink_sys::uplink_bucket_iterator_next(p_bucket_iterator) {
-        bucket_count += 1;
-
-        let p_bucket_result = uplink_sys::uplink_bucket_iterator_item(p_bucket_iterator);
-        let bucket_name = CStr::from_ptr((*p_bucket_result).name)
-            .to_str()
-            .expect("Invalid bucket name C string.");
-        let created = datetime_string_from_unix_time((*p_bucket_result).created);
-
-        println!(
-            "Bucket {} => name: {}, created: {}",
-            bucket_count, bucket_name, created
-        );
-
-        // Free memory
-        uplink_sys::uplink_free_bucket(p_bucket_result);
-    }
-
-    // Free memory
-    uplink_sys::uplink_free_access_result(access_result);
-    uplink_sys::uplink_free_project_result(project_result);
-    uplink_sys::uplink_free_bucket_iterator(p_bucket_iterator);
-    uplink_sys::uplink_free_error(p_bucket_iterator_err);
-}
-```
-
-# uplink
-In the future a safe crate may be added to this repo to wrap the unsafe pointer/memory handling of the sys crate.
-
-# Testing
-The project has been tested on the following operating systems:
-```
-* ubuntu
-	* Version: 20.04.2 LTS
-	* Processor: Intel® Core™ i7-10510U CPU @ 1.80GHz × 8
-* macOS
-	* Version: 10.15.7
-	* Processor: 2.6 GHz 6-Core Intel Corei7
-```
+Each crate matches a root's child directory with the same name and each directory has its own README which provides more detailed information and its current status.
diff --git a/uplink-sys/Dockerfile b/uplink-sys/Dockerfile
diff --git a/uplink-sys/LICENSE b/uplink-sys/LICENSE
diff --git a/uplink-sys/README.md b/uplink-sys/README.md
@@ -1,40 +1,50 @@
 # uplink-sys
 
 [![Actions Status](https://github.com/storj-thirdparty/uplink-rust/workflows/uplink-sys/badge.svg)](https://github.com/storj-thirdparty/uplink-rust/actions)
+[![Crates.io](https://img.shields.io/crates/v/uplink-sys)](https://crates.io/crates/uplink-sys)
 
-This crate provides Rust bindings to [uplink-c](https://github.com/storj/uplink-c/), the C interface for the storj uplink API library.
-
-[TODO]() is the safe wrapper crate for this library.
+This crate provides auto-generated unsafe Rust bindings, through [bindgen](https://github.com/rust-lang/rust-bindgen/), to C functions provided by [uplink-c](https://github.com/storj/uplink-c/), the C interface for the Storj uplink API library.
 
 # Building (from repo)
 ## Linux
- - Install [Go](https://golang.org/doc/install)  
- - Install [Rust](https://www.rust-lang.org/tools/install)  
- - Install GCC and make  
+ - Install [Go](https://golang.org/doc/install)
+ - Install [Rust](https://www.rust-lang.org/tools/install)
+ - Install GCC and make
   `sudo apt install build-essential`
- - Install libclang (required by bindgen for generating platform specific c bindings)  
+ - Install libclang (required by bindgen for generating platform specific c bindings)
   `sudo apt install libclang-dev`
- - Checkout this repo  
- - Build crate  
+ - Checkout this repo
+ - Build crate
   `make build` (from `uplink-sys` directory)
-  
+
 ## macOS
- - Install [Go](https://golang.org/doc/install)  
- - Install [Rust](https://www.rust-lang.org/tools/install)  
- - Checkout this repo  
- - Build crate  
+ - Install [Go](https://golang.org/doc/install)
+ - Install [Rust](https://www.rust-lang.org/tools/install)
+ - Checkout this repo
+ - Build crate
   `make build` (from `uplink-sys` directory)
-  
+
 # Building (from crates.io) (TODO ONCE CRATE IS PUBLISHED)
-## Linux 
- - Install [Go](https://golang.org/doc/install)  
- - Install libclang (required by bindgen for generating platform specific c bindings)  
+## Linux
+ - Install [Go](https://golang.org/doc/install)
+ - Install libclang (required by bindgen for generating platform specific c bindings)
  - Add uplink-sys to Cargo.toml
 
 # Tests
+
+__NOTE__ the project has been tested on the following operating systems:
+```
+* ubuntu
+	* Version: 20.04.2 LTS
+	* Processor: Intel® Core™ i7-10510U CPU @ 1.80GHz × 8
+* macOS
+	* Version: 10.15.7
+	* Processor: 2.6 GHz 6-Core Intel Corei7
+```
+
 ## Setup
-To allow the integrations tests access to the test project, create a file in this directory with the satellite address and api key for running tests.  
-Do not commit this file to the repo.  
+To allow the integrations tests access to the test project, create a file in this directory with the satellite address and api key for running tests.
+Do not commit this file to the repo.
 `test_secrets.txt`:
 ```
 <satellite_addresss>
@@ -43,6 +53,79 @@ Do not commit this file to the repo.
 ## Run
 `make test`
 
-# Examples
-For a usage example see `examples/list_buckets`.  This contains a rust project that lists buckets for a project, you just need to add access parameters.
-[TODO]() is a safe library crate wrapping this sys crate so more examples using the wrapper library can be found there.
+# Usage
+See the [examples directory](https://github.com/storj-thirdparty/uplink-rust/tree/main/uplink-sys/examples) to see how use the `uplink-sys` crate.
+
+Below is an example showing how to list buckets using the crate's unsafe C bindings.
+
+```rust
+// Access parameters
+let satellite_address = CString::new("SATELLITE ADDRESS HERE").expect("CString::new failed");
+let api_key = CString::new("API KEY HERE").expect("CString::new failed");
+let passphrase = CString::new("PASSPHRASE HERE").expect("CString::new failed");
+
+unsafe {
+    // Request access
+    let access_result = uplink_sys::uplink_request_access_with_passphrase(
+        satellite_address.as_ptr() as *mut uplink_sys::uplink_const_char,
+        api_key.as_ptr() as *mut uplink_sys::uplink_const_char,
+        passphrase.as_ptr() as *mut uplink_sys::uplink_const_char,
+    );
+    if access_result.error != std::ptr::null_mut() {
+        println!("Error requesting access: {:?}", *(access_result.error));
+    }
+
+    // Access project
+    let project_result = uplink_sys::uplink_open_project(access_result.access);
+    if project_result.error != std::ptr::null_mut() {
+        println!("Error accessing project: {:?}", *(project_result.error));
+    }
+
+    // Create empty string for bucket option struct
+    let bucket_options_str = CString::new("").expect("CString::new failed");
+    let mut bucket_options = uplink_sys::UplinkListBucketsOptions {
+        cursor: bucket_options_str.as_ptr(),
+    };
+
+    // Request bucket iterator
+    let p_bucket_iterator =
+        uplink_sys::uplink_list_buckets(project_result.project, &mut bucket_options);
+
+    // Check for valid bucket iterator
+    let p_bucket_iterator_err = uplink_sys::uplink_bucket_iterator_err(p_bucket_iterator);
+    if p_bucket_iterator_err == std::ptr::null_mut() {
+        println!("Valid bucket iterator.");
+    } else {
+        println!(
+            "Invalid bucket iterator. Error: {:?}.",
+            *p_bucket_iterator_err
+        );
+    }
+
+    // Iterate through all buckets
+    let mut bucket_count = 0;
+    while uplink_sys::uplink_bucket_iterator_next(p_bucket_iterator) {
+        bucket_count += 1;
+
+        let p_bucket_result = uplink_sys::uplink_bucket_iterator_item(p_bucket_iterator);
+        let bucket_name = CStr::from_ptr((*p_bucket_result).name)
+            .to_str()
+            .expect("Invalid bucket name C string.");
+        let created = datetime_string_from_unix_time((*p_bucket_result).created);
+
+        println!(
+            "Bucket {} => name: {}, created: {}",
+            bucket_count, bucket_name, created
+        );
+
+        // Free memory
+        uplink_sys::uplink_free_bucket(p_bucket_result);
+    }
+
+    // Free memory
+    uplink_sys::uplink_free_access_result(access_result);
+    uplink_sys::uplink_free_project_result(project_result);
+    uplink_sys::uplink_free_bucket_iterator(p_bucket_iterator);
+    uplink_sys::uplink_free_error(p_bucket_iterator_err);
+}
+```
diff --git a/uplink/.gitignore b/uplink/.gitignore
@@ -0,0 +1,2 @@
+/target
+Cargo.lock
diff --git a/uplink/Cargo.toml b/uplink/Cargo.toml
@@ -0,0 +1,14 @@
+[package]
+name = "uplink"
+version = "0.0.1"
+authors = ["Ivan Fraixedes <ivan@fraixed.es>"]
+edition = "2021"
+description = "Idiomatic and safe Rust binding for the Storj Lib Uplink"
+license = "MIT"
+repository = "https://github.com/storj-thirdparty/uplink-rust"
+keywords = ["storj", "storjlabs", "decentralized", "binding", "uplink"]
+categories = ["api-bindings"]
+homepage = "https://storj.io"
+
+
+[dependencies]
diff --git a/uplink/LICENSE b/uplink/LICENSE
@@ -0,0 +1,22 @@
+The MIT License
+
+Copyright (c) 2021 Storj Labs, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+'Software'), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
diff --git a/uplink/src/lib.rs b/uplink/src/lib.rs
@@ -0,0 +1 @@
+// TODO: to be implemented

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+[workspace]`
	`2`	`+members = ["uplink", "uplink-sys"]`