-
Notifications
You must be signed in to change notification settings - Fork 113
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add a Reva SDK #1280
Merged
Merged
Add a Reva SDK #1280
Changes from 6 commits
Commits
Show all changes
12 commits
Select commit
Hold shift + click to select a range
3c9af75
Integrate libreva as pkg/sdk
Daniel-WWU-IT 8ae48a9
Reuse more existing Reva code
Daniel-WWU-IT b87e6c8
Reuse more existing Reva code
Daniel-WWU-IT 3af9eaa
Add SDK example
Daniel-WWU-IT 36a4ea4
Add SDK documentation
Daniel-WWU-IT 608ad3b
Add changelog
Daniel-WWU-IT 626bbe4
Hound fixes
Daniel-WWU-IT 167cff1
Hound fixes
Daniel-WWU-IT 2c1ecce
Tidy up go.mod/.sum
Daniel-WWU-IT 5e4131d
Correct license headers
Daniel-WWU-IT 3c87a3b
Correct license headers
Daniel-WWU-IT b3d21e3
Lint fixes
Daniel-WWU-IT File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,5 @@ | ||
| Enhancement: Add a Reva SDK | ||
|
|
||
| A Reva SDK has been added to make working with a remote Reva instance much easier by offering a high-level API that hides all the underlying details of the CS3API. | ||
|
|
||
| https://github.com/cs3org/reva/pull/xxx |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,70 @@ | ||
| --- | ||
| title: "Reva SDK" | ||
| linkTitle: "Reva SDK" | ||
| weight: 5 | ||
| description: > | ||
| Use the Reva SDK to easily access and work with a remote Reva instance. | ||
| --- | ||
| The Reva SDK (located under `/pkg/sdk/`) is a simple software development kit to work with Reva through the [CS3API](https://github.com/cs3org/go-cs3apis). It's goal is to make working with Reva as easy as possible by providing a high-level API which hides all the details of the underlying CS3API. | ||
|
|
||
| ## Design | ||
| The main design goal of the SDK is _simplicity_. This means that the code is extremely easy to use instead of being particularly fancy or feature-rich. | ||
|
|
||
| There are two central kinds of objects you'll be using: a _session_ and various _actions_. The session represents the connection to the Reva server through its gRPC gateway client; the actions are then used to perform operations like up- and downloading or enumerating all files located at a specific remote path. | ||
|
|
||
| ## Using the SDK | ||
| ### 1. Session creation | ||
| The first step when using the SDK is to create a session and establish a connection to Reva (which actually results in a token-creation and not a permanent connection, but this should not bother you in any way): | ||
|
|
||
| ``` | ||
| session := sdk.MustNewSession() // Panics if this fails (should usually not happen) | ||
| session.Initiate("reva.host.com:443", false) | ||
| session.BasicLogin("my-login", "my-pass") | ||
| ``` | ||
|
|
||
| Note that error checking is omitted here for brevity, but nearly all methods in the SDK return an error which should be checked upon. | ||
|
|
||
| If the session has been created successfully - which can also be verified by calling `session.IsValid()` -, you can use one of the various actions to perform the actual operations. | ||
|
|
||
| ### 2. Performing operations | ||
| An overview of all currently supported operations can be found below; here is an example of how to upload a file using the `UploadAction`: | ||
|
|
||
| ``` | ||
| act := action.MustNewUploadAction(session) | ||
| info, err := act.UploadBytes([]byte("HELLO WORLD!\n"), "/home/mytest/hello.txt") | ||
| // Check error... | ||
| fmt.Printf("Uploaded file: %s [%db] -- %s", info.Path, info.Size, info.Type) | ||
| ``` | ||
|
|
||
| As you can see, you first need to create an instance of the desired action by either calling its corresponding `New...Action` or `MustNew...Action` function; these creators always require you to pass the previously created session object. The actual operations are then performed by using the appropriate methods offered by the action object. | ||
|
|
||
| A more extensive example of how to use the SDK can also be found in `/examples/sdk/sdk.go`. | ||
|
|
||
| ## Supported operations | ||
| An action object often bundles various operations; the `FileOperationsAction`, for example, allows you to create directories, check if a file exists or remove an entire path. Below is an alphabetically sorted table of the available actions and their supported operations: | ||
|
|
||
| | Action | Operation | Description | | ||
| | --- | --- | --- | | ||
| | `DownloadAction` | `Download` | Downloads a specific resource identified by a `ResourceInfo` object | | ||
| | | `DownloadFile` | Downloads a specific file | | ||
| | `EnumFilesAction`<sup>1</sup> | `ListAll` | Lists all files and directories in a given path | | ||
| | | `ListAllWithFilter` | Lists all files and directories in a given path that fulfill a given predicate | | ||
| | | `ListDirs` | Lists all directories in a given path | | ||
| | | `ListFiles` | Lists all files in a given path | | ||
| | `FileOperationsAction` | `DirExists` | Checks whether the specified directory exists | | ||
| | | `FileExists` | Checks whether the specified file exists | | ||
| | | `MakePath` | Creates the entire directory tree specified by a path | | ||
| | | `Move` | Moves a specified resource to a new target | | ||
| | | `MoveTo` | Moves a specified resource to a new directory, creating it if necessary | | ||
| | | `Remove` | Deletes the specified resource | | ||
| | | `ResourceExists` | Checks whether the specified resource exists | | ||
| | | `Stat` | Queries information of a resource | | ||
| | `UploadAction`<sup>2</sup> | `Upload` | Uploads data from a reader to a target file | | ||
| | | `UploadBytes` | Uploads byte data to a target file | | ||
| | | `UploadFile` | Uploads a file to a target file | | ||
| | | `UploadFileTo` | Uploads a file to a target directory | | ||
|
|
||
| * <sup>1</sup> All enumeration operations support recursion. | ||
| * <sup>2</sup> The `UploadAction` creates the target directory automatically if necessary. | ||
|
|
||
| _Note that not all features of the CS3API are currently implemented._ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,145 @@ | ||
| /* | ||
| * MIT License | ||
| * | ||
| * Copyright (c) 2020 Daniel Mueller | ||
| * | ||
| * 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. | ||
| */ | ||
|
|
||
| package main | ||
|
|
||
| import ( | ||
| "fmt" | ||
| "log" | ||
|
|
||
| "github.com/cs3org/reva/pkg/sdk" | ||
| "github.com/cs3org/reva/pkg/sdk/action" | ||
| ) | ||
|
|
||
| func runActions(session *sdk.Session) { | ||
| // Try creating a directory | ||
| { | ||
| act := action.MustNewFileOperationsAction(session) | ||
| if err := act.MakePath("/home/subdir/subsub"); err == nil { | ||
| log.Println("Created path /home/subdir/subsub") | ||
| } else { | ||
| log.Println("Could not create path /home/subdir/subsub") | ||
| } | ||
| fmt.Println() | ||
| } | ||
|
|
||
| // Try deleting a directory | ||
| { | ||
| act := action.MustNewFileOperationsAction(session) | ||
| if err := act.Remove("/home/subdir/subsub"); err == nil { | ||
| log.Println("Removed path /home/subdir/subsub") | ||
| } else { | ||
| log.Println("Could not remove path /home/subdir/subsub") | ||
| } | ||
| fmt.Println() | ||
| } | ||
|
|
||
| // Try uploading | ||
| { | ||
| act := action.MustNewUploadAction(session) | ||
| act.EnableTUS = true | ||
| if info, err := act.UploadBytes([]byte("HELLO WORLD!\n"), "/home/subdir/tests.txt"); err == nil { | ||
| log.Printf("Uploaded file: %s [%db] -- %s", info.Path, info.Size, info.Type) | ||
| } else { | ||
| log.Printf("Can't upload file: %v", err) | ||
| } | ||
| fmt.Println() | ||
| } | ||
|
|
||
| // Try moving | ||
| { | ||
| act := action.MustNewFileOperationsAction(session) | ||
| if err := act.MoveTo("/home/subdir/tests.txt", "/home/sub2"); err == nil { | ||
| log.Println("Moved tests.txt around") | ||
| } else { | ||
| log.Println("Could not move tests.txt around") | ||
| } | ||
| fmt.Println() | ||
| } | ||
|
|
||
| // Try listing and downloading | ||
| { | ||
| act := action.MustNewEnumFilesAction(session) | ||
| if files, err := act.ListFiles("/home", true); err == nil { | ||
| for _, info := range files { | ||
| log.Printf("%s [%db] -- %s", info.Path, info.Size, info.Type) | ||
|
|
||
| // Download the file | ||
| actDl := action.MustNewDownloadAction(session) | ||
| if data, err := actDl.Download(info); err == nil { | ||
| log.Printf("Downloaded %d bytes for '%v'", len(data), info.Path) | ||
| } else { | ||
| log.Printf("Unable to download data for '%v': %v", info.Path, err) | ||
| } | ||
|
|
||
| log.Println("---") | ||
| } | ||
| } else { | ||
| log.Printf("Can't list files: %v", err) | ||
| } | ||
| fmt.Println() | ||
| } | ||
|
|
||
| // Try accessing some files and directories | ||
| { | ||
| act := action.MustNewFileOperationsAction(session) | ||
| if act.FileExists("/home/blargh.txt") { | ||
| log.Println("File '/home/blargh.txt' found") | ||
| } else { | ||
| log.Println("File '/home/blargh.txt' NOT found") | ||
| } | ||
|
|
||
| if act.DirExists("/home") { | ||
| log.Println("Directory '/home' found") | ||
| } else { | ||
| log.Println("Directory '/home' NOT found") | ||
| } | ||
| fmt.Println() | ||
| } | ||
| } | ||
|
|
||
| func main() { | ||
| session := sdk.MustNewSession() | ||
| if err := session.Initiate("sciencemesh-test.uni-muenster.de:9600", false); err != nil { | ||
| log.Fatalf("Can't initiate Reva session: %v", err) | ||
| } | ||
|
|
||
| if methods, err := session.GetLoginMethods(); err == nil { | ||
| fmt.Println("Supported login methods:") | ||
| for _, m := range methods { | ||
| fmt.Printf("* %v\n", m) | ||
| } | ||
| fmt.Println() | ||
| } else { | ||
| log.Fatalf("Can't list login methods: %v", err) | ||
| } | ||
|
|
||
| if err := session.BasicLogin("daniel", "danielpass"); err == nil { | ||
| log.Printf("Successfully logged into Reva (token=%v)", session.Token()) | ||
| fmt.Println() | ||
| runActions(session) | ||
| } else { | ||
| log.Fatalf("Can't log in to Reva: %v", err) | ||
| } | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,44 @@ | ||
| /* | ||
| * MIT License | ||
| * | ||
| * Copyright (c) 2020 Daniel Mueller | ||
| * | ||
| * 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. | ||
| */ | ||
|
|
||
| package action | ||
|
|
||
| import ( | ||
| "fmt" | ||
|
|
||
| "github.com/cs3org/reva/pkg/sdk" | ||
| ) | ||
|
|
||
| type action struct { | ||
| session *sdk.Session | ||
| } | ||
|
|
||
| func (act *action) initAction(session *sdk.Session) error { | ||
| if !session.IsValid() { | ||
| return fmt.Errorf("no valid session provided") | ||
| } | ||
| act.session = session | ||
|
|
||
| return nil | ||
| } |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
run
go mod tidyto cleanup these deps