shep 0.1.0.pre.alpha0 → 0.2.1.pre.alpha0

data/lib/shep/version.rb

@@ -0,0 +1,4 @@
+
+module Shep
+  Version = '0.2.1-alpha0'
+end

data/lib/shep.rb

@@ -11,9 +11,9 @@ require 'fileutils'
 
 # SHEP: Simple Http intErface to Pmastodon
 module Shep
-
 end
 
+require_relative 'shep/version'
 require_relative 'shep/exceptions'
 require_relative 'shep/typeboxes'
 require_relative 'shep/entity_base'

data/run_rake_test.example.sh

@@ -5,12 +5,15 @@ set -e
 # needed to run the full suite of tests.  Actual values have been
 # replaced with nonsense.
 #
-# If none of these are set, only offline tests will be run
+# If none of these are set, only offline tests will be run.
+#
+# Put your test command on the command line to invoke it; otherwise,
+# it will run `rake test`.
 
 
 #
 # Set these to enable basic read tests:
-# 
+#
 
 # The host
 #export SHEP_TEST_HOST="mastodon.anti.social"
@@ -24,7 +27,7 @@ set -e
 # Set these if you also have an account that you wish to use for
 # testing.  This will only read from the account (we hope), but it's
 # probably not a good idea to use an account you care about.
-# 
+#
 
 #export SHEP_ACCOUNT=54321
 #export SHEP_TOKEN=JDJidvpsdvjapojSDFvfvafWER3qrwDVe4
@@ -41,6 +44,10 @@ set -e
 
 #export SHEP_TEST_ALL=1
 
-
 cd $(dirname "$0")/shep
-rake test
+
+if [ -z "$1" ]; then
+    rake test
+else
+    eval "$@"
+fi

data/shep.gemspec

@@ -1,6 +1,8 @@
+require_relative "lib/shep/version"
+
 Gem::Specification.new do |s|
   s.name        = 'shep'
-  s.version     = '0.1.0-alpha0'
+  s.version     = Shep::Version
   s.date        = '2023-06-03'
   s.summary     = "An alternate interface to the Mastodon Web API"
   s.description = <<-EOF
@@ -24,5 +26,5 @@ EOF
   s.add_development_dependency 'rake', '~> 13.0.6'
   
   s.homepage    = 'https://codeberg.org/suetanvil/shep'
-  s.license     = 'AGPL with linking exemption'
+  s.license     = 'AGPL-3.0-only with linking exception'
 end

data/spec/session_reader_1_unauth_spec.rb

@@ -2,16 +2,16 @@
 require_relative 'spec_helper'
 require_relative '../lib/shep'
 
+require "stringio"
+
 include Shep
 
 
 describe Session, :anonymous do
   include_context :uses_temp_dir
 
-
-
   it "retrieves account information." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
     acct = ss.fetch_account(READ_ACCOUNT)
 
     expect( acct.class ) .to be Entity::Account
@@ -24,7 +24,7 @@ describe Session, :anonymous do
   end
 
   it "keeps track of rate limit information." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
     acct = ss.fetch_account(READ_ACCOUNT)
 
     expect( ss.rate_limit.remaining ) .to be <= ss.rate_limit.limit
@@ -34,7 +34,7 @@ describe Session, :anonymous do
   end
 
   it "retrieves followers and following accounts." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     following = ss.each_following(READ_ACCOUNT, limit: 10).to_a
     expect( following.size  ) .to be <= 10
@@ -47,7 +47,7 @@ describe Session, :anonymous do
   end
 
   it "retrieves statuses." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     sts_all = ss.each_status(READ_ACCOUNT, limit: 50).to_a
     expect( sts_all.size ) .to be > 0
@@ -76,15 +76,20 @@ describe Session, :anonymous do
 
 
   it "does more account stuff." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     acct1 = ss.fetch_account_by_username(READ_ACCOUNT_HANDLE)
     acct2 = ss.fetch_account(acct1.id)
     expect( acct1 ) .to eq acct2
+
+    # If it's missing, you should get nil back. (Funny prank idea: create
+    # this account just to mess with me.)
+    bogus = ss.fetch_account_by_username("bogus_account_not_here_alsidjfals")
+    expect( bogus ) .to be nil
   end
 
   it "fetches individual statuses." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     count = 0
     ss.each_status(READ_ACCOUNT, limit: 5) {|ref_status|
@@ -96,7 +101,7 @@ describe Session, :anonymous do
   end
 
   it "leaves optional session fields nil if no token is given." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
     statuses = ss.each_status(READ_ACCOUNT, limit: 1).to_a
 
     expect( statuses.size ) .to be > 0
@@ -110,7 +115,7 @@ describe Session, :anonymous do
   end
 
   it "fetches status contexts." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     # Search for the first status to have a reply
     match_status = nil
@@ -137,7 +142,7 @@ describe Session, :anonymous do
   end
 
   it "fetches accounts that boosted and/or favourited a status." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     status_count = 0
     boosted_found = 0
@@ -175,9 +180,8 @@ describe Session, :anonymous do
     expect( boosters_found ) .to be > 0
   end
 
-
   it "retrieves groups of items via block as well as enumerator." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     count = 0
     ss.each_following(READ_ACCOUNT, limit: 10) { count += 1 }
@@ -192,9 +196,8 @@ describe Session, :anonymous do
     expect( count ) .to be > 0
   end
 
-# TODO: move to own describe block.
   it "retrieves status' media attachments." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     # Find the earliest status with one or more media attachments
     candidate = nil
@@ -242,7 +245,7 @@ describe Session, :anonymous do
 
 
   it "retrieves the site's public timeline." do
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     caturday = "caturday"
     
@@ -282,7 +285,7 @@ describe Session, :anonymous do
   it "retrieves posts by tag." do
     caturday = "caturday"
 
-    ss = Session.new(host: HOST)
+    ss = Session.new(host: HOST, ua_comment: "(integration test)")
 
     # Find the latest 100 toots.  This assumes an average distribution
     # that may not happen on the actual live server, in which case

data/spec/session_reader_2_auth_spec.rb

@@ -7,8 +7,9 @@ require_relative '../lib/shep'
 include Shep
 
 describe Session, :account do
+
   it "fetches status sources." do
-    ss = Session.new(host: HOST, token: TOKEN)
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
     statuses = ss.each_status(WRITE_ACCOUNT, limit: 1).to_a
     expect( statuses.empty? ) .to be false
     stat0 = statuses[0]
@@ -22,13 +23,13 @@ describe Session, :account do
   end
 
   it "reads the home timeline" do
-    ss = Session.new(host: HOST, token: TOKEN)
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
     statuses = ss.each_home_status(limit: 10).to_a
     expect( statuses.size ) .to be > 0
   end
 
   it "reads notifications" do
-    ss = Session.new(host: HOST, token: TOKEN)
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
 
     ntfns = ss.each_notification(limit: 10).to_a
     expect( ntfns.size ) .to be > 0
@@ -72,25 +73,22 @@ describe Session, :account do
     }.call
   end
 
-  skip "dismisses notifications" do
-    ss = Session.new(host: HOST, token: TOKEN)
+  it "timeline retrivals support max_id:" do
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
 
-    # We dismiss the first notification, then confirm that it is no
-    # longer there.  Since this is not repeatable, we skip it by
-    # default and manually enable it when we want to test it.
+    range_fn = proc { |&action|
+      group_1 = action.call(limit: 10).to_a
+      expect(group_1.size) .to eq 10   # not an error, but we can't continue if false
 
-    ntfns = ss.each_notification(limit: 10).to_a
-    expect( ntfns.size ) .to be > 0
-    first = ntfns[0]
+      group_2 = action.call(limit: 5, max_id: group_1[4].id).to_a
+      expect( group_2.size ) .to be > 0 # not an error but...
 
-    ss.dismiss_notification(first.id)
+      expect( group_2 ) .to eq group_1[5..]
+    }
 
-    ntfns2 = ss.each_notification(limit: 10).to_a
-    expect( ntfns2.size ) .to eq ntfns.size - 1
-    expect( ntfns2[0] ) .to_not eq first
+    range_fn.call{|**kwargs| ss.each_status(READ_ACCOUNT, **kwargs)}
+    range_fn.call{|**kwargs| ss.each_public_status(**kwargs)}
+    range_fn.call{|**kwargs| ss.each_tag_status("caturday", **kwargs)}
+    range_fn.call{|**kwargs| ss.each_home_status(**kwargs)}
   end
-
-
-  # skip "" do ; end
-
 end

data/spec/session_writer_spec.rb

@@ -6,8 +6,6 @@ require_relative '../lib/shep'
 
 include Shep
 
-POST_UUID = "fc49e486-d445-4ca7-9d6d-a27c89c5c471"  #SecureRandom.uuid
-
 describe Session, :account_limited do
   include_context :uses_temp_dir
 
@@ -18,7 +16,7 @@ describe Session, :account_limited do
   it "posts statuses" do
     testpost = "Test post #{POST_UUID} "
 
-    ss = Session.new(host: HOST, token: TOKEN)
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
 
     visibilities = %w{public unlisted private direct}
     for vis in visibilities
@@ -46,7 +44,7 @@ describe Session, :account_limited do
   end
 
   it "posts status with media" do
-    ss = Session.new(host: HOST, token: TOKEN)
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
 
     file1 = File.join(File.dirname(__FILE__), "data", "smallimg.jpg")
     file2 = File.join(File.dirname(__FILE__), "data", "smallish.jpg")
@@ -82,7 +80,7 @@ describe Session, :account_limited do
   end
 
   it "edits statuses" do
-    ss = Session.new(host: HOST, token: TOKEN)
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
 
     base_text = "edited msg #{POST_UUID}\n#{Time.now}\n-"
     post = ss.post_status(base_text, language: "en")
@@ -160,7 +158,7 @@ describe Session, :account_limited do
   end
 
   it "deletes statuses" do
-    ss = Session.new(host: HOST, token: TOKEN)
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
 
     # Test for the test itself
     expect( @new_posts.size ) .to be > 0
@@ -175,9 +173,4 @@ describe Session, :account_limited do
 
     @new_posts = []
   end
-
-
-  # skip "" do ; end
-  # skip "" do ; end
-
 end

data/spec/session_zzz_tricky_spec.rb

@@ -0,0 +1,205 @@
+
+# These are the things that are hard or slow to test, so they need to
+# be run by hand, possibly with some external intervention.
+
+
+require_relative 'spec_helper'
+require_relative '../lib/shep'
+
+include Shep
+
+
+# Test `dismiss_notification`; this permanently dismisses the most
+# recent notification so you will need to first confirm that a)
+# there's a notification present and b) it's one you don't care about.
+describe Session, :tricky_del_notification do
+  it "expects to be configured for writing" do
+    expect(WRITE_ACCOUNT) .to_not be nil
+  end
+
+  it "dismisses notifications" do
+    ss = Session.new(host: HOST, token: TOKEN, ua_comment: "(integration test)")
+
+    # We dismiss the first notification, then confirm that it is no
+    # longer there.  Since this is not repeatable, we skip it by
+    # default and manually enable it when we want to test it.
+
+    ntfns = ss.each_notification(limit: 10).to_a
+    expect( ntfns.size ) .to be > 0
+    first = ntfns[0]
+
+    ss.dismiss_notification(first.id)
+
+    ntfns2 = ss.each_notification(limit: 10).to_a
+    expect( ntfns2.size ) .to eq ntfns.size - 1
+    expect( ntfns2[0] ) .to_not eq first
+  end
+end
+
+
+# These tests exhaust the ratelimit of the delete API endpoint several
+# times.  Running these two tests takes a long time and leaves us with
+# no more deletes.
+describe Session, :tricky_ratelimit do
+
+  it "expects to be configured for writing" do
+    expect(WRITE_ACCOUNT) .to_not be nil
+  end
+
+  it "retries when the rate limit is reached" do
+    # Enables retry mode and sets rlhook as the hook function to call,
+    # then posts and deletes status until the hook as been called.
+    # Afterward, we make one more try.
+
+    rlhook_called = false
+    rlhook = proc do |rl|
+      rlhook_called = true
+
+      delay = (rl.reset - Time.now).round
+      STDOUT.puts "Waiting #{delay}s for rate limit to reset."
+
+      # We stop at the 3 second mark so the underlying delay will also
+      # kick in.
+      while rl.reset - 3 >= Time.now
+        STDOUT.print "\r    #{(rl.reset - Time.now).round} seconds     "
+        STDOUT.flush
+        sleep 1
+      end
+
+      STDOUT.puts "\nDone!"
+    end
+
+    ss = Session.new(host: HOST,
+                     token: TOKEN,
+                     ua_comment: "(integration test; rate limit reached)",
+
+                     rate_limit_retry: true,
+                     retry_hook: rlhook,
+
+                     logger: :info
+                    )
+
+    post_and_del = proc do
+      testpost = "test post for deleting9 #{POST_UUID} #{Time.now}"
+      post = ss.post_status(testpost)
+      delpost = ss.delete_status(post.id)
+
+      expect( post.id ) .to eq delpost.id
+
+      STDOUT.print "."
+      STDOUT.flush
+    end
+
+
+    limit = nil
+    count = 0
+    while !rlhook_called
+      post_and_del.call
+
+      # First pass, we fetch the deletion limit
+      limit = ss.rate_limit.limit unless limit
+
+      count += 1
+      expect( count ) .to be < (2*limit + 1)
+    end
+
+    # Ensure we did at least one iteration
+    expect( count ) .to be >= 1
+    expect( rlhook_called ) .to be true
+
+    # And ensure that we can do another post/delete cycle
+    post_and_del.call
+    expect( ss.rate_limit.remaining ) .to be > 0
+  end
+
+
+  # This test will deliberately exhaust the deletion rate limit.
+  it "throws Error::RateLimit when rate limit is exhusted" do
+    # We post and delete the post until the ratelimit is exhausted, at
+    # which point Session should throw a Shep::Error::RateLimit
+
+    ss = Session.new(host: HOST,
+                     token: TOKEN,
+                     ua_comment: "(integration test; rate limit reached)")
+
+    post_and_del = proc{
+      testpost = "test post #{POST_UUID} #{Time.now}"
+      post = ss.post_status(testpost)
+      delpost = ss.delete_status(post.id)
+
+      expect( post.id ) .to eq delpost.id
+    }
+
+    expect { 50.times{ post_and_del.call } }
+      .to raise_error(Shep::Error::RateLimit)
+  end
+end
+
+
+# Ratelimit retry is different for media uploads because the media
+# file is an IO-like object that gets read as part of the upload.
+# This test ensures that this also works.
+#
+# (It does this by uploading the same image file over and over again.
+# It's a small file though, so hopefully that will minimize the stress
+# we put on the server.)
+describe Session, :tricky_ratelimit_media_upload do
+  it "expects to be configured for writing" do
+    expect(WRITE_ACCOUNT) .to_not be nil
+  end
+
+  it "rate-limit retry works with media uploads too" do
+
+    rlhook_called = false
+    rlhook = proc do |rl|
+      rlhook_called = true
+
+      delay = (rl.reset - Time.now).round
+      STDOUT.puts "Waiting #{delay}s for rate limit to reset."
+
+      # We stop at the 3 second mark so the underlying delay will also
+      # kick in.
+      while rl.reset - 3 >= Time.now
+        STDOUT.print "\r    #{(rl.reset - Time.now).round} seconds     "
+        STDOUT.flush
+        sleep 1
+      end
+
+      STDOUT.puts "\nDone!"
+    end
+
+    ss = Session.new(host: HOST,
+                     token: TOKEN,
+                     ua_comment: "(integration test; rate limit reached)",
+
+                     rate_limit_retry: true,
+                     retry_hook: rlhook,
+
+                     logger: :info
+                    )
+
+    media_file = File.join(File.dirname(__FILE__), "data", "smallimg.jpg")
+
+    limit = nil
+    count = 0
+    while !rlhook_called
+      ma = ss.upload_media(media_file)
+
+      # First pass, we fetch the deletion limit
+      limit = ss.rate_limit.limit unless limit
+
+      STDOUT.print "."
+      STDOUT.flush
+
+      count += 1
+    end
+
+    # Ensure we did at least one iteration
+    expect( rlhook_called ) .to be true
+    expect( count ) .to be >= 1
+
+    # And ensure that we can do another post/delete cycle
+    ma = ss.upload_media(media_file)
+    expect( ma.id ) .to_not be nil  # kind of redundant, but whatever
+  end
+end

data/spec/spec_helper.rb

@@ -20,13 +20,22 @@ WRITE_ACCOUNT           = ENV['SHEP_ACCOUNT']
 ALL_TESTS_REQUESTED     = !!ENV['SHEP_TEST_ALL']
 
 
+
+# UUID to put in test posts so we can identify them when testing deletion.
+POST_UUID = "fc49e486-d445-4ca7-9d6d-a27c89c5c471"  #SecureRandom.uuid
+# Currently a constant so that I can clean up after broken tests.
+# Ideally, this should be different for each run.
+
+
 # Tags:
 #
-#   offline         - runs without a Mastodon server
+#   offline         - runs without a Mastodon server (always on)
 #   anonymous       - requires a server but no login
 #   account         - requires normal server account (which it *may* modify!)
 #   account_limited - like 'account' but will also perform heavily
 #                     rate-limited actions (e.g. delete, upload media)
+#
+#
 
 
 RSpec.configure {|conf|
@@ -52,8 +61,8 @@ RSpec.configure {|conf|
     puts
 
     conf.filter_run_including(:offline)
-    conf.filter_run_including(:anonymous) if allow_anonymous
-    conf.filter_run_including(:account) if allow_account
+    conf.filter_run_including(:anonymous)       if allow_anonymous
+    conf.filter_run_including(:account)         if allow_account
     conf.filter_run_including(:account_limited) if allow_limited
   end
 

data/yard_helper.rb

@@ -6,6 +6,11 @@ class EntityFieldDeclHandler < YARD::Handlers::Ruby::Base  #AttributeHandler
   namespace_only
 
   process do
+    sanitized = {
+      '<' => '&lt;',
+      '>' => '&gt;',
+    }
+
     mastotype = namespace.name.to_s.gsub(/_/, '::')
     new_docstr = "Ruby object representing a Mastodon `#{mastotype}` object:\n\n"
 
@@ -15,9 +20,13 @@ class EntityFieldDeclHandler < YARD::Handlers::Ruby::Base  #AttributeHandler
       # completely done fighting with YARD to get it to recognize my
       # 'attr' tags.
 
-      new_docstr += " * #{name} (#{type.to_yard_s})\n"
+      typename = type.to_yard_s
+        .gsub(/[<>]/) {|match| sanitized[match]}    # Excape angle brackets
+        .gsub(/(Entity::\w+)/, '{\1}')              # So YARD can generate refs
+
+      new_docstr += " * #{name} (#{typename})\n"
     end
-    
+
     new_docstr += "\n"
     new_docstr += "See `Shep::Entity` for an overview.\n\n"
     new_docstr += namespace.docstring.to_raw.strip
@@ -25,6 +34,3 @@ class EntityFieldDeclHandler < YARD::Handlers::Ruby::Base  #AttributeHandler
     namespace.docstring.replace(new_docstr)
   end
 end
-
-
-