sferik 0.0.1

data/lib/sferik/connections.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "openssl"
+require "zlib"
+require_relative "errors"
+
+module Sferik
+  # The connections a client makes its requests over
+  #
+  # Each one opened is kept, and the next request to the same scheme, host, and port is made over it, which saves
+  # connecting again: with https, most of the time a request takes. A client's own are kept by the thread that makes
+  # the request (or the fiber, which is as far as Thread.current goes), since a connection is for one at a time, and
+  # by the process, since one that a fork inherits is its parent's. They're never closed here: Net::HTTP opens one
+  # again that has sat unused for more than half a minute, or that the server has closed by then, and what a thread
+  # leaves behind is closed when it's collected, unless {Client#close} closes them first. Those of
+  # {Client#keep_alive} are kept for its block, and closed after.
+  #
+  # @api private
+  class Connections
+    # The errors Net::HTTP raises when the server can't be reached, or its response can't be read
+    NETWORK_ERRORS = [IOError, SocketError, SystemCallError, Timeout::Error, OpenSSL::SSL::SSLError, Net::HTTPBadResponse,
+      Net::HTTPHeaderSyntaxError, Net::ProtocolError, Zlib::Error].freeze
+    private_constant :NETWORK_ERRORS
+
+    # The seconds a connection may sit unused, and still be the one the next request is made over
+    #
+    # Net::HTTP's own two would open one again for anything that asks every few seconds, as a {Client#cached} client
+    # asking who's reading does, every five. Cloudflare leaves one open for minutes, and Net::HTTP looks whether the
+    # server has closed one before it uses it, whatever this says.
+    KEEP_ALIVE = 30
+    private_constant :KEEP_ALIVE
+
+    # Where a thread keeps the connections it has opened
+    OPENED = :sferik_connections
+    private_constant :OPENED
+
+    # Initialize the connections of a client
+    #
+    # @api private
+    # @param timeouts [Hash{Symbol => Numeric}] the seconds to wait: open_timeout, read_timeout, and write_timeout
+    # @param kept [Hash{Array => Net::HTTP}, nil] where to keep the connections opened, or nil for the thread to
+    # @return [Connections] the connections
+    def initialize(timeouts, kept = nil)
+      @timeouts = timeouts
+      @kept = kept
+    end
+
+    # Yield connections of their own, and close them afterwards
+    #
+    # They have the same timeouts as these.
+    #
+    # @api private
+    # @param kept [Hash{Array => Net::HTTP}] where to keep the connections opened
+    # @yield [connections] the requests to make
+    # @yieldparam connections [Connections] connections that are closed after the block
+    # @yieldreturn [Object] anything
+    # @return [Object] what the block returns
+    def keeping(kept = {})
+      yield self.class.new(@timeouts, kept)
+    ensure
+      kept.each_value(&:finish)
+    end
+
+    # Send a request
+    #
+    # @api private
+    # @param request [Net::HTTPRequest] the request, to a URL
+    # @return [Net::HTTPResponse] the response
+    # @raise [Unanswered] if the server was connected to, and its response didn't come, or can't be read
+    # @raise [NetworkError] if the server can't be connected to
+    def request(request)
+      http = connection(request.uri)
+      http.request(request)
+    rescue *NETWORK_ERRORS => e
+      raise (http ? Unanswered : NetworkError), "#{e.class}: #{e} (#{request.method} #{request.uri})"
+    end
+
+    # What a block makes of a response, made each time
+    #
+    # Only a {Cache} keeps what's made.
+    #
+    # @api private
+    # @param _uri [URI::HTTP] the URL that was asked for
+    # @param _accept [String] the media type it was asked for as
+    # @param _response [Net::HTTPResponse] the response that came
+    # @yield what to make of the response
+    # @yieldreturn [Object] what's made of it
+    # @return [Object] what the block returned
+    def made(_uri, _accept, _response)
+      yield
+    end
+
+    # Close the connections that are kept, and keep none of them
+    #
+    # One that another process opened, which a fork inherits, is only let go of: closing it here would close it for
+    # the process whose it is.
+    #
+    # @api private
+    # @return [nil]
+    def close
+      kept.each { |key, http| http.finish if key.first.eql?(Process.pid) }
+      kept.clear
+      nil
+    end
+
+    # The connections themselves, which keep no responses
+    #
+    # A {Cache} has the ones it's over instead, for another cache to be built over.
+    #
+    # @api private
+    # @return [Connections] the connections
+    def uncached = self
+
+    private
+
+    # The connection to the host of a URL
+    #
+    # It's the one kept for that scheme, host, and port, by this process, with these timeouts, opened if there's none
+    # yet, and left open.
+    #
+    # @api private
+    # @param uri [URI::HTTP] the URL
+    # @return [Net::HTTP] the connection
+    def connection(uri)
+      kept[[Process.pid, uri.scheme, uri.hostname, uri.port, @timeouts]] ||= start(uri)
+    end
+
+    # Where the connections opened are kept
+    #
+    # @api private
+    # @return [Hash{Array => Net::HTTP}] where these were given to keep theirs, or else where the thread keeps its own
+    def kept
+      given = @kept
+      return given if given
+
+      Thread.current[OPENED] ||= {}
+    end
+
+    # Open a connection to the host of a URL
+    #
+    # @api private
+    # @param uri [URI::HTTP] the URL
+    # @return [Net::HTTP] the connection, left open
+    def start(uri)
+      hostname = uri.hostname #: String
+      Net::HTTP.start(hostname, uri.port, use_ssl: uri.scheme.eql?("https"), keep_alive_timeout: KEEP_ALIVE, **@timeouts)
+    end
+  end
+  private_constant :Connections
+end

data/lib/sferik/contributions.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "day"
+require_relative "push"
+
+module Sferik
+  # A year of GitHub contributions, as returned by {API::CodeEndpoints#contributions}
+  # @api public
+  class Contributions < Resource
+    # @!method total
+    #   The contributions in the last year
+    #   @api public
+    #   @return [Integer] the contributions in the last year
+    #   @example
+    #     contributions.total # => 5242
+    attribute :total
+
+    # @!method longest_streak
+    #   The longest run of days with contributions, in days
+    #   @api public
+    #   @return [Integer] the longest run of days with contributions, in days
+    #   @example
+    #     contributions.longest_streak # => 30
+    attribute :longest_streak
+
+    # @!method days
+    #   One entry per day, oldest first
+    #   @api public
+    #   @return [Array<Day>] one entry per day, oldest first
+    #   @example
+    #     contributions.days # => [#<Sferik::Day ...>, ...]
+    list :days, "contributions", type: Day
+
+    # @!method since
+    #   The year the GitHub account was created
+    #   @api public
+    #   @return [Integer] the year the GitHub account was created
+    #   @example
+    #     contributions.since # => 2008
+    attribute :since
+
+    # @!method last_push
+    #   The latest public push, or nil if none is recent
+    #   @api public
+    #   @return [Push, nil] the latest public push, or nil if none is recent
+    #   @example
+    #     contributions.last_push # => #<Sferik::Push ...>
+    attribute :last_push, "lastPush", type: Push
+
+    # @!method live?
+    #   Whether the numbers are what GitHub says now
+    #
+    #   They aren't when they're the snapshot, which the site falls back to, or the last that were fetched, more than
+    #   two hours ago, which it goes on with when it can't fetch them again: {#as_of} says when they're from.
+    #
+    #   @api public
+    #   @return [Boolean] false when the numbers are a snapshot, or were last fetched more than two hours ago
+    #   @example
+    #     contributions.live? # => true
+    predicate :live
+
+    # @!method as_of
+    #   When the numbers are from
+    #
+    #   That's the hour they were fetched in, or the last day of the snapshot, if they're that. It's to the hour so
+    #   that numbers that are fetched again, and haven't changed, are the same response, which a {Client#cached}
+    #   client isn't sent again: {Status::Loaded#contributions} is when they were fetched, to the second.
+    #
+    #   @api public
+    #   @return [Time] when the numbers are from
+    #   @example
+    #     contributions.as_of # => 2026-10-08 01:00:00 UTC
+    timestamp :as_of, Time
+
+    # @!method command
+    #   The shell command the home page shows it as
+    #   @api public
+    #   @return [String] the shell command the home page shows it as
+    #   @example
+    #     contributions.command # => "git log --author=sferik --since=1.year --graph"
+    attribute :command
+
+    inspect_with :total, :longest_streak, :since
+  end
+end

data/lib/sferik/day.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # A day of GitHub contributions, as returned in {Contributions#days}
+  # @api public
+  class Day < Resource
+    # @!method date
+    #   The day
+    #   @api public
+    #   @return [Date] the day
+    #   @example
+    #     day.date # => #<Date: 2026-10-01>
+    timestamp :date, Date
+
+    # @!method count
+    #   The contributions that day
+    #   @api public
+    #   @return [Integer] the contributions that day
+    #   @example
+    #     day.count # => 12
+    attribute :count
+
+    # @!method level
+    #   The shade in the graph, from 0 (none) to 4 (most)
+    #
+    #   1 to 4 are the quartiles of the year's days with any contributions.
+    #   @api public
+    #   @return [Integer] the shade in the graph, from 0 (none) to 4 (most)
+    #   @example
+    #     day.level # => 3
+    attribute :level
+  end
+end

data/lib/sferik/dependency.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+require_relative "figure"
+
+module Sferik
+  # The xkcd comic on the home page, as returned by {API::ProfileEndpoints#dependency}
+  # @api public
+  class Dependency < Resource
+    # @!method command
+    #   The shell command the home page shows it as
+    #   @api public
+    #   @return [String] the shell command the home page shows it as
+    #   @example
+    #     dependency.command # => "imgcat ~/dependency.webp"
+    attribute :command
+
+    # @!method figure
+    #   The comic, and what it shows in words
+    #   @api public
+    #   @return [Figure] the comic, and what it shows in words
+    #   @example
+    #     dependency.figure # => #<Sferik::Figure href="https://xkcd.com/2347/" src="/img/dependency.webp">
+    attribute :figure, "figure", type: Figure
+  end
+end

data/lib/sferik/deployment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # The commit of the site that's deployed, as returned by {API::SiteEndpoints#deployment}
+  #
+  # A copy of the site that wasn't deployed, like one run by hand, has nil for each.
+  #
+  # @api public
+  class Deployment < Resource
+    # @!method commit
+    #   The SHA of the commit
+    #   @api public
+    #   @return [String, nil] the SHA of the commit
+    #   @example
+    #     deployment.commit # => "6a34226a3f351a78339b75430055a018ac30c964"
+    attribute :commit
+
+    # @!method deployed
+    #   When it was deployed
+    #   @api public
+    #   @return [Time, nil] when it was deployed
+    #   @example
+    #     deployment.deployed # => 2026-10-07 18:04:11 UTC
+    timestamp :deployed, Time
+
+    # @!method url
+    #   The commit, on GitHub
+    #   @api public
+    #   @return [String, nil] the commit, on GitHub
+    #   @example
+    #     deployment.url # => "https://github.com/sferik/sferik-web/commit/6a34226a3f351a78339b75430055a018ac30c964"
+    attribute :url
+  end
+end

data/lib/sferik/errors.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "net/http/status" # the reason phrases, which net/http itself doesn't load
+
+module Sferik
+  # Base error class for all Sferik errors
+  # @api public
+  class Error < StandardError; end
+
+  # Raised when a path can't be in a URL: one with a space, say
+  # @api public
+  class InvalidURL < Error; end
+
+  # Raised when the server can't be reached, or its response can't be read: a timeout, a refused connection, a failed
+  # DNS lookup, a TLS error, or a body that doesn't decompress
+  # @api public
+  class NetworkError < Error; end
+
+  # Raised when a request was sent, or may have been, and no answer came that could be read: the connection was
+  # open, and then it timed out, or closed, or what came back wasn't a response. Any other {NetworkError} is for a
+  # server that couldn't be connected to, so nothing was sent.
+  # @api public
+  class Unanswered < NetworkError; end
+
+  # Raised when a request is redirected more than {Client#max_redirects} times
+  # @api public
+  class TooManyRedirects < Error; end
+
+  # Raised when a response isn't what the API documents, such as JSON that doesn't parse
+  # @api public
+  class InvalidResponse < Error; end
+
+  # Base class for HTTP errors from the sferik.net API
+  # @api public
+  class HTTPError < Error
+    # The media type of a response that is plain text, whatever its parameters
+    PLAIN_TEXT = %r{\Atext/plain\s*(;|\z)}i
+    private_constant :PLAIN_TEXT
+
+    # A Retry-After header that gives a number of seconds
+    SECONDS = /\A\d+\z/
+    private_constant :SECONDS
+
+    # The status code of an error that is built without one: none, since this class is for no status in particular
+    # @api public
+    CODE = nil
+
+    # The HTTP status code
+    # @api public
+    # @return [Integer, nil] the HTTP status code: nil only for an error built by hand, of a class with no {CODE}
+    # @example
+    #   error.code # => 404
+    attr_reader :code
+
+    # The headers of the response
+    # @api public
+    # @return [Hash{String => String}] the headers by name, in lowercase, frozen
+    # @example
+    #   error.headers["content-type"] # => "application/json; charset=utf-8"
+    attr_reader :headers
+
+    # The body of the response
+    # @api public
+    # @return [String] the body, in the charset its Content-Type names (without one, UTF-8 if it's text or JSON, and binary
+    #   if not), frozen
+    # @example
+    #   error.body # => "{\"error\":\"Not Found\"}"
+    attr_reader :body
+
+    # Initialize a new HTTPError
+    #
+    # The message is the error a JSON response body names, or else the body if it's plain text, or else the status
+    # line: a page of HTML, as a proxy in front of the API may answer with, is no message. The message is in UTF-8,
+    # whatever the charset of the body: bytes that aren't valid in that charset are replaced, and a body in a charset
+    # that can't be read as text at all is no message either.
+    #
+    # Nothing is required, so that an error can be raised by hand, as a spec that stubs a request does: the code is
+    # then the one the class is for (404 for {NotFound}), and the message its status line, or the class's name for a
+    # class with no code.
+    #
+    # @api public
+    # @param message [String, nil] a message to use instead: why a redirect wasn't followed, say
+    # @param code [Integer, nil] the HTTP status code (defaults to the CODE of the class)
+    # @param reason [String, nil] the reason phrase of the status line: "Not Found", say (defaults to the code's)
+    # @param headers [Hash{String => String}] the headers of the response by name, in lowercase
+    # @param body [String] the body of the response
+    # @return [HTTPError] a new instance
+    # @example
+    #   Sferik::HTTPError.new(code: 404, reason: "Not Found", headers: {"content-type" => "text/plain"}, body: "")
+    # @example Raise one by hand, with the code of its class
+    #   raise Sferik::NotFound                # code 404, message "404 Not Found"
+    #   raise Sferik::NotFound, "No such page"
+    def initialize(message = nil, code: self.class::CODE, reason: Net::HTTP::STATUS_CODES[code], headers: {}, body: "")
+      @code = code
+      @headers = headers.dup.freeze
+      @body = body.dup.freeze
+      super(message || detail(reason))
+    end
+
+    # Which error it is, as the API names it in a JSON response body
+    #
+    # The two endpoints that write name theirs: "busy" and "full" for a 429 from {API::SiteEndpoints#write} (one message
+    # a minute from an address, and twenty a day in all), "too_long", "empty", "undelivered", and so on. And any
+    # request may be told "not_found", "bad_path" (a path that isn't properly percent-encoded), "method_not_allowed",
+    # or "internal" (the server's own failure), and {API::ProfileEndpoints#webfinger} "no_account".
+    #
+    # @api public
+    # @return [String, nil] the code: nil if the body isn't JSON that names one
+    # @example
+    #   error.error_code # => "busy"
+    def error_code
+      named(utf8.scrub, "code")
+    rescue Encoding::ConverterNotFoundError
+      nil
+    end
+
+    # The seconds to wait before trying again
+    #
+    # They are what the Retry-After header of the response gives, as a 429 has, and a 502 from {API::SiteEndpoints#write}.
+    #
+    # @api public
+    # @return [Integer, nil] the seconds: nil if the response doesn't say, or names a date rather than a number of seconds
+    # @example
+    #   error.retry_after # => 60
+    def retry_after
+      seconds = headers["retry-after"]
+      seconds.to_i if SECONDS.match?(seconds)
+    end
+
+    private
+
+    # What the response says went wrong
+    #
+    # @api private
+    # @param reason [String, nil] the reason phrase of the status line
+    # @return [String, nil] the error the body names, or else the body if that's plain text, or else the status line,
+    #   if there is one
+    def detail(reason)
+      text = utf8.scrub.strip
+      named(text, "error") || plain(text) || status_line(reason)
+    rescue Encoding::ConverterNotFoundError
+      status_line(reason)
+    end
+
+    # The status line of the response, without the version of HTTP
+    #
+    # @api private
+    # @param reason [String, nil] the reason phrase
+    # @return [String, nil] the code and the reason, or whichever there is, or nil if there's neither
+    def status_line(reason)
+      line = "#{code} #{reason}".strip
+      line unless line.empty?
+    end
+
+    # The body in UTF-8, so that the message can be put in any other text
+    #
+    # A binary body, which is one that isn't text or JSON and whose response named no charset, is taken for UTF-8.
+    #
+    # @api private
+    # @return [String] the body, in UTF-8
+    # @raise [Encoding::ConverterNotFoundError] if the body's charset is one nothing can be converted from, like UTF-7
+    def utf8
+      return String.new(body, encoding: Encoding::UTF_8) if body.encoding.equal?(Encoding::BINARY)
+
+      body.encode(Encoding::UTF_8, invalid: :replace, undef: :replace)
+    end
+
+    # What a JSON response body names
+    #
+    # @api private
+    # @param text [String] the response body
+    # @param key [String] the key: "error" or "code" (the API's errors are {"error": "Not Found", "code": "not_found"})
+    # @return [String, nil] the String a JSON object has under the key, if it does
+    def named(text, key)
+      parsed = JSON.parse(text)
+      value = parsed.fetch(key, nil) if parsed.instance_of?(Hash)
+      value if value.instance_of?(String)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # The body of a response that is plain text
+    #
+    # @api private
+    # @param text [String] the response body
+    # @return [String, nil] the body, if the response is plain text and has one
+    def plain(text)
+      text if PLAIN_TEXT.match?(headers["content-type"]) && !text.empty?
+    end
+  end
+
+  # Raised for a 4xx response
+  # @api public
+  class ClientError < HTTPError
+    # The status code of an error that is built without one
+    # @api public
+    CODE = 400
+  end
+
+  # Raised for a 404 Not Found response
+  # @api public
+  class NotFound < ClientError
+    # The status code of an error that is built without one
+    # @api public
+    CODE = 404
+  end
+
+  # Raised for a 406 Not Acceptable response: the resource has no representation in the format asked for
+  # @api public
+  class NotAcceptable < ClientError
+    # The status code of an error that is built without one
+    # @api public
+    CODE = 406
+  end
+
+  # Raised for a 429 Too Many Requests response: the server takes one message a minute from an address, and twenty a
+  # day in all (see {API::SiteEndpoints#write}). {#retry_after} is how long to wait, and {#error_code} which limit it was.
+  # @api public
+  class TooManyRequests < ClientError
+    # The status code of an error that is built without one
+    # @api public
+    CODE = 429
+  end
+
+  # Raised for a 5xx response
+  # @api public
+  class ServerError < HTTPError
+    # The status code of an error that is built without one
+    # @api public
+    CODE = 500
+  end
+end

data/lib/sferik/figure.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require_relative "resource"
+
+module Sferik
+  # An image, and what it is in words, as returned by {Dependency#figure}
+  # @api public
+  class Figure < Resource
+    # @!method type
+    #   "figure"
+    #   @api public
+    #   @return [String] "figure"
+    #   @example
+    #     figure.type # => "figure"
+    attribute :type
+
+    # @!method href
+    #   Where the image is from
+    #   @api public
+    #   @return [String] where the image is from
+    #   @example
+    #     figure.href # => "https://xkcd.com/2347/"
+    attribute :href
+
+    # @!method src
+    #   The image's path
+    #   @api public
+    #   @return [String] the image's path
+    #   @example
+    #     figure.src # => "/img/dependency.webp"
+    attribute :src
+
+    # @!method srcset
+    #   The image's paths by pixel density
+    #   @api public
+    #   @return [String] the image's paths by pixel density
+    #   @example
+    #     figure.srcset # => "/img/dependency.webp 1x, /img/dependency-2x.webp 2x"
+    attribute :srcset
+
+    # @!method width
+    #   The image's width in pixels
+    #   @api public
+    #   @return [Integer] the image's width in pixels
+    #   @example
+    #     figure.width # => 385
+    attribute :width
+
+    # @!method height
+    #   The image's height in pixels
+    #   @api public
+    #   @return [Integer] the image's height in pixels
+    #   @example
+    #     figure.height # => 489
+    attribute :height
+
+    # @!method alt
+    #   What the image shows, in words
+    #   @api public
+    #   @return [String] what the image shows, in words
+    #   @example
+    #     figure.alt # => "A tall, precarious tower of blocks..."
+    attribute :alt
+
+    # @!method title
+    #   The image's title text
+    #   @api public
+    #   @return [String] the image's title text
+    #   @example
+    #     figure.title # => "Someday ImageMagick will finally break for good..."
+    attribute :title
+
+    # @!method caption
+    #   The image's caption, as HTML
+    #   @api public
+    #   @return [String] the image's caption, as HTML
+    #   @example
+    #     figure.caption # => "Adapted from ..."
+    attribute :caption
+
+    inspect_with :href, :src
+  end
+end