petail 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f8b4586f6ff3956d439fa35a0aaa64753b3839261a55df4cc9ce83b0bbdd277f
-  data.tar.gz: 4b20c15bc80355c4d55dd83d365ca3ed8806775385623b005e53aaa61cf9b260
+  metadata.gz: 90ccb34a36bfc17201ce4b4881e8f37acbbc3714f076c5de0e7cf1d5ad373346
+  data.tar.gz: 0a2ee99b2cd3191aa9ec08473a218436bd259576f3b0e6e31c8779eddcbfe5b0
 SHA512:
-  metadata.gz: 1e7a2e97589c26880828fda50953a8cf542b0eb6c1c285bed3e4889d091c8486a5c1e6998e5efae59dc0a5a013e3f30859366d08773155cc3ae96c95beffdbd1
-  data.tar.gz: 8f69aaadab1e77609b51824528b22e896c6e3c5a7c3b963e9fadd7edb098f232ba6f1cc64f07a3fcf746c0a9e1e16173a5e5bd8dfd7b059fc179e67786f4d608
+  metadata.gz: b663a7f90af61259298cd14a8f23c63afbd0d0e6aab80c3c38c0242e7cc240418563021623bcf95e7af88e3368788bdad8ac30178431788f4cc3e552219815b7
+  data.tar.gz: 6efc822522e3e828df9c2d81953a8b2a2344e6ec9aec462ebe063cb32feffcc10552b4f874b67888d3e347875a805621df317b429d2a57227ecb55e061530611

data/README.adoc

@@ -55,10 +55,12 @@ The quickest way to get started is to create a new instance and then cast as JSO
 
 [source,ruby]
 ----
-payload = Petail.new type: "https://demo.io/problem_details/timeout",
-                     status: 413,
-                     detail: "You've exceeded the 5MB upload limit.",
-                     instance: "/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3"
+payload = Petail[
+  type: "https://demo.io/problem_details/timeout",
+  status: 413,
+  detail: "You've exceeded the 5MB upload limit.",
+  instance: "/profile/3a1bfd54-ae6c-4a61-8d0d-90c132428dc3"
+]
 
 payload.to_json
 
@@ -82,6 +84,19 @@ payload.to_xml
 # </problem>
 ----
 
+💡 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:
@@ -97,11 +112,11 @@ Petail.media_type_for :xml   # "application/problem+xml"
 
 === Payload
 
-You'll always get a `Petail::Payload` object answered back when using `Petail.new` for which you can cast to JSON, XML, and other types. There are few conveniences provided for you when constructing a new payload. For instance, you can also use status to set default title:
+You'll always get a `Petail::Payload` object answered back when using `Petail.[]` or `Petail.new` for which you can cast to JSON, XML, and other types. There are few conveniences provided for you when constructing a new payload. For instance, you can also use status to set default title:
 
 [source,ruby]
 ----
-Petail.new status: 413
+Petail[status: 413]
 # #<Struct:Petail::Payload:0x0000ec80
 #   detail = nil,
 #   extensions = {},
@@ -116,7 +131,7 @@ Notice that standard HTTP 413 title of "Content Too Large" is provided for you b
 
 [source,ruby]
 ----
-Petail.new status: :bad_request
+Petail[status: :bad_request]
 # #<Struct:Petail::Payload:0x0000f280
 #   detail = nil,
 #   extensions = {},
@@ -133,7 +148,7 @@ Due to the payload being a `Struct`, you have all of the standard methods availa
 
 [source,]
 ----
-payload = Petail.new status: :forbidden
+payload = Petail[status: :forbidden]
 
 payload.add_extension(:account, "/accounts/1")
        .add_extension(:balance, 50)
@@ -165,7 +180,7 @@ Both serialization and deserialization of JSON is supported. For example, given
 
 [source,ruby]
 ----
-payload = Petail.new(
+payload = Petail[
   type: "https://test.io/problem_details/out_of_credit",
   title: "You do not have enough credit.",
   status: 403,
@@ -175,7 +190,7 @@ payload = Petail.new(
     balance: 30,
     accounts: %w[/accounts/1 /accounts/10]
   }
-)
+]
 ----
 
 This means you can serialize as follows:
@@ -183,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"
 # {
@@ -192,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"
+#   ]
 # }
 ----
 
@@ -208,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.",
@@ -232,7 +245,7 @@ XML is supported too but isn't as robust as JSON support, at the moment. This is
 
 [source,ruby]
 ----
-payload = Petail.new(
+payload = Petail[
   type: "https://test.io/problem_details/out_of_credit",
   title: "You do not have enough credit.",
   status: 403,
@@ -242,7 +255,7 @@ payload = Petail.new(
     balance: 30,
     accounts: %w[/accounts/1 /accounts/10]
   }
-)
+]
 ----
 
 This means you can serialize as follows:
@@ -349,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/lib/petail.rb

@@ -10,6 +10,10 @@ module Petail
   MEDIA_TYPE_XML = "application/problem+xml"
   TYPES = %i[json xml].freeze
 
+  def self.[](**) = Payload.for(**)
+
+  def self.new(**) = Payload.for(**)
+
   def self.from_json(...) = Payload.from_json(...)
 
   def self.from_xml(...) = Payload.from_xml(...)
@@ -17,6 +21,4 @@ module Petail
   def self.media_type_for key, types: TYPES
     types.include?(key) ? const_get("MEDIA_TYPE_#{key.upcase}") : ""
   end
-
-  def self.new(**) = Payload.for(**)
 end

data/petail.gemspec

@@ -2,7 +2,7 @@
 
 Gem::Specification.new do |spec|
   spec.name = "petail"
-  spec.version = "0.2.0"
+  spec.version = "0.4.0"
   spec.authors = ["Brooke Kuhlmann"]
   spec.email = ["brooke@alchemists.io"]
   spec.homepage = "https://alchemists.io/projects/petail"
@@ -24,6 +24,7 @@ Gem::Specification.new do |spec|
 
   spec.required_ruby_version = "~> 3.4"
   spec.add_dependency "rack", ">= 2.2", "< 4.0"
+  spec.add_dependency "rexml", "~> 3.4"
 
   spec.extra_rdoc_files = Dir["README*", "LICENSE*"]
   spec.files = Dir["*.gemspec", "lib/**/*"]

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: petail
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Brooke Kuhlmann
@@ -55,6 +55,20 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '4.0'
+- !ruby/object:Gem::Dependency
+  name: rexml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.4'
 email:
 - brooke@alchemists.io
 executables: []
@@ -95,7 +109,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.9
 specification_version: 4
 summary: A RFC 9457 Problem Details for HTTP APIs implementation.
 test_files: []