petail 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e974c64e0259b3561130ac6d4ea4a7bae80fa381e9ab7ee7cb3ab0338d9fe2c4
-  data.tar.gz: 6e99b146485fd8da57711ed81512ee599b10797fbc5cfb2072941927f78bd640
+  metadata.gz: 417bd45430e7d40be79470dcd1a09f6fbab6ca729a893c02568f944b67592cd5
+  data.tar.gz: 328809222adc5db346e50b7b144a98c3fd4c0f6e32fef701ee03f7d65a33b210
 SHA512:
-  metadata.gz: 4f6aa6a580106976c75f5f7db20362ffad7be1c6d25c1c55ed19dafe8c7ea7b50387213dcac51395d8cb9f6fe9aa5160bd1879fb20b9cbde9b48dedfdbe63822
-  data.tar.gz: a51c4609448bc36218c226c4f71a1b3fd99d46d4d16c666c4b009d76f1020ec2ee2634f156fbbaecd6012c9f4149409d45d44d00e378e5ecbc1eef1037db9bb9
+  metadata.gz: c01be4f0f48a6b5f9b4622b8f133102a8cc0abe073c9176827748b8848f1208c7682590fd52ae0734a696e6cd2fa3d5beb7fc338fc520bc7afaef9cb55eb9a9c
+  data.tar.gz: 1c684b3c8e69e3a9c54b627226e2c3ebdecafe1cf013b70f69ac0c6582a5ff4394e201ece321eee3e1115b7fa8573e7d234edc97e20c5b609a770b05cdcc7fad

data/README.adoc

@@ -86,6 +86,17 @@ payload.to_xml
 
 💡 You can also use `Petail.new` to create instances if you don't like `Petail.[]`, as shown above, but `.[]` is preferred.
 
+=== Members
+
+As briefly shown above, the minimum members (attributes) that make up problem details are:
+
+* `type` (optional): The full (or relative) URI that links to additional documentation. Default: `"about:blank"`.
+* `status` (optional): The link:https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status[HTTP status code] (or symbol) that must match your HTTP status code. Default: `nil`.
+* `title` (optional): The HTTP status label that must match your HTTP status code label. Default: HTTP status label (dynamically computed based on code unless overwritten).
+* `detail` (optional): The human readable reason for the error (should not include debugging information). Default: `nil`.
+* `instance` (optional): The full (or relative) URI that represents the cause of the error. Default: `nil`.
+* `extensions` (optional): A free form hash of additional details. Default: `{}`.
+
 === Media Types
 
 For convenience, you can obtain the necessary media types for your HTTP headers as follows:
@@ -170,7 +181,7 @@ Both serialization and deserialization of JSON is supported. For example, given
 [source,ruby]
 ----
 payload = Petail[
-  type: "https://test.io/problem_details/out_of_credit",
+  type: "https://demo.io/problem_details/out_of_credit",
   title: "You do not have enough credit.",
   status: 403,
   detail: "Your current balance is 30, but that costs 50.",
@@ -187,22 +198,20 @@ This means you can serialize as follows:
 [source,ruby]
 ----
 payload.to_json
-# {"type":"https://test.io/problem_details/out_of_credit","title":"You do not have enough credit.","status":403,"detail":"Your current balance is 30, but that costs 50.","instance":"/accounts/1","extensions":{"balance":30,"accounts":["/accounts/1","/accounts/10"]}}
+# "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
 
 payload.to_json indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"
 # {
-#   "type": "https://test.io/problem_details/out_of_credit",
+#   "type": "https://demo.io/problem_details/out_of_credit",
 #   "title": "You do not have enough credit.",
 #   "status": 403,
 #   "detail": "Your current balance is 30, but that costs 50.",
 #   "instance": "/accounts/1",
-#   "extensions": {
-#     "balance": 30,
-#     "accounts": [
-#       "/accounts/1",
-#       "/accounts/10"
-#     ]
-#   }
+#   "balance": 30,
+#   "accounts": [
+#     "/accounts/1",
+#     "/accounts/10"
+#   ]
 # }
 ----
 
@@ -212,7 +221,7 @@ You can also deserialize by taking the result of the above and turning the raw J
 
 [source,ruby]
 ----
-Petail.from_json "{\"type\":\"https://test.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"extensions\":{\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}}"
+Petail.from_json "{\"type\":\"https://demo.io/problem_details/out_of_credit\",\"title\":\"You do not have enough credit.\",\"status\":403,\"detail\":\"Your current balance is 30, but that costs 50.\",\"instance\":\"/accounts/1\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
 
 # #<Struct:Petail::Payload:0x00007670
 #   detail = "Your current balance is 30, but that costs 50.",
@@ -226,7 +235,7 @@ Petail.from_json "{\"type\":\"https://test.io/problem_details/out_of_credit\",\"
 #   instance = "/accounts/1",
 #   status = 403,
 #   title = "You do not have enough credit.",
-#   type = "https://test.io/problem_details/out_of_credit"
+#   type = "https://demo.io/problem_details/out_of_credit"
 # >
 ----
 
@@ -237,7 +246,7 @@ XML is supported too but isn't as robust as JSON support, at the moment. This is
 [source,ruby]
 ----
 payload = Petail[
-  type: "https://test.io/problem_details/out_of_credit",
+  type: "https://demo.io/problem_details/out_of_credit",
   title: "You do not have enough credit.",
   status: 403,
   detail: "Your current balance is 30, but that costs 50.",
@@ -254,13 +263,13 @@ This means you can serialize as follows:
 [source,ruby]
 ----
 payload.to_xml
-# "<?xml version='1.0' encoding='UTF-8'?><problem xmlns='urn:ietf:rfc:7807'><type>https://test.io/problem_details/out_of_credit</type><title>You do not have enough credit.</title><status>403</status><detail>Your current balance is 30, but that costs 50.</detail><instance>/accounts/1</instance><balance>30</balance><accounts><i>/accounts/1</i><i>/accounts/10</i></accounts></problem>"
+# "<?xml version='1.0' encoding='UTF-8'?><problem xmlns='urn:ietf:rfc:7807'><type>https://demo.io/problem_details/out_of_credit</type><title>You do not have enough credit.</title><status>403</status><detail>Your current balance is 30, but that costs 50.</detail><instance>/accounts/1</instance><balance>30</balance><accounts><i>/accounts/1</i><i>/accounts/10</i></accounts></problem>"
 
 payload.to_xml indent: 2
 # <?xml version='1.0' encoding='UTF-8'?>
 # <problem xmlns='urn:ietf:rfc:7807'>
 #   <type>
-#     https://test.io/problem_details/out_of_credit
+#     https://demo.io/problem_details/out_of_credit
 #   </type>
 #   <title>
 #     You do not have enough credit.
@@ -297,7 +306,7 @@ You can also deserialize by taking the result of the above and turning the raw J
 payload = Petail.from_xml <<~XML
   <?xml version='1.0' encoding='UTF-8'?>
   <problem xmlns='urn:ietf:rfc:7807'>
-    <type>https://test.io/problem_details/out_of_credit</type>
+    <type>https://demo.io/problem_details/out_of_credit</type>
     <title>You do not have enough credit.</title>
     <status>403</status>
     <detail>Your current balance is 30, but that costs 50.</detail>
@@ -322,10 +331,75 @@ XML
 #   instance = "/accounts/1",
 #   status = 403,
 #   title = "You do not have enough credit.",
-#   type = "https://test.io/problem_details/out_of_credit"
+#   type = "https://demo.io/problem_details/out_of_credit"
 # >
 ----
 
+=== Examples
+
+There is a lot of useful information you can provide in your problem details depending on the context you are working in. Some have been shown above but here's a few more that might be of interest.
+
+==== HATEOAS
+
+With link:https://nordicapis.com/tools-to-make-hateoas-compliance-easier[HATEOAS], you can provide additional information and links for which the client can understand what next actions are available. The below example shows how you can provide additional resources for clients to adjust accordingly:
+
+[source,ruby]
+----
+Petail[
+  type: "https://demo.io/problem_details/rate_limit",
+  title: "Rate limit exceeded",
+  status: 429,
+  detail: "You have exceeded your rate limit of 150 requests per minute",
+  instance: "/articles",
+  extensions: {
+    retry_after: 5,
+    links: [
+      {
+        ref: "self",
+        href: "/articles"
+      },
+      {
+        rel: "retry",
+        href: "/articles",
+        title: "Retry after five minutes"
+      },
+      {
+        rel: "status",
+        href: "/statuses/rate_limit",
+        title: "Check current rate limit usage"
+      }
+    ]
+  }
+]
+----
+
+==== Semantic Structure
+
+In other situations, you might need a different structure in order to aid clients that might be AI driven which needs a semantically structured response in order to course correct. Example:
+
+[source,ruby]
+----
+Petail[
+  type: "https://demo.io/problem_details/invalid_field",
+  title: "Invalid field value",
+  status: 400,
+  detail: "The category requested doesn't exist",
+  instance: "/categories",
+  extensions: {
+    parameters: {
+      category_id: 123
+    },
+    suggestions: [
+      "ruby",
+      "git",
+      "htmx"
+    ]
+  }
+]
+----
+
+With the above, the client now knows what parameters where invalid along with relevant suggestions for proceeding. Even better, the suggestions implicitly show the types of IDs that are required.
+
 == Development
 
 To contribute, run:
@@ -353,6 +427,13 @@ To test, run:
 bin/rake
 ----
 
+== Resources
+
+You can find additional resources here:
+
+* link:https://www.iana.org/assignments/http-problem-types/http-problem-types.xhtml[IANA Hypertext Transfer Protocol (HTTP) Problem Types]: A registered list of problem types you can use.
+* link:https://github.com/protocol-registries/http-problem-types[HTTP Problem Type Registration Requests]: Where you can register new problem types.
+
 == link:https://alchemists.io/policies/license[License]
 
 == link:https://alchemists.io/policies/security[Security]

data/lib/petail/payload.rb

@@ -5,8 +5,10 @@ require "rack/utils"
 require "rexml"
 
 module Petail
+  PRIMARY_KEYS = %i[type title status detail instance].freeze
+
   # Models the problem details response payload.
-  Payload = Struct.new :type, :title, :status, :detail, :instance, :extensions do
+  Payload = Struct.new(*PRIMARY_KEYS, :extensions) do
     def self.for(**attributes)
       status = attributes.delete(:status).then { Rack::Utils.status_code it if it }
       title = attributes.delete(:title).then { it || Rack::Utils::HTTP_STATUS_CODES[status] }
@@ -14,18 +16,23 @@ module Petail
       new title:, status:, **attributes
     end
 
-    def self.from_json(body) = self.for(**JSON(body, symbolize_names: true))
+    def self.from_json body
+      attributes = JSON body, symbolize_names: true
+      extensions = attributes.reject { |key| PRIMARY_KEYS.include? key }
+
+      self.for(**attributes.slice(*PRIMARY_KEYS), extensions:)
+    end
 
     # :reek:TooManyStatements
     def self.from_xml body, deserializer: XML::Deserializer
       elements = REXML::Document.new(body).root.elements
 
       attributes = elements.each_with_object({extensions: {}}) do |element, collection|
-        name = element.name
+        name = element.name.to_sym
         text = element.text
 
         case name
-          when "type", "title", "detail", "instance", "status" then collection[name.to_sym] = text
+          when *PRIMARY_KEYS then collection[name] = text
           else collection[:extensions].merge! deserializer.call(element)
         end
       end
@@ -48,11 +55,12 @@ module Petail
 
     def extension?(name) = extensions.key? name
 
-    def to_h = super.compact.tap { it.delete :extensions if extensions.empty? }
+    def to_h = {type:, title:, status:, detail:, instance:, **extensions}.compact
 
     def to_json(*) = to_h.to_json(*)
 
     # :reek:TooManyStatements
+    # :reek:FeatureEnvy
     def to_xml(serializer: XML::Serializer, **options)
       document = REXML::Document.new
       document.add REXML::XMLDecl.new("1.0", "UTF-8")
@@ -60,9 +68,7 @@ module Petail
       problem = REXML::Element.new("problem").add_namespace("urn:ietf:rfc:7807")
       document.add problem
 
-      attributes = to_h
-      attributes.merge! attributes.delete :extensions if extensions.any?
-      attributes.each { |name, value| serializer.call name, value, problem }
+      to_h.each { |name, value| serializer.call name, value, problem }
 
       "".dup.tap { document.write(**options, output: it) }
     end

data/petail.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "petail"
-  spec.version = "0.3.0"
+  spec.version = "0.5.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/petail"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: petail
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -109,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 3.7.1
 specification_version: 4
 summary: A RFC 9457 Problem Details for HTTP APIs implementation.
 test_files: []