liberty 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cd2f5e057e9a8a59d5fd94c67b47972793d0662a010e06a824271a9717dc1af
-  data.tar.gz: 2a03907e15c4100c6dbff7d6d4af219c00d72e94d91ab4c1bdf31cb32b6f0ca8
+  metadata.gz: 9450a8fadf0c6726d4249f2b6a62f4918045795f199be8ec8bec29412bbaebc1
+  data.tar.gz: 55ea606054dabaeec94add7f6b5fe63a5d38add6eca13dc9f4fc1ef2754ad5c2
 SHA512:
-  metadata.gz: 85adf8822f586339d802a8389d48babd728fb522d3df1c2c6bd3383b36ab5f4d2bf395cd6f6ffb01b20a6ddffa083e6757bad0f4203fcd51f40c3f77a37124a3
-  data.tar.gz: 4fb75c34eb3382e668b63b4ea12dfc5d35de40fc7d1734fa2d89023c0ec3ad9c9ea6fb38153aa952d016cdcad05153bd4c3dfa2df276e7fd6da352afc2fe8f78
+  metadata.gz: 17e9cd7824c5b5038daee7fd5d3d441886865dc78562797cd502b8f96f6fd9cd48b2ed92da934265321757a2237e3682092e8653b1b4370260d73b3d9caef253
+  data.tar.gz: 7416e1f47f06cb05dd7fbaadc777f71bbac9bc828a5954f4db401c52e42abc88777ee3fd49ad1e24e22e412953e7d2b188b2a6983b153ea36f535f02a5f7d48c

data/.qlty/.gitignore

@@ -0,0 +1,7 @@
+*
+!configs
+!configs/**
+!hooks
+!hooks/**
+!qlty.toml
+!.gitignore

data/.qlty/qlty.toml

@@ -0,0 +1,81 @@
+# This file was automatically generated by `qlty init`.
+# You can modify it to suit your needs.
+# We recommend you to commit this file to your repository.
+#
+# This configuration is used by both Qlty CLI and Qlty Cloud.
+#
+#     Qlty CLI -- Code quality toolkit for developers
+#     Qlty Cloud -- Fully automated Code Health Platform
+#
+# Try Qlty Cloud: https://qlty.sh
+#
+# For a guide to configuration, visit https://qlty.sh/d/config
+# Or for a full reference, visit https://qlty.sh/d/qlty-toml
+config_version = "0"
+
+exclude_patterns = [
+  "*_min.*",
+  "*-min.*",
+  "*.min.*",
+  "**/.yarn/**",
+  "**/*.d.ts",
+  "**/assets/**",
+  "**/bower_components/**",
+  "**/build/**",
+  "**/cache/**",
+  "**/config/**",
+  "**/db/**",
+  "**/deps/**",
+  "**/dist/**",
+  "**/extern/**",
+  "**/external/**",
+  "**/generated/**",
+  "**/Godeps/**",
+  "**/gradlew/**",
+  "**/mvnw/**",
+  "**/node_modules/**",
+  "**/protos/**",
+  "**/seed/**",
+  "**/target/**",
+  "**/templates/**",
+  "**/testdata/**",
+  "**/vendor/**",
+]
+
+test_patterns = [
+  "**/test/**",
+  "**/spec/**",
+  "**/*.test.*",
+  "**/*.spec.*",
+  "**/*_test.*",
+  "**/*_spec.*",
+  "**/test_*.*",
+  "**/spec_*.*",
+]
+
+[smells]
+mode = "comment"
+
+[[source]]
+name = "default"
+default = true
+
+
+[[plugin]]
+name = "actionlint"
+
+[[plugin]]
+name = "osv-scanner"
+
+[[plugin]]
+name = "ripgrep"
+mode = "comment"
+
+[[plugin]]
+name = "standardrb"
+
+[[plugin]]
+name = "trufflehog"
+
+[[plugin]]
+name = "zizmor"

data/CHANGELOG.md

@@ -1,3 +1,28 @@
+## [0.4.0] - 2026-09-15
+
+### Breaking changes
+
+- Endpoints now offer `authenticated?` and `authorized?` hooks for plugging in your own auth handlers. Both default to `false` to prevent endpoints from being exposed accidentally, so every existing endpoint responds with a 401 until it overrides them. Applications upgrading from older versions must override these methods, either to return `true` or with code that handles auth.
+
+### Added
+
+- Responds with `401 Authentication required` when `authenticated?` returns `false`, and with `403 Forbidden` when `authorized?` returns `false`. The endpoint's status, headers, and content are only consulted when both return `true`.
+- Adds a `www_authenticate_header` hook to endpoints. When it returns a challenge, such as `Bearer realm="api"`, 401 responses include it as the `WWW-Authenticate` header. It defaults to `nil`, which omits the header.
+- Exposes the request's `Authorization` header as `request.headers[:authorization]` so endpoints can read credentials.
+- Responds to `HEAD` requests that fail auth with an empty body and a `content-length` header, as the Rack specification requires.
+
+## [0.3.1] - 2026-09-07
+
+### Fixed
+
+- Responds to `HEAD` requests with an empty body, as the Rack specification requires. Status and headers, including `content-length`, still describe what the matching `GET` would return.
+- Responds to `HEAD` requests for unknown routes with a 404 and an empty body.
+- Builds the 404 response per request instead of reusing a frozen constant, which Rack::Lint rejects.
+
+### Changed
+
+- Adds `qlty` and `flog` tasks to the default Rake task, alongside `spec` and `standard`.
+
 ## [0.3.0] - 2026-09-06
 
 ### Breaking changes

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    liberty (0.3.0)
+    liberty (0.4.0)
       json (~> 2.3)
       mustermann (~> 4.0)
       mustermann-contrib (~> 4.0)

data/README.md

@@ -50,6 +50,14 @@ Here's an example for an HTTP get to the `/hello` route, which returns a hello w
 class MyEndpoint < Liberty::Endpoint
   responds_to :get, '/hello'
 
+  def authenticated?
+    true
+  end
+
+  def authorized?
+    true
+  end
+
   def status
     200
   end
@@ -83,6 +91,49 @@ end
 If you configure your CORS headers before you launch your application, `Endpoints` will
 automatically respond with the right headers.
 
+### Authentication & Authorization
+
+Every `Endpoint` has two hooks: `#authenticated?` and `#authorized?`. Both default to `false`,
+so an endpoint that does not implement them responds with `401 Authentication required`. Override
+them to plug in your own auth. Liberty checks `#authenticated?` first and responds with a 401 when
+it returns `false`. It then checks `#authorized?` and responds with `403 Forbidden` when that
+returns `false`. Your endpoint's status, headers, and content are only consulted when both return
+`true`. The raw `Authorization` header is available as `request.headers[:authorization]`.
+
+A 401 response should tell the client how to authenticate. Override `#www_authenticate_header`
+to return the challenge, such as `Bearer realm="api"`, and Liberty adds it as the
+`WWW-Authenticate` header on 401 responses. When it returns `nil` the header is omitted.
+
+Here's an example of how to use `#authenticated?` and `#authorized?`:
+
+```ruby
+class YourEndpoint < Liberty::Endpoint
+  responds_to :get, "/your_endpoint"
+
+  def authenticated?
+    !current_user.nil?
+  end
+
+  def www_authenticate_header
+    'Bearer realm="api"'
+  end
+
+  def authorized?
+    current_user.admin?
+  end
+
+  def current_user
+    @current_user ||= Sessions.find_by_token(bearer_token)
+  end
+
+  private
+
+  def bearer_token
+    request.headers[:authorization].to_s.delete_prefix("Bearer ")
+  end
+end
+```
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:

data/Rakefile

@@ -7,4 +7,25 @@ RSpec::Core::RakeTask.new(:spec)
 
 require "standard/rake"
 
-task default: %i[spec standard]
+FLOG_LIMIT = 10.0
+
+def qlty_bin
+  installed = File.expand_path("~/.qlty/bin/qlty")
+  ENV.fetch("QLTY_BIN") { File.exist?(installed) ? installed : "qlty" }
+end
+
+desc "Run qlty lint checks and report code smells"
+task :qlty do
+  sh qlty_bin, "check", "--all", "--no-progress"
+  sh qlty_bin, "smells", "--all", "--quiet"
+end
+
+desc "Fail when the average flog score per method reaches #{FLOG_LIMIT}"
+task :flog do
+  report = `bundle exec flog -m lib`
+  puts report
+  average = report[/^\s*([\d.]+): flog\/method average/, 1].to_f
+  abort("Quality gate failed: average flog #{average} is #{FLOG_LIMIT} or higher") if average >= FLOG_LIMIT
+end
+
+task default: %i[spec standard qlty flog]

data/lib/liberty/adapters/error_response.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Liberty
+  module Adapters
+    class ErrorResponse
+      attr_reader :endpoint
+
+      def initialize(endpoint)
+        @endpoint = endpoint
+      end
+
+      def to_rack_response
+        [status, headers, rack_body]
+      end
+
+      private
+
+      def headers
+        {
+          Response::CONTENT_LENGTH => body.bytesize.to_s,
+          Response::CONTENT_TYPE => Response::MIME_TYPE_TEXT
+        }
+      end
+
+      def rack_body
+        endpoint.request.head? ? [] : [body]
+      end
+    end
+  end
+end

data/lib/liberty/adapters/forbidden_response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative "error_response"
+
+module Liberty
+  module Adapters
+    class ForbiddenResponse < ErrorResponse
+      private
+
+      def status
+        403
+      end
+
+      def body
+        "Forbidden"
+      end
+    end
+  end
+end

data/lib/liberty/adapters/request.rb

@@ -7,6 +7,7 @@ module Liberty
     class Request
       PARSED_BODY = "parsed_body"
       ROUTER_PARAMS = "router.params"
+      AUTHORIZATION = "HTTP_AUTHORIZATION"
 
       attr_reader :env
 
@@ -15,18 +16,27 @@ module Liberty
       end
 
       def headers
-        @headers ||= env ? {
-          accept_media_types: accept_media_types,
-          preferred_media_type: preferred_media_type
-        } : {}
+        @headers ||= env ? env_headers : {}
       end
 
       def params
         @params ||= env ? all_params : {}
       end
 
+      def head?
+        env ? rack_request.head? : false
+      end
+
       private
 
+      def env_headers
+        {
+          accept_media_types: accept_media_types,
+          preferred_media_type: preferred_media_type,
+          authorization: env[AUTHORIZATION]
+        }
+      end
+
       def all_params
         form_params.merge!(body_params).merge!(url_params)
       end
@@ -69,7 +79,9 @@ module Liberty
       end
 
       def symbolize_keys(hash)
-        hash.each_with_object({}) { |(key, value), obj| obj[key.to_sym] = value }
+        hash.each_with_object({}) do |(key, value), obj|
+          obj[key.to_sym] = value
+        end
       end
 
       def rack_request

data/lib/liberty/adapters/response.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require_relative "forbidden_response"
+require_relative "unauthenticated_response"
+
 module Liberty
   module Adapters
     class Response
@@ -17,15 +20,34 @@ module Liberty
       end
 
       def to_rack_response
-        [status, headers, [content]]
+        return unauthenticated_response unless endpoint.authenticated?
+        return forbidden_response unless endpoint.authorized?
+
+        [status, headers, rack_body]
       end
 
       private
 
+      def unauthenticated_response
+        UnauthenticatedResponse.new(endpoint).to_rack_response
+      end
+
+      def forbidden_response
+        ForbiddenResponse.new(endpoint).to_rack_response
+      end
+
       def status
         endpoint.status
       end
 
+      def rack_body
+        head? ? [] : [content]
+      end
+
+      def head?
+        endpoint.request.head?
+      end
+
       def headers
         headers = {CONTENT_LENGTH => content_length}
         headers[CONTENT_TYPE] = content_type if content_type

data/lib/liberty/adapters/unauthenticated_response.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "error_response"
+
+module Liberty
+  module Adapters
+    class UnauthenticatedResponse < ErrorResponse
+      WWW_AUTHENTICATE = "www-authenticate"
+
+      private
+
+      def status
+        401
+      end
+
+      def headers
+        challenge ? super.merge(WWW_AUTHENTICATE => challenge) : super
+      end
+
+      def challenge
+        endpoint.www_authenticate_header
+      end
+
+      def body
+        "Authentication required"
+      end
+    end
+  end
+end

data/lib/liberty/endpoint.rb

@@ -22,6 +22,17 @@ module Liberty
       request.headers[:preferred_media_type]
     end
 
+    def authenticated?
+      false
+    end
+
+    def www_authenticate_header
+    end
+
+    def authorized?
+      false
+    end
+
     def status
       DEFAULT_STATUS
     end

data/lib/liberty/router.rb

@@ -15,7 +15,9 @@ module Liberty
     PATH_INFO = "PATH_INFO"
     ROUTER_PARAMS = "router.params"
     DYNAMIC_PREFIX = /:/
-    NOT_FOUND_RESPONSE = [404, {"content-length" => "9"}, ["Not Found"]].freeze
+    NOT_FOUND_STATUS = 404
+    NOT_FOUND_BODY = "Not Found"
+    CONTENT_LENGTH = "content-length"
 
     def initialize
       @apps = {}
@@ -46,7 +48,7 @@ module Liberty
 
     def call(env)
       endpoint = find_endpoint(env[REQUEST_METHOD], env[PATH_INFO]) { |params| env[ROUTER_PARAMS] = params }
-      endpoint ? endpoint.call(env) : NOT_FOUND_RESPONSE
+      endpoint ? endpoint.call(env) : not_found_response(env)
     end
 
     def print(stdout = $stdout)
@@ -55,6 +57,18 @@ module Liberty
 
     private
 
+    def not_found_response(env)
+      [NOT_FOUND_STATUS, not_found_headers, not_found_body(env)]
+    end
+
+    def not_found_headers
+      {CONTENT_LENGTH => NOT_FOUND_BODY.bytesize.to_s}
+    end
+
+    def not_found_body(env)
+      (env[REQUEST_METHOD] == HEAD) ? [] : [NOT_FOUND_BODY]
+    end
+
     def register_route(verb, path, to)
       dynamic?(path) ? register_dynamic_route(verb, path, to) : register_static_route(verb, path, to)
     end

data/lib/liberty/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Liberty
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: liberty
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alan Ridlehoover
@@ -102,6 +102,8 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ".qlty/.gitignore"
+- ".qlty/qlty.toml"
 - ".rspec"
 - ".ruby-version"
 - ".standard.yml"
@@ -114,11 +116,14 @@ files:
 - Rakefile
 - assets/liberty.png
 - lib/liberty.rb
+- lib/liberty/adapters/error_response.rb
+- lib/liberty/adapters/forbidden_response.rb
 - lib/liberty/adapters/parsers/factory.rb
 - lib/liberty/adapters/parsers/json.rb
 - lib/liberty/adapters/parsers/null.rb
 - lib/liberty/adapters/request.rb
 - lib/liberty/adapters/response.rb
+- lib/liberty/adapters/unauthenticated_response.rb
 - lib/liberty/application.rb
 - lib/liberty/cors.rb
 - lib/liberty/cors/middleware.rb