Skip to content

Commit

Permalink
Fix hmac_paths documentation
Browse files Browse the repository at this point in the history
Fix a typo, and use 2 spaces before code examples.
  • Loading branch information
jeremyevans committed Apr 11, 2024
1 parent cd7caf3 commit 0a2e9fc
Showing 1 changed file with 16 additions and 16 deletions.
32 changes: 16 additions & 16 deletions lib/roda/plugins/hmac_paths.rb
Original file line number Diff line number Diff line change
Expand Up @@ -14,12 +14,12 @@ module RodaPlugins
# protection against users who know the secret value. The secret must be at least
# 32 bytes.
#
# plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes'
# plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes'
#
# To generate a valid HMAC path, you call the +hmac_path+ method:
#
# hmac_path('/widget/1')
# # => "/0c2feaefdfc80cc73da19b060c713d4193c57022815238c6657ce2d99b5925eb/0/widget/1"
# hmac_path('/widget/1')
# # => "/0c2feaefdfc80cc73da19b060c713d4193c57022815238c6657ce2d99b5925eb/0/widget/1"
#
# The first segment in the returned path is the HMAC. The second segment is flags for
# the type of paths (see below), and the rest of the path is as given.
Expand Down Expand Up @@ -74,11 +74,11 @@ module RodaPlugins
# a foobar with the same ID. When generating HMAC paths where the matching +r.hmac_path+
# call is not at the root of the routing tree, you must pass the +:root+ option:
#
# hmac_path('/1', root: '/widget')
# # => "/widget/daccafce3ce0df52e5ce774626779eaa7286085fcbde1e4681c74175ff0bbacd/0/1"
# hmac_path('/1', root: '/widget')
# # => "/widget/daccafce3ce0df52e5ce774626779eaa7286085fcbde1e4681c74175ff0bbacd/0/1"
#
# hmac_path('/1', root: '/foobar')
# # => "/foobar/c5fdaf482771d4f9f38cc13a1b2832929026a4ceb05e98ed6a0cd5a00bf180b7/0/1"
# hmac_path('/1', root: '/foobar')
# # => "/foobar/c5fdaf482771d4f9f38cc13a1b2832929026a4ceb05e98ed6a0cd5a00bf180b7/0/1"
#
# Note how the HMAC changes even though the path is the same.
#
Expand All @@ -88,8 +88,8 @@ module RodaPlugins
# The +:method+ option creates a path that can only be called with a certain request
# method:
#
# hmac_path('/widget/1', method: :get)
# # => "/d38c1e634ecf9a3c0ab9d0832555b035d91b35069efcbf2670b0dfefd4b62fdd/m/widget/1"
# hmac_path('/widget/1', method: :get)
# # => "/d38c1e634ecf9a3c0ab9d0832555b035d91b35069efcbf2670b0dfefd4b62fdd/m/widget/1"
#
# Note how this results in a different HMAC than the original <tt>hmac_path('/widget/1')</tt>
# call. This sets the flags segment to +m+, which means +r.hmac_path+ will consider the
Expand All @@ -103,28 +103,28 @@ module RodaPlugins
# means +r.hmac_path+ will check for that exact query string. Requests with an empty query
# string or a different string will not match.
#
# hmac_path('/widget/1', params: {foo: 'bar'})
# # => "/fe8d03f9572d5af6c2866295bd3c12c2ea11d290b1cbd016c3b68ee36a678139/p/widget/1?foo=bar"
# hmac_path('/widget/1', params: {foo: 'bar'})
# # => "/fe8d03f9572d5af6c2866295bd3c12c2ea11d290b1cbd016c3b68ee36a678139/p/widget/1?foo=bar"
#
# For GET requests, which cannot have request bodies, that is sufficient to ensure that the
# submitted params are exactly as specified. However, POST requests can have request bodies,
# and request body params override query string params in +r.params+. So if you are using
# this for POST requests (or other HTTP verbs that can have request bodies), use +r.GET+
# instead of +r.params+ to specificly check query string parameters.
# instead of +r.params+ to specifically check query string parameters.
#
# You can use +:root+, +:method+, and +:params+ at the same time:
#
# hmac_path('/1', root: '/widget', method: :get, params: {foo: 'bar'})
# # => "/widget/9169af1b8f40c62a1c2bb15b1b377c65bda681b8efded0e613a4176387468c15/mp/1?foo=bar"
# hmac_path('/1', root: '/widget', method: :get, params: {foo: 'bar'})
# # => "/widget/9169af1b8f40c62a1c2bb15b1b377c65bda681b8efded0e613a4176387468c15/mp/1?foo=bar"
#
# This gives you a path only valid for a GET request with a root of <tt>/widget</tt> and
# a query string of <tt>foo=bar</tt>.
#
# To handle secret rotation, you can provide an +:old_secret+ option when loading the
# plugin.
#
# plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes',
# old_secret: 'previous-secret-value-with-at-least-32-bytes'
# plugin :hmac_paths, secret: 'some-secret-value-with-at-least-32-bytes',
# old_secret: 'previous-secret-value-with-at-least-32-bytes'
#
# This will use +:secret+ for constructing new paths, but will respect paths generated by
# +:old_secret+.
Expand Down

0 comments on commit 0a2e9fc

Please sign in to comment.