solid-community-client-simple 0.0.2 → 0.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f3179178af2f1aa377389010b0c70b3f5f3fbb5fd1d3f7e236eb5d1a51c14744
-  data.tar.gz: 6f0d2834a7ba126bca117223ebc6fda28b9ae752bc935cefa7ead948084e50eb
+  metadata.gz: bb57f2c8135d3faa45c2920c23b3524f7e9364bbdc3c16f423cab14fc19caa92
+  data.tar.gz: c4d848a43f8228153cd31af586e12795bf0592a40a9617f51b63e4aede39152f
 SHA512:
-  metadata.gz: f4309001b3d49ebf7dc1124f15e59999160eb060b0af21991777520809918f2010f51d9d68109f19deb6cdaf5d0c54c4e9502fdc723c29c3cfc858b3a49928dd
-  data.tar.gz: 4f675efc01c2a5fb9c832c3053914abed55921c06499073400584856c3b28b83575644e6f480e660375b2ac92e29171d264a0eee39c79382301ecbf4c32f79bc
+  metadata.gz: 8b275de160f100f06f6bbf8b000521aa3ed767a1560498c7089a451ad9809ac8cd5e6eb1b0f15ae597bf16d695df9c070ddbd04a0a6ab322d41528890b3241e5
+  data.tar.gz: fea34b8719aa51866cd156f53444ef2dc32a419ad666ac507696844ec4e3a0cafe6477dd66188bf2948af03353b2241e30858dd599754cf21c8ffcfdca91ac42

data/README.md

@@ -1,4 +1,4 @@
-# SOLID Client for Community Server
+# SOLID Client for the SOLID Community Server
 
 Talk to SOLID Pods
 
@@ -7,4 +7,28 @@ Talk to SOLID Pods
 If you want an idea of what's happening behind the scenes, have a look at this Gist:  
 https://gist.github.com/markwilkinson/c5e819ae08d3753b1ee63edb2a504401
 
-I will get around to documentation as soon as I can.  In the meantime, have a look at demo.rb for simple simple simple examples of how to use this gem.
+
+Note that this was created for a specific project, with a short timeline.  It currently does only the things
+I need it to do!  It is not, in any way a full-featured SOLID POD library!  Having said that, it does get you through all of the stages of login and to the point of having a DPOP proof that allows you to interact in an LDP-style manner with the POD (e.g. creating/updating/deleting Resources and/or Containers)
+
+Future iterations will be much more powerful, as my requirements grow through the life of my project.
+
+Example Interaction
+
+```
+# this assumes you are running the SOLID Community Client docker image exposing port 3000
+# you must have already set-up a login and have a POD on that server to talk to!
+
+require "solid-community-client-simple"
+s = SOLID::CommunityClient.new(server: "http://localhost:3000/", username: "mark.wilkinson@upm.es", password: "markw")
+s.login
+at = s.get_current_access_token(webid: "http://localhost:3000/markw/profile/card#me", name: "codetest")
+dpop = s.prepare_dpop(url: "http://localhost:3000/markw/", method: "get")
+res = s.execute_with_proof(dpop: dpop, data: "", content_type: "text/turtle", current_access_token: at)
+puts res.body
+
+```
+
+Please share bug reports via the Issues, but please also be aware that this is not (yet!) intended for widespread use.  I simply found the documentation for interacting with the Community Server to be... extremely frustrating!  (documentation should not be via software snippets!).  Anyway, to avoid anyone else having to figure out what the javascript in that documentation is doing, I have captured it in this code, and in the Gist linked above.
+
+Enjoy!

data/demo.rb

@@ -1,5 +1,5 @@
- require "./lib/solid.rb"
-#require "solid-community-client-simple"
+# require "./lib/solid.rb"
+require "solid-community-client-simple"
 s = SOLID::CommunityClient.new(server: "http://localhost:3000/", username: "mark.wilkinson@upm.es", password: "markw")
 s.login
 at = s.get_current_access_token(webid: "http://localhost:3000/markw/profile/card#me", name: "codetest")

data/lib/solid.rb

@@ -5,6 +5,15 @@ module SOLID
     attr_accessor :username, :password, :server, :account_meta, :login_meta, :credentials_url, :webid_url, :webids,
                   :css_account_token, :tokenid, :secret, :auth_string, :encoded_auth, :current_access_token
 
+    #
+    # Initialize the SOLID Community Client Object
+    #
+    # @param [String] server The URL of the SOLID Pod you want to interact with
+    # @param [String] username Your SOLID Pod username (defaults to ENV['SOLIDUSER'])
+    # @param [String] password Your SOLID Pod password (default to ENV['SOLIDPASSWORD'])
+    # @param [webid] webid Your WebID that you use for authentication against that POD (default nil)
+    #
+    # @return [SOLID::CommunityClient]
     def initialize(server:, username: ENV['SOLIDUSER'], password: ENV['SOLIDPASSWORD'], webid: nil)
       @username = username
       @password = password
@@ -13,6 +22,17 @@ module SOLID
       @webid = webid
     end
 
+    #
+    # Login to the POD. This creates additional accessors in the SOLID::CommunityClient
+    # Including:  
+    #    #account_meta - this contains the parsed JSON from a GET on the PODs ./accout endpoint
+    #    #login_meta - this contains the parsed JSON from a GET on the PODs login_url (part of the #account_meta)
+    #    #credentials_url - the URL to be used to get credentials for the POD
+    #    #webid_url - the URL to call to get the list of WebIDs that have access to this POD
+    #
+    #
+    # @return [Boolean] Was login successful? (if not, this method will crash, for the moment!  No error tolerance at all!)
+    #
     def login
       account = server + '.account/'
 
@@ -56,6 +76,11 @@ module SOLID
       true
     end
 
+    #
+    # Retrieve the list of WebIDs that have access to this POD
+    #
+    # @return [Array[String]] an array of URL strings that are the webids of all legitimate POD users
+    #
     def get_webids
       resp = RestClient::Request.new({
                                        method: :get,
@@ -71,6 +96,14 @@ module SOLID
       webids
     end
 
+    #
+    # Create the access token for this POD based in your WebID
+    #
+    # @param [String] webid The URL of your WebID
+    # @param [String] name some arbigtrary name to give your token (no sanity checking on the characters right now...)
+    #
+    # @return [String] The access token (this also sets the value of the SOLID::CommunityClient#current_access_token instance method)
+    #
     def create_access_token(webid:, name: 'my-token')
       payload = { "name": name, "webId": webid }.to_json
       warn "", "", credentials_url, css_account_token, payload, "", ""
@@ -116,6 +149,14 @@ module SOLID
       @current_access_token = j['access_token']
     end
 
+    #
+    # Either retrieve or create a valid access token.  This should be used in preference to create_access_token, because it has logic to test the validity of the current token, and renew if it has a remaining lifespan of less than 30 seconds.
+    #
+    # @param [String] webid Your WebID URL
+    # @param [String] name arbitrary string to call your token
+    #
+    # @return [String] The string of a valid token
+    #
     def get_current_access_token(webid:, name: "my-token")
       create_access_token(webid: webid, name: name) unless current_access_token && !(current_access_token.empty?)
 
@@ -141,11 +182,29 @@ module SOLID
       current_access_token
     end
 
+    #
+    # Get the CommunityClient ready to do a specific DPoP interaction.  DPoP requires the URL that you will interact with, adn the HTEP method you will use.  You have to call this method prior to every new kind of interaction with the POD 
+    #
+    # @param [String] url The URL you will interact with
+    # @param [String] method The HTTP Method (e.g. GET)
+    #
+    # @return [SOLID::DPOP] a SOLID::DPOP object
+    #
     def prepare_dpop(url:, method:)
       SOLID::DPOP.new(url: url, method: method)
     end
 
 
+    #
+    # Execute an interaction with a POD (e.g. read or create a resource or container)
+    #
+    # @param [SOLID::DPOP] dpop The appropriate DPOP object (created by #prepare_dpop)
+    # @param [String] data The data in your payload (can be "" but MUST be set, even for a GET!)
+    # @param [String] content_type the MIME Content-type for the data
+    # @param [String] current_access_token Your current access token (from #get_current_access_token)
+    #
+    # @return [RestClient::Response] This has no error checking at all... a failed request will cause a crash
+    #
     def execute_with_proof(dpop:, data:, content_type:, current_access_token:)
 
       req = RestClient::Request.new({

data/lib/version.rb

@@ -2,6 +2,6 @@
 
 module SOLID
   module CommunityClient
-    VERSION = "0.0.2"
+    VERSION = "0.0.3"
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: solid-community-client-simple
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.3
 platform: ruby
 authors:
 - Mark Wilkinson
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-08-13 00:00:00.000000000 Z
+date: 2024-08-16 00:00:00.000000000 Z
 dependencies: []
 description: A simple client to interact with the SOLID Community Server.  NOTA BENE
   - this is NOT a fully functional SOLID client. It does only what I need it to do
@@ -58,7 +58,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.33
+rubygems_version: 3.3.23
 signing_key: 
 specification_version: 4
 summary: A simple client to interact with the SOLID Community Server.