petail 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e974c64e0259b3561130ac6d4ea4a7bae80fa381e9ab7ee7cb3ab0338d9fe2c4
-  data.tar.gz: 6e99b146485fd8da57711ed81512ee599b10797fbc5cfb2072941927f78bd640
+  metadata.gz: 90ccb34a36bfc17201ce4b4881e8f37acbbc3714f076c5de0e7cf1d5ad373346
+  data.tar.gz: 0a2ee99b2cd3191aa9ec08473a218436bd259576f3b0e6e31c8779eddcbfe5b0
 SHA512:
-  metadata.gz: 4f6aa6a580106976c75f5f7db20362ffad7be1c6d25c1c55ed19dafe8c7ea7b50387213dcac51395d8cb9f6fe9aa5160bd1879fb20b9cbde9b48dedfdbe63822
-  data.tar.gz: a51c4609448bc36218c226c4f71a1b3fd99d46d4d16c666c4b009d76f1020ec2ee2634f156fbbaecd6012c9f4149409d45d44d00e378e5ecbc1eef1037db9bb9
+  metadata.gz: b663a7f90af61259298cd14a8f23c63afbd0d0e6aab80c3c38c0242e7cc240418563021623bcf95e7af88e3368788bdad8ac30178431788f4cc3e552219815b7
+  data.tar.gz: 6efc822522e3e828df9c2d81953a8b2a2344e6ec9aec462ebe063cb32feffcc10552b4f874b67888d3e347875a805621df317b429d2a57227ecb55e061530611

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:
@@ -187,7 +198,7 @@ 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://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\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
 
 payload.to_json indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"
 # {
@@ -196,13 +207,11 @@ payload.to_json indent: "  ", space: " ", object_nl: "\n", array_nl: "\n"
 #   "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://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\",\"balance\":30,\"accounts\":[\"/accounts/1\",\"/accounts/10\"]}"
 
 # #<Struct:Petail::Payload:0x00007670
 #   detail = "Your current balance is 30, but that costs 50.",
@@ -353,6 +362,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.4.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.4.0
 platform: ruby
 authors:
 - Brooke Kuhlmann