blue_factory 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 85317663395ff94cb8ab867825021b522b84f99ce46d7175411438fb225fa9ac
-  data.tar.gz: bb1edb042efcb2bb387f0fc1ef37c94169fbd7b579f8d7da5227f5029a488e75
+  metadata.gz: 137dfe791cea0735d1e273b584e5e9c0bc7bd475f55fa83480e6401b20d4f074
+  data.tar.gz: c191f1baf6c008233796c97eb67f6489b3cf43dcea2a99c5354bb51373410c53
 SHA512:
-  metadata.gz: 7d98c5367c5a939cd3bc2c02a51a3513668bc73aa898141e40e1c2d2c12698b3dc653fb3e04bde7fd5b3d0b523c8f7f15507a50ffb264d3329c6bf91661fdff5
-  data.tar.gz: f5604c93743f6790123a8ade93ed2c6984e6d198692c5b3c5a66b9508597e7f4ecff0d37bb520853f251fcf15afa437f6eb7f9e572a40630437683b9b3345829
+  metadata.gz: 9af6495afeae4b5698621433232432ee5deaaedcf55bab7090ab43ab37bdb0c12b47f5b0888d7fea747423f468ecf5378878a270187421c1f20b3fe345a05c2b
+  data.tar.gz: b6aa3624fb8c84a479611f143459dd4bfea1f835c59907fbf53ae23f2c8671f0605149fd835162d26940243d4e7975a3cc57cf638d293d93196e40484cf6dda0

data/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.3.0] - 2026-02-15
+
+- added YARD documentation
+- added explicit `base64` dependency in gemspec
+- added `MAX_LIMIT` (100) and `DEFAULT_LIMIT` (50) constants
+- removed the length limit on feed rkeys, since it isn't actually limited to 15
+- removed deprecated options `enable_unsafe_auth` and `validate_responses`
+- fixed `rake:publish` not working with feed `description` is nil (thx @jthigpen)
+- `rake:publish` shows a better error message when `createSession` requires a 2FA token
+- added various additional checks:
+  * `Server` checks if `BlueFactory.hostname` and `BlueFactory.publisher_did` are set before launching
+  * `add_feed` checks if the key contains only valid characters
+  * `add_feed` checks if the feed class has a `#get_posts` method
+  * `getFeedSkeleton` ensures that the limit param is between 1 and 100 (so you don't need to check that)
+  * `raw_did` checks if the extracted payload contains an `iss` key
+
 ## [0.2.1] - 2025-12-07
 
 - updated gemspec so the gem can be used with Sinatra 4.x

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The zlib License
 
-Copyright (c) 2025 Jakub Suder
+Copyright (c) 2026 Jakub Suder
 
 This software is provided 'as-is', without any express or implied
 warranty.  In no event will the authors be held liable for any damages

data/README.md

@@ -3,19 +3,21 @@
 A Ruby gem for hosting custom feeds for Bluesky.
 
 > [!NOTE]
-> ATProto Ruby gems collection: [skyfall](https://tangled.org/@mackuba.eu/skyfall) | [blue_factory](https://tangled.org/@mackuba.eu/blue_factory) | [minisky](https://tangled.org/@mackuba.eu/minisky) | [didkit](https://tangled.org/@mackuba.eu/didkit)
+> Part of ATProto Ruby SDK: [ruby.sdk.blue](https://ruby.sdk.blue)
 
 
 ## What does it do
 
 BlueFactory is a Ruby library which helps you build a web service that hosts custom feeds a.k.a. "[feed generators](https://github.com/bluesky-social/feed-generator)" for the Bluesky social network. It implements a simple HTTP server based on [Sinatra](https://sinatrarb.com) which provides the required endpoints for the feed generator interface. You need to provide the content for the feed by making a query to your preferred local database.
 
-A feed server will usually be run together with a second piece of code that streams posts from the Bluesky "firehose" stream, runs them through some kind of filter and saves some or all of them to the database. To build that part, you can use my other Ruby gem [Skyfall](https://tangled.org/@mackuba.eu/skyfall).
+A feed server will usually be run together with a second piece of code that streams posts from the Bluesky "firehose" stream, runs them through some kind of filter and saves some or all of them to the database. To build that part, you can use my other Ruby gem [Skyfall](https://tangled.org/mackuba.eu/skyfall).
 
 
 ## Installation
 
-Add this to your `Gemfile`:
+BlueFactory should run on any somewhat recent version of Ruby (3.x/4.x), although it's recommended to use one that's still getting maintenance updates, ideally the latest one. In production, it's also recommended to install it with [YJIT support](https://shopify.engineering/ruby-yjit-is-production-ready) and with [jemalloc](https://scalingo.com/blog/improve-ruby-application-memory-jemalloc). A compatible version should be preinstalled on many Linux systems, otherwise you can install one using tools such as [RVM](https://rvm.io), [asdf](https://asdf-vm.com), [ruby-install](https://github.com/postmodern/ruby-install) or [ruby-build](https://github.com/rbenv/ruby-build), or `rpm` or `apt-get` on Linux (see more installation options on [ruby-lang.org](https://www.ruby-lang.org/en/downloads/)).
+
+To use it in your app, add this to your `Gemfile`:
 
     gem 'blue_factory', '~> 0.2'
 
@@ -27,7 +29,7 @@ The server is configured through the `BlueFactory` module. The two required sett
 - `publisher_did` – DID identifier of the account that you will publish the feed on (the string that starts with `did:plc:...`)
 - `hostname` – the hostname on which the feed service will be run
 
-You also need to configure at least one feed by passing a feed key and a feed object. The key is the identifier (rkey) that will appear at the end of the feed URI – it must only contain characters that are valid in URLs (preferably all lowercase) and it can't be longer than 15 characters. The feed object is anything that implements the single required method `get_posts` (could be a class, a module or an instance).
+You also need to configure at least one feed by passing a feed key and a feed object. The key is the identifier (rkey) that will appear at the end of the feed URI – it must only contain characters that are valid in URLs (preferably all lowercase) and it should be rather short. The feed object is anything that implements the single required method `get_posts` (could be a class, a module or an instance).
 
 So a simple setup could look like this:
 
@@ -335,7 +337,7 @@ You also need to republish the feed by running the same task again any time you
 
 ## Credits
 
-Copyright © 2025 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/mackuba.eu)).
+Copyright © 2026 Kuba Suder ([@mackuba.eu](https://bsky.app/profile/did:plc:oio4hkxaop4ao4wz2pp3f4cr)).
 
 The code is available under the terms of the [zlib license](https://choosealicense.com/licenses/zlib/) (permissive, similar to MIT).
 

data/lib/blue_factory/configuration.rb

@@ -1,36 +1,43 @@
 require_relative 'modules/configurable'
 require_relative 'modules/interactions'
 require_relative 'modules/feeds'
+require_relative 'errors'
 
 module BlueFactory
   extend Configurable
   extend Feeds
   extend Interactions
 
+  #
+  # The server's `did:web:` service DID built from the configured hostname.
+  # @return [String]
+  # @raise [ConfigurationError] if the hostname is not set
+  #
   def self.service_did
+    if hostname.nil?
+      raise ConfigurationError, "The `hostname` property is not set. Set it with: BlueFactory.set(:hostname, 'example.com')"
+    end
+
     'did:web:' + hostname
   end
 
+  #
+  # Current application environment, usually `:development` or `:production`. It's read from the
+  # env variables `APP_ENV` or `RACK_ENV`, or `:development` by default.
+  #
+  # @return [Symbol]
+  #
   def self.environment
     (ENV['APP_ENV'] || ENV['RACK_ENV'] || :development).to_sym
   end
 
-  configurable :publisher_did, :hostname, :validate_responses, :enable_unsafe_auth
+  # @!method self.hostname
+  #   The hostname on which the feed server runs. Configured through {#set}.
+  #   @return [String, nil]
 
-  def self.set(property, value)
-    if property.to_sym == :enable_unsafe_auth
-      puts "==="
-      puts "WARNING: option :enable_unsafe_auth and old API get_posts(args, user_did) is deprecated and will be removed in version 0.3."
-      puts "Switch to get_posts(args, context) instead and get the user DID from: context.user.raw_did."
-      puts "==="
-      @enable_unsafe_auth = value
-    elsif property.to_sym == :validate_responses
-      puts "==="
-      puts "WARNING: option :validate_responses is deprecated and will be removed in version 0.3. " +
-        "Responses are now always validated, also in production."
-      puts "==="
-    else
-      super
-    end
-  end
+  # @!method self.publisher_did
+  #   The DID of the account publishing the feeds. Configured through {#set}.
+  #   @return [String, nil]
+
+  configurable :publisher_did, :hostname
 end

data/lib/blue_factory/errors.rb

@@ -1,31 +1,77 @@
 module BlueFactory
+
+  #
+  # Raised during request processing if the authorization token can't be parsed; it can also be
+  # thrown from the user's {FeedHandler#get_posts} method to indicate that the given user is not
+  # authorized to access the requested feed, or that the feed requires authentication and it wasn't
+  # provided.
+  #
+  # The server intercepts this exception and returns a "401 Unauthorized" response to the AppView,
+  # which should result in the app displaying an error banner (along with the provided error
+  # message) in the feed view.
+  #
+
   class AuthorizationError < StandardError
+
+    # @return [String, nil] machine-readable error identifier
     attr_reader :error_type
 
-    def initialize(message = "Authentication required", error_type = nil)
+    # @param message [String] human-readable error message
+    # @param error_type [String] machine-readable error code
+    #
+    def initialize(message = "Authentication required", error_type = "AuthenticationRequired")
       super(message)
       @error_type = error_type
     end
   end
 
-  class InvalidKeyError < StandardError
+  #
+  # Raised when some required configuration is missing or invalid.
+  #
+
+  class ConfigurationError < StandardError
   end
 
+  #
+  # Raised during request processing if some of the parameters are invalid. The error is turned
+  # into a "400 Bad Request" response send to the AppView.
+  #
+
   class InvalidRequestError < StandardError
+
+    # @return [String, nil] machine-readable error identifier
     attr_reader :error_type
 
-    def initialize(message, error_type = nil)
+    # @param message [String] human-readable error message
+    # @param error_type [String] machine-readable error code
+    #
+    def initialize(message, error_type = "InvalidRequest")
       super(message)
       @error_type = error_type
     end
   end
 
+  #
+  # Raised during request processing if the response returned by the user's class from the
+  # {FeedHandler#get_posts} method doesn't fully match the expected format. The error is turned
+  # into a "500 Internal Server Error" response returned to the AppView.
+  #
+
   class InvalidResponseError < StandardError
   end
 
+  #
+  # Raised during request processing if the user's provided class does not have expected API.
+  #
+
   class InvalidFeedClassError < StandardError
   end
 
+  #
+  # Raised during request processing if the `:feed` parameter points to a feed generator URI
+  # which is not on the list of feeds configured in the app.
+  #
+
   class UnsupportedAlgorithmError < StandardError
   end
 end

data/lib/blue_factory/feed_handler.rb

@@ -0,0 +1,153 @@
+module BlueFactory
+
+  #
+  # @abstract This is not a real class, but it shows what *your* feed class should look like.
+  #
+  # Abstract interface describing the API that the feed class that will be handling the requests
+  # sent to `getFeedSkeleton`, which you pass to {BlueFactory::Feeds#add_feed}, is expected to have.
+  #
+  # All methods except {#get_posts} are only used briefly when submitting the feed as a record
+  # using the `bluesky:publish` rake task, so only {#get_posts} is really required during normal
+  # day to day operation.
+  #
+
+  class FeedHandler
+
+    # The main method required to serve a feed. It accepts a hash of query params and optionally
+    # a request context object, and is expected to return a hash of data with URIs of posts to
+    # be displayed.
+    #
+    # The response hash should include:
+    #
+    # - `:posts` *(Array<String, Hash>)* — an array of posts (see below)
+    # - `:cursor` *(String)* — optionally, a cursor to be passed when loading the next page
+    # - `:req_id` *(String)* — optionally, a request ID that will be passed with "interactions"
+    #
+    # A post in `:posts` can be either a string with the AT URI of the post, or a hash with fields:
+    #
+    # - `:post` *(String)* — the AT URI of the post
+    # - `:context` *(String)* — optionally, a context string that will be passed with "interactions"
+    # - `:reason` *(Hash)* — optionally, a reason why a post appears in the feed:
+    #     - `{ :repost => repost_uri }` — the post is displayed because someone reposted it (the uri points to a repost record)
+    #     - `{ :pin => true }` — the post is pinned at the top of the feed
+    #
+    # @example Simple posts response
+    #   {
+    #     posts: [
+    #       "at://.../app.bsky.feed.post/...",
+    #       "at://.../app.bsky.feed.post/...",
+    #       "at://.../app.bsky.feed.post/...",
+    #       ...
+    #     ],
+    #     cursor: "1760639159"
+    #   }
+    #     
+    # @example More complex response
+    #   {
+    #     posts: [
+    #       {
+    #         post: "at://.../app.bsky.feed.post/...",
+    #         reason: { pin: true }
+    #       },
+    #       "at://.../app.bsky.feed.post/...",
+    #       "at://.../app.bsky.feed.post/...",
+    #       "at://.../app.bsky.feed.post/...",
+    #       {
+    #         post: "at://.../app.bsky.feed.post/...",
+    #         reason: { repost: "at://.../app.bsky.feed.repost/..." },
+    #         context: 'qweqweqwe'
+    #       },
+    #       "at://.../app.bsky.feed.post/...",
+    #       ...
+    #     ],
+    #     cursor: "1760639159",
+    #     req_id: "req2048"
+    #   }
+    #
+    # @example User authorization
+    #   def get_posts(params, context)
+    #     if AUTHORIZED_USERS.include?(context.user.raw_did)
+    #       # ...
+    #     else
+    #       raise BlueFactory::AuthorizationError, "You shall not pass!"
+    #     end
+    #   end
+    #
+    # @overload get_posts(params)
+    #   Use this version if you don't need the context object.
+    #
+    #   @param params [Hash] the received query params
+    #
+    #   @option params [String] :feed
+    #     the AT URI of the feed record
+    #   @option params [String, nil] :cursor
+    #     the cursor returned from the last response (the format is chosen by you)
+    #   @option params [Integer, nil] :limit
+    #     requested number of posts (between 1 and 100)
+    #
+    #   @raise [InvalidRequestError] if the request is invalid for some reason (e.g. bad cursor format)
+    #   @return [Hash] post data
+    #
+    # @overload get_posts(params, context)
+    #   Use this version if you want to be passed the context object.
+    #
+    #   @param params [Hash] the received query params
+    #   @param context [RequestContext] request context
+    #
+    #   @option params [String] :feed
+    #     the AT URI of the feed record
+    #   @option params [String, nil] :cursor
+    #     the cursor returned from the last response (the format is chosen by you)
+    #   @option params [Integer, nil] :limit
+    #     requested number of posts (between 1 and 100)
+    #
+    #   @raise [AuthorizationError] if the requesting user is not authorized to see this feed
+    #   @raise [InvalidRequestError] if the request is invalid for some reason (e.g. bad cursor format)
+    #   @return [Hash] post data
+
+    def get_posts(params, context = nil)
+    end
+
+    # Returns the name of the feed that will be shown to the user in the app.
+    #
+    # This name is displayed not only in the header and in link cards, but also in the pinned feeds
+    # tabs and the right sidebar on the desktop, so it should not be too long, ideally 1-3 words.
+    #
+    # @return [String]
+
+    def display_name
+    end
+
+    # (optional) Longer description of the feed, which explains how the feed works and what kind of
+    # content it serves.
+    #
+    # @return [String, nil]
+
+    def description
+    end
+
+    # (optional) Path of the image file which will be used as the feed's avatar (PNG or JPG).
+    #
+    # @return [String, nil]
+
+    def avatar_file
+    end
+
+    # (optional) Special feed type - return `:video` for video feeds.
+    #
+    # @return [String, nil]
+
+    def content_mode
+    end
+
+    # (optional) Return true to opt-in to receiving interactions from users viewing the feed.
+    #
+    # @see Interaction
+    # @return [Boolean]
+
+    def accepts_interactions
+    end
+
+    private_class_method :new
+  end
+end

data/lib/blue_factory/interaction.rb

@@ -1,17 +1,74 @@
 module BlueFactory
+
+  #
+  # Represents a single feed interaction event.
+  #
+  # Interactions are various kinds of events registered while a user is browsing the feed,
+  # either automatically in response to their browsing (e.g. "post seen", "post liked") or as
+  # explicit actions taken consciously by the user, with the intention of passing information back
+  # to the feed operator (clicking "show more like this" / "show less like this" in the post context
+  # menu). Interactions are submitted through the `app.bsky.feed.sendInteractions` endpoint and may
+  # be batched.
+  #
+  # When that endpoint is called, BlueFactory wraps the submitted interaction objects in
+  # instances of {Interaction} and passes them to the configured handler block, which is set up
+  # through {Interactions#on_interactions} or {Interactions#interactions_handler=} on {BlueFactory}.
+  #
+  # Note: the {Interaction} objects include info about what interaction has been triggered and
+  # on which specific post (post AT URI), but they don't include info in which *feed* it has been
+  # triggered. If you have multiple feeds configured and need to know which feed an interaction
+  # is from, you need to include either a `context` field (assigned to a specific post) or a
+  # `req_id` field (assigned to the whole request) in the data response returned from
+  # {FeedHandler#get_posts}.
+  #
+
   class Interaction
+
+    #
+    # Mapping of interaction identifiers in the protocol to short code symbols.
+    #
+
     EVENTS = {
+      # user has liked a post in the feed
       'app.bsky.feed.defs#interactionLike' => :like,
+
+      # user has quoted a post in the feed
       'app.bsky.feed.defs#interactionQuote' => :quote,
+
+      # user has replied to a post in the feed
       'app.bsky.feed.defs#interactionReply' => :reply,
+
+      # user has reposted a post in the feed
       'app.bsky.feed.defs#interactionRepost' => :repost,
+
+      # user has scrolled down to the given post
       'app.bsky.feed.defs#interactionSeen' => :seen,
+
+      # user has clicked "show less like this" on a post
       'app.bsky.feed.defs#requestLess' => :request_less,
+
+      # user has clicked "show more like this" on a post
       'app.bsky.feed.defs#requestMore' => :request_more
     }
 
-    attr_reader :item, :event, :context, :req_id, :type
+    # @return [String] the URI of the post
+    attr_reader :item
+
+    # @return [String] the protocol identifier of the interaction type
+    attr_reader :event
+
+    # @return [Symbol, nil] short code symbol of the interaction type
+    attr_reader :type
+
+    # @return [String, nil] optional post context from the original response
+    attr_reader :context
+
+    # @return [String, nil] optional request identifier from the original response
+    attr_reader :req_id
 
+    #
+    # @param data [Hash] interaction JSON data
+    #
     def initialize(data)
       @item = data['item']
       @event = data['event']

data/lib/blue_factory/modules/configurable.rb

@@ -1,4 +1,12 @@
 module BlueFactory
+
+  #
+  # @api private
+  #
+  # Adds a helper for configuring supported properties to {BlueFactory}.
+  # Use these APIs through the main {BlueFactory} module, not directly.
+  #
+
   module Configurable
     def self.extended(target)
       target.instance_variable_set('@properties', [])
@@ -10,6 +18,14 @@ module BlueFactory
       singleton_class.attr_reader(*properties)
     end
 
+    #
+    # Sets a configurable property to the given value.
+    #
+    # @api public
+    # @param property [String, Symbol] configuration key
+    # @param value [Object] value to assign
+    # @raise [NoMethodError] if no such property is defined
+    #
     def set(property, value)
       if @properties.include?(property.to_sym)
         self.instance_variable_set("@#{property}", value)
@@ -19,5 +35,6 @@ module BlueFactory
     end
 
     private :configurable
+    private_class_method :extended
   end
 end

data/lib/blue_factory/modules/feeds.rb

@@ -1,33 +1,92 @@
+require_relative '../errors'
+
 module BlueFactory
+
+  #
+  # @api private
+  #
+  # Adds configuration for feeds and provides lookup of configured feeds to {BlueFactory}.
+  # Use these APIs through the main {BlueFactory} module, not directly.
+  #
+
   module Feeds
     def self.extended(target)
       target.instance_variable_set('@feeds', {})
     end
 
-    def add_feed(key, feed_class)
+    RKEY_REGEXP = /\A[A-Za-z0-9\.\-_:~]+\z/
+
+    #
+    # Registers a feed handler for a given rkey. The full AT URI of the feed generator, which is
+    # listed in `describeFeedGenerator` and expected in the `feed` parameter to `getFeedSkeleton`
+    # will be: `"at://#{publisher_did}/app.bsky.feed.generator/#{key}"`. The key should be a string
+    # no longer than 15 characters and should not contain slashes, preferably only lowercase letters,
+    # digits and hyphens.
+    #
+    # The feed handler is expected to be an object which has a `#get_posts` method which accepts
+    # requests routed from the BlueFactory server and returns post data in a specified format.
+    # See the abstract {FeedHandler} class for a description of the expected API.
+    #
+    # @api public
+    # @param key [String] the feed rkey
+    # @param feed_handler [#get_posts] feed implementation object
+    # @raise [ConfigurationError] if the key has invalid format
+    #
+    def add_feed(key, feed_handler)
       validate_key(key)
-      @feeds[key.to_s] = feed_class
+      validate_feed(key, feed_handler)
+
+      @feeds[key.to_s] = feed_handler
     end
 
+    #
+    # Lists all configured feed keys.
+    #
+    # @api public
+    # @return [Array<String>]
+    #
     def feed_keys
       @feeds.keys
     end
 
+    #
+    # Returns a feed handler configured for a given rkey.
+    #
+    # @api public
+    # @param key [String] feed key
+    # @return [#get_posts, nil] feed object, if registered
+    #
     def get_feed(key)
       @feeds[key.to_s]
     end
 
+    #
+    # Returns an array of all registered feed handler objects.
+    #
+    # @api public
+    # @return [Array<#get_posts>]
+    #
     def all_feeds
       @feeds.values
     end
 
+
     private
 
     def validate_key(key)
-      raise InvalidKeyError, "Key must be a string" unless key.is_a?(String)
-      raise InvalidKeyError, "Key must not be empty" if key == ''
-      raise InvalidKeyError, "Key must not contain a slash" if key.include?('/')
-      raise InvalidKeyError, "Key must not be longer than 15 characters" if key.length > 15
+      raise ConfigurationError, "Key must be a string (got: #{key.inspect})" unless key.is_a?(String)
+      raise ConfigurationError, "Key must not be empty" if key == ''
+      raise ConfigurationError, "Key #{key.inspect} contains invalid characters" if key !~ RKEY_REGEXP
     end
+
+    def validate_feed(key, feed)
+      get_posts = feed.method(:get_posts) rescue nil
+
+      if get_posts.nil?
+        raise InvalidFeedClassError, "The feed object for '#{key}' is missing required method `get_posts`"
+      end
+    end
+
+    private_class_method :extended
   end
 end

data/lib/blue_factory/modules/interactions.rb

@@ -1,9 +1,47 @@
 module BlueFactory
+
+  #
+  # @api private
+  #
+  # Adds configuration for an interactions handler to {BlueFactory}.
+  # Use these APIs through the main {BlueFactory} module, not directly.
+  #
+
   module Interactions
+
+    #
+    # Returns the currently configured feed interactions handler.
+    #
+    # @api public
+    # @see Interaction
+    # @yieldparam interactions [Array<Interaction>] one or more received interactions
+    # @yieldparam context [RequestContext] HTTP request context, including e.g. user auth info
+    #
     def on_interactions(&block)
       @interactions_handler = block
     end
 
-    attr_accessor :interactions_handler
+    #
+    # Returns the currently configured feed interactions handler.
+    #
+    # @api public
+    # @see Interaction
+    # @see #on_interactions
+    # @return [Proc, nil]
+    #
+    def interactions_handler
+      @interactions_handler
+    end
+
+    #
+    # Registers a callback for incoming feed interactions.
+    #
+    # @api public
+    # @see Interaction
+    # @see #on_interactions
+    #
+    def interactions_handler=(block)
+      @interactions_handler = block
+    end
   end
 end

data/lib/blue_factory/output_generator.rb

@@ -1,6 +1,11 @@
 require_relative 'errors'
 
 module BlueFactory
+
+  #
+  # @private
+  #
+
   class OutputGenerator
     AT_URI_REGEXP = %r(^at://did:(plc:[a-z0-9]+|web:[a-z0-9\-]+(\.[a-z0-9\-]+)+)/app\.bsky\.feed\.post/[a-z0-9]+$)
 

data/lib/blue_factory/request_context.rb

@@ -1,21 +1,50 @@
 require_relative 'user_info'
 
 module BlueFactory
+
+  #
+  # An object which provides some metadata about the `getFeedSkeleton` request being processed.
+  # The context is passed to the {FeedHandler#get_posts} method of the provided feed handler object,
+  # if the method is made to accept two parameters.
+  #
+
   class RequestContext
-    attr_accessor :request
 
+    # Returns the underlying request object.
+    #
+    # @return [Sinatra::Request]
+    #   see {https://www.rubydoc.info/gems/sinatra/Sinatra/Request Sinatra::Request}
+    #
+    attr_reader :request
+
+    # @param request
+    #   ({https://www.rubydoc.info/gems/sinatra/Sinatra/Request Sinatra::Request})
+    #    — the original Sinatra/Rack request object
+    #
     def initialize(request)
       @request = request
     end
 
+    #
+    # The request environment hash.
+    # @return [Hash] Rack environment
+    #
     def env
       @request.env
     end
 
+    #
+    # Parsed user information derived from the authorization header.
+    # @return [UserInfo]
+    #
     def user
       UserInfo.new(env['HTTP_AUTHORIZATION'])
     end
 
+    #
+    # Indicates if an authorization header was provided at all or not.
+    # @return [Boolean] true when the authorization header is non-empty
+    #
     def has_auth?
       env['HTTP_AUTHORIZATION'] != nil
     end

data/lib/blue_factory/server.rb

@@ -8,7 +8,36 @@ require_relative 'output_generator'
 require_relative 'request_context'
 
 module BlueFactory
+
+  #
+  # Sinatra server implementing the required feed generator endpoints. Usually you will only
+  # interact with it in order to start the server in a startup script.
+  #
+  # @example Starting locally during development
+  #   BlueFactory::Server.run!
+  #
+  # @example Starting from Rack config `config.ru` in production
+  #   run BlueFactory::Server
+  #
+
   class Server < Sinatra::Base
+
+    # @private
+    @@config_checked = false
+
+    # Run the Sinatra app as a self-hosted server.
+    # See {https://www.rubydoc.info/gems/sinatra/Sinatra/Base#run!-class_method Sinatra::Base.run!}.
+    # @raise [ConfigurationError] if the {BlueFactory.hostname} or {BlueFactory.publisher_did} is not set
+
+    def self.run!(options = {}, &block)
+      verify_config
+      super
+    end
+
+    before do
+      Server.send(:verify_config) unless @@config_checked
+    end
+
     configure do
       disable :static
       enable :quiet
@@ -17,6 +46,10 @@ module BlueFactory
     end
 
     helpers do
+      #
+      # @api private
+      #
+
       def config
         BlueFactory
       end
@@ -43,7 +76,7 @@ module BlueFactory
         end
 
         if feed_uri !~ %r(^at://[\w\-\.\:]+/[\w\.]+/[\w\.\-]+$)
-          raise InvalidRequestError, "Error: feed must be a valid at-uri"
+          raise InvalidRequestError, "Error: feed must be a valid AT URI"
         end
 
         feed_key = feed_uri.split('/').last
@@ -55,20 +88,26 @@ module BlueFactory
 
         feed
       end
+
+      def validate_limit(args)
+        if args[:limit]
+          args[:limit] = args[:limit].to_i.clamp(1, MAX_LIMIT)
+        end
+      end
     end
 
     get '/xrpc/app.bsky.feed.getFeedSkeleton' do
       begin
         feed = get_feed(params[:feed])
-        get_posts = feed.method(:get_posts)
         args = params.slice(:feed, :cursor, :limit)
+        validate_limit(args)
 
-        if config.enable_unsafe_auth
-          context = RequestContext.new(request)
-          response = feed.get_posts(args, context.user.raw_did)
-        elsif get_posts.arity == 1
+        get_posts = feed.method(:get_posts)
+
+        case get_posts.arity
+        when 1
           response = feed.get_posts(args)
-        elsif get_posts.arity == 2
+        when 2
           context = RequestContext.new(request)
           response = feed.get_posts(args, context)
         else
@@ -78,17 +117,17 @@ module BlueFactory
         json = OutputGenerator.new.generate(response)
         return json_response(json)
       rescue InvalidRequestError => e
-        return json_error(e.error_type || "InvalidRequest", e.message)
+        return json_error(e.error_type, e.message)
       rescue AuthorizationError => e
-        return json_error(e.error_type || "AuthenticationRequired", e.message, status: 401)
+        return json_error(e.error_type, e.message, status: 401)
       rescue UnsupportedAlgorithmError => e
         return json_error("UnsupportedAlgorithm", e.message)
       rescue InvalidResponseError => e
-        if settings.development?
-          return json_error("InvalidResponse", e.message, status: 500)
-        else
+        if settings.production?
           request.logger&.<< "#{e.class}: #{e.message}\n"
           return json_error("InvalidResponse", "Feed response was invalid", status: 500)
+        else
+          return json_error("InvalidResponse", e.message, status: 500)
         end
       end
     end
@@ -126,5 +165,23 @@ module BlueFactory
         json_error('MethodNotImplemented', 'Method Not Implemented', status: 501)
       end
     end
+
+
+    private
+
+    def self.verify_config
+      if BlueFactory.hostname.nil?
+        raise ConfigurationError, "The `hostname` property is not set. Set it with: BlueFactory.set(:hostname, 'example.com')"
+      end
+
+      if BlueFactory.publisher_did.nil?
+        raise ConfigurationError,
+          "The `publisher_did` property is not set. Set it with: BlueFactory.set(:publisher_did, 'did:plc:qweqweqwe')"
+      end
+
+      @@config_checked = true
+    end
+
+    private_class_method :verify_config
   end
 end

data/lib/blue_factory/tasks/publish.rake

@@ -87,10 +87,19 @@ namespace :bluesky do
     password = STDIN.noecho(&:gets).chomp
     puts
 
-    json = BlueFactory::Net.post_request(pds_host, 'com.atproto.server.createSession', {
-      identifier: publisher_did,
-      password: password
-    })
+    begin
+      json = BlueFactory::Net.post_request(pds_host, 'com.atproto.server.createSession', {
+        identifier: publisher_did,
+        password: password
+      })
+    rescue BlueFactory::Net::ResponseError => e
+      if e.response.code.to_i == 401 && e.response.body.include?('"error":"AuthFactorTokenRequired"')
+        puts "Error: this Rake task doesn't support logging in with 2FA. Please use an app password here if you have 2FA enabled."
+        exit 1
+      else
+        raise
+      end
+    end
 
     access_token = json['accessJwt']
 
@@ -104,15 +113,15 @@ namespace :bluesky do
     record = {
       did: BlueFactory.service_did,
       displayName: feed_display_name,
-      description: feed_description,
       createdAt: Time.now.iso8601,
     }
 
     record[:avatar] = avatar_ref if avatar_ref
+    record[:description] = feed_description if feed_description
     record[:contentMode] = feed_content_mode if feed_content_mode
     record[:acceptsInteractions] = true if feed.respond_to?(:accepts_interactions) && feed.accepts_interactions
 
-    json = BlueFactory::Net.post_request(pds_host, 'com.atproto.repo.putRecord', {
+    BlueFactory::Net.post_request(pds_host, 'com.atproto.repo.putRecord', {
       repo: publisher_did,
       collection: BlueFactory::FEED_GENERATOR_TYPE,
       rkey: feed_key,

data/lib/blue_factory/tasks/support.rb

@@ -3,8 +3,25 @@ require 'net/http'
 require 'uri'
 
 module BlueFactory
+
+  #
+  # @api private
+  # HTTP request helpers.
+  #
+
   module Net
-    class ResponseError < StandardError; end
+
+    # @api private
+    # Thrown when a HTTP response is not 200 OK.
+    #
+    class ResponseError < StandardError
+      attr_reader :response
+
+      def initialize(response, message)
+        @response = response
+        super(message)
+      end
+    end
 
     def self.get_request(server, method = nil, params = nil, auth: nil)
       headers = {}
@@ -17,7 +34,7 @@ module BlueFactory
       end
 
       response = ::Net::HTTP.get_response(url, headers)
-      raise ResponseError, "Invalid response: #{response.code} #{response.body}" if response.code.to_i / 100 != 2
+      raise ResponseError.new(response, "Invalid response: #{response.code} #{response.body}") if response.code.to_i / 100 != 2
 
       JSON.parse(response.body)
     end
@@ -30,7 +47,7 @@ module BlueFactory
       body = data.is_a?(String) ? data : data.to_json
 
       response = ::Net::HTTP.post(URI("#{server}/xrpc/#{method}"), body, headers)
-      raise ResponseError, "Invalid response: #{response.code} #{response.body}" if response.code.to_i / 100 != 2
+      raise ResponseError.new(response, "Invalid response: #{response.code} #{response.body}") if response.code.to_i / 100 != 2
 
       JSON.parse(response.body)
     end

data/lib/blue_factory/user_info.rb

@@ -4,11 +4,27 @@ require 'json'
 require_relative 'errors'
 
 module BlueFactory
+
+  #
+  # An object which provides info about the user making the request, based on the
+  # included authorization header (if any). Accessed through {RequestContext#user}.
+  #
+
   class UserInfo
+
+    #
+    # @param auth_header [String, nil] value of the "Authorization" HTTP header
+    #
     def initialize(auth_header)
       @auth = auth_header
     end
 
+    #
+    # The bearer token extracted from the authorization header.
+    #
+    # @return [String, nil]
+    # @raise [AuthorizationError] if the header is not a "Bearer" token
+    #
     def token
       @token ||= begin
         if @auth.nil? || @auth.strip.empty?
@@ -21,6 +37,17 @@ module BlueFactory
       end
     end
 
+    #
+    # Returns the user's (unverified) DID decoded from the JWT payload of the bearer token.
+    #
+    # Important: this method does not verify the signature of the token, which means
+    # the token can be fairly easily forged to impersonate another user, and this method
+    # would not detect that. Do not rely on it for use cases where it's important to be
+    # certain of the requesting user's identity.
+    #
+    # @return [String, nil] user DID decoded from the token
+    # @raise [AuthorizationError] when the token format is invalid
+    #
     def raw_did
       return nil if token.nil?
 
@@ -29,10 +56,15 @@ module BlueFactory
 
       begin
         payload = JSON.parse(Base64.decode64(parts[1]))
-        payload['iss']
       rescue StandardError => e
         raise AuthorizationError.new("Invalid JWT format", "BadJwt")
       end
+
+      if did = payload['iss']
+        did
+      else
+        raise AuthorizationError.new("Invalid JWT format", "BadJwt")
+      end
     end
   end
 end

data/lib/blue_factory/version.rb

@@ -1,3 +1,3 @@
 module BlueFactory
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

data/lib/blue_factory.rb

@@ -2,6 +2,36 @@ require_relative 'blue_factory/configuration'
 require_relative 'blue_factory/server'
 require_relative 'blue_factory/version'
 
+#
+# This is the main module of the library, through which you configure the feed service.
+#
+# @example Configuring the server and feeds
+#   require 'blue_factory'
+#
+#   BlueFactory.set :publisher_did, 'did:plc:qwertyuiopasdf'
+#   BlueFactory.set :hostname, 'feeds.example.com'
+#
+#   BlueFactory.add_feed 'photos', PhotographyFeed.new
+#
+# @example Handling interactions
+#   BlueFactory.on_interactions do |interactions, context|
+#     interactions.each do |i|
+#       unless i.type == :seen
+#         puts "[#{Time.now}] #{context.user.raw_did}: #{i.type} #{i.item}"
+#       end
+#     end
+#   end
+#
+
 module BlueFactory
+
+  # The collection NSID of a Bluesky feed generator service.
   FEED_GENERATOR_TYPE = 'app.bsky.feed.generator'
+
+  # Maximum allowed value for the limit parameter in `getFeedSkeleton`.
+  MAX_LIMIT = 100
+
+  # Default value for the limit parameter in `getFeedSkeleton`. This value isn't used by the library
+  # (if no limit parameter is passed, it isn't added), but you can use it as a fallback in your code.
+  DEFAULT_LIMIT = 50
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: blue_factory
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Kuba Suder
@@ -9,6 +9,20 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
 - !ruby/object:Gem::Dependency
   name: sinatra
   requirement: !ruby/object:Gem::Requirement
@@ -46,6 +60,7 @@ files:
 - lib/blue_factory.rb
 - lib/blue_factory/configuration.rb
 - lib/blue_factory/errors.rb
+- lib/blue_factory/feed_handler.rb
 - lib/blue_factory/interaction.rb
 - lib/blue_factory/modules/configurable.rb
 - lib/blue_factory/modules/feeds.rb
@@ -59,13 +74,13 @@ files:
 - lib/blue_factory/user_info.rb
 - lib/blue_factory/version.rb
 - sig/blue_factory.rbs
-homepage: https://github.com/mackuba/blue_factory
+homepage: https://ruby.sdk.blue
 licenses:
 - Zlib
 metadata:
-  bug_tracker_uri: https://github.com/mackuba/blue_factory/issues
-  changelog_uri: https://github.com/mackuba/blue_factory/blob/master/CHANGELOG.md
-  source_code_uri: https://github.com/mackuba/blue_factory
+  bug_tracker_uri: https://tangled.org/mackuba.eu/blue_factory/issues
+  changelog_uri: https://tangled.org/mackuba.eu/blue_factory/blob/master/CHANGELOG.md
+  source_code_uri: https://tangled.org/mackuba.eu/blue_factory
 rdoc_options: []
 require_paths:
 - lib
@@ -80,7 +95,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: A Ruby gem for hosting custom feeds for Bluesky
 test_files: []