ruby-openid 2.0.4 → 2.1.2

data/CHANGELOG

@@ -1,41 +1,78 @@
-Tue Feb 12 18:02:31 PST 2008  Kevin Turner <kevin@janrain.com>
-  tagged 2.0.4
+Fri Jun 27 15:39:14 PDT 2008  Kevin Turner <kevin@janrain.com>
+  tagged 2.1.2
 
-Tue Feb 12 18:01:44 PST 2008  Kevin Turner <kevin@janrain.com>
-  * set version to 2.0.4
+Fri Jun 27 15:38:05 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * update version to 2.1.2
 
-Tue Feb 12 17:49:53 PST 2008  Kevin Turner <kevin@janrain.com>
-  * HTMLTokenizer: raise OpenIDError instead of RuntimeError
+Fri Jun 27 15:01:35 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * util: remove call to srand
+  
+  From the Ruby FAQ:
+  
+  9.2 How do random number seeds work?
+  
+  It depends. In Ruby versions prior to 1.5.2, the random number generator had
+  (by default) a constant seed, and so would produce the same series of numbers
+  each time a program was run. If you needed less deterministic behaviors, you
+  called srand to set up a less predictable seed.
+  
+  Newer Rubys (Rubies?) have a different behavior. If rand is called without a
+  prior call to srand, Ruby will generate its own random(ish) seed. Successive
+  runs of a program that does not use srand will generate different sequences of
+  random numbers. To get the old, predictable, behavior (perhaps for testing),
+  call srand with a constant seed. 
+
+Fri Jun 27 13:34:43 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * LICENSE: htmltokenizer is (c) 2004 Ben Giddings
+
+Fri Jun 27 13:32:09 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * Yadis.html_yadis_location: catch HTMLTokenizerError
 
-Thu Jan 31 11:34:11 PST 2008  Kevin Turner <kevin@janrain.com>
-  * Consumer.IdResHandler.verify_return_to_args: include more details in exception messages.
+Fri Jun 27 13:24:13 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * htmltokenizer: define HTMLTokenizerError to raise
 
-Mon Jan 21 15:50:54 PST 2008  Kevin Turner <kevin@janrain.com>
-  * StandardFetcher.fetch: catch more exceptions to wrap in to FetchingErrors.
+Fri Jun 27 13:18:38 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * htmltokenizer: Don't raise OpenIDError from htmltokenizer (it's not in the OpenID module namespace) #255
 
-Mon Jan 21 14:23:10 PST 2008  Kevin Turner <kevin@janrain.com>
-  * OpenID::normalize_url: urinorm raises URI::Error, not ArgumentError.
+Wed Jun 25 17:31:26 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * OpenID::Server::CheckIDRequest.answer: document return type
 
-Tue Jan 15 11:48:49 PST 2008  rubys@intertwingly.net
-  * The following set of changes gets ruby-openid to work with Ruby 1.9,
-  revision 15006 and REXML revision 1301.  The codebase with this
-  patch continues to work on Ruby 1.8.6.
+Wed Jun 25 17:06:35 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * TrustRoot.check_sanity: don't fail if the trust root is not parseable
 
-Mon Jan 14 18:06:29 PST 2008  Kevin Turner <kevin@janrain.com>
-  * Consumer.complete_id_res: catch all OpenIDError instead of just DiscoveryFailure and ProtocolError.  Fixes #104.
+Wed Jun 25 16:31:30 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * Message.from_http_response: accept 206 code
+
+Wed Jun 25 14:14:05 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * move OpenID::VERSION definition in openid.rb, for #256
+
+Wed Jun 25 13:55:18 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * Add admin/gettlds.py to ease updating of TLD list in trust root validation
+
+Wed Jun 25 13:50:22 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * TrustRoot.TOP_LEVEL_DOMAINS: updated
+
+Fri Jun 13 14:18:04 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * xrds.rb: fix stray colon
+
+Fri Jun 13 13:41:58 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * Yadis::get_canonical_id: case-insensitive comparison
+  
+  Porting a patch from =wil:
   
-  This seems to be the desired behavior.
+  1. There should only be a single CanonicalID in each XRD (in the latest XRI
+  resolution spec), so I made it use the first CID found instead of the last.
   
-  IdResHandler.check_auth: don't bother casting an OpenIDError to another OpenIDError.
+  2. Use case-insensitive comparison when comparing CanonicalIDs.
 
-Mon Jan 14 17:59:38 PST 2008  Kevin Turner <kevin@janrain.com>
-  * OpenID::ServerError: add server_url to attributes.
+Wed Jun 11 15:24:12 PDT 2008  Kevin Turner <kevin@janrain.com>
+  * Accept response code 206 from fetcher results.  Fixes #260
 
-Mon Jan 14 17:21:10 PST 2008  Kevin Turner <kevin@janrain.com>
-  * ProtocolError, ServerError: subclass OpenIDError
+Wed Jun 11 11:27:25 PDT 2008  cygnus@janrain.com
+  * admin/fixperms: Fix stale entries
 
-Mon Jan 14 17:20:01 PST 2008  Kevin Turner <kevin@janrain.com>
-  * UPGRADE: fix typo in example path
+Wed Jun 11 11:08:11 PDT 2008  cygnus@janrain.com
+  * Add test cases for trust roots with non-ASCII characters in path or hostname
 
-Fri Jan 11 11:31:29 PST 2008  cygnus@janrain.com
-  tagged 2.0.3
+Fri Jun  6 15:50:12 PDT 2008  cygnus@janrain.com
+  tagged 2.1.1

data/LICENSE

@@ -1,7 +1,10 @@
 The code in lib/hmac/ is Copyright 2001 by Daiki Ueno, and distributed under
 the terms of the Ruby license.  See http://www.ruby-lang.org/en/LICENSE.txt
 
-The remainder of this package is Copyright 2006-2007 by JanRain, Inc. and
+lib/openid/yadis/htmltokenizer.rb is Copyright 2004 by Ben Giddings and
+distributed under the terms of the Ruby license.
+
+The remainder of this package is Copyright 2006-2008 by JanRain, Inc. and
 distributed under the terms of license below:
 
                                  Apache License

data/README

@@ -31,20 +31,21 @@ Check the installation:
 The library is known to work with Ruby 1.8.4 on Unix, Max OSX and
 Win32.  Examples have been tested with Rails 1.1 and 1.2, and 2.0.
 
-==Getting Started with OpenID::Consumer
-OpenID::Consumer is the place to start if you'd like to support OpenID
-authentication on your website.  The examples directory contains
-several working examples to help you get started, and the
-OpenID::Consumer class is well-documented.
+==Getting Started
+The best way to start is to look at the rails_openid example.
+You can run it with:
+ cd examples/rails_openid
+ script/server
 
-Also, check out the OpenIDLoginGenerator!  Read examples/README for
-more info.
+If you are writing an OpenID Relying Party, a good place to start is:
+examples/rails_openid/app/controllers/consumer_controller.rb
 
-==Serving OpenID with OpenID::Server
-The examples directory contains a fully-functional OpenID server that
-uses the Ruby on Rails framework.  Start by reading about the
-OpenID::Server interface documentation and looking at the example.
+And if you are writing an OpenID provider:
+examples/rails_openid/app/controllers/server_controller.rb
 
+The library code is quite well documented, so don't be squeamish, and
+look at the library itself if there's anything you don't understand in
+the examples.
 
 ==Homepage
 http://openidenabled.com/ruby-openid/
@@ -64,8 +65,14 @@ Please join this list to discuss, ask implementation questions, report
 bugs, etc.  Also check out the openid channel on the freenode IRC
 network.
 
+If you have a bugfix or feature you'd like to contribute, don't
+hesitate to send it to us.  For more detailed information on how to
+contribute, see
+
+  http://openidenabled.com/contribute/
+
 ==Author
-Copyright 2006-2007, JanRain, Inc.
+Copyright 2006-2008, JanRain, Inc.
 
 Contact openid@janrain.com or visit the OpenID channel on pibb.com:
 

data/UPGRADE

@@ -57,6 +57,11 @@ additional arguments to the return_to url, use
 Generating the redirect is the same as before, but add any extensions
 first.
 
+If you need to set up an SSL certificate authority list for the fetcher,
+use the 'ca_file' attr_accessor on the OpenID::StandardFetcher.  This has
+changed from 'ca_path' in the 1.x.x series library.  That is, set
+OpenID.fetcher.ca_file = '/path/to/ca.list'
+before calling consumer.begin.
 
 === Requesting Simple Registration Data
 

data/examples/README

@@ -15,28 +15,14 @@ Rails installed, and then:
 
 Open a web browser to http://localhost:3000/ and follow the instructions.
 
-
-==Rails OpenidLoginGenerator
-
-A port of the standard LoginGenerator OpenID authentication instead of
-passwords.  Use this generator as a *starting point* for your OpenID
-enabled rails app.
-
-You can read about LoginGenerator at
-http://wiki.rubyonrails.com/rails/pages/LoginGenerator
-
-===Running the generator
-
-* Copy the contents of rails_openid_login_generator into 
- ~/.rails/generators/openid_login 
- (or symlink: ln -s examples/rails_openid_login_generator 
-                    ~/.rails/generators/openid_login)
-* run script/generate openid_login openid
-
-You will now have an openid_controller.rb in app/controllers. You'll
-need to create your 'users' database table before running the
-application.  For schemas and more details about this generator, read
-README_LOGIN in you rails root directory.
+The relevant code to work from when writing your Rails OpenID Relying
+Party is: 
+  rails_openid/app/controllers/consumer_controller.rb
+If you are working on an OpenID provider, check out
+  rails_openid/app/controllers/server_controller.rb
+
+Since the library and examples are Apache-licensed, don't be shy about 
+copy-and-paste.
 
 ==Rails ActiveRecord OpenIDStore plugin
 

data/examples/active_record_openid_store/XXX_add_open_id_store_to_db.rb

@@ -2,12 +2,12 @@
 class AddOpenIdStoreToDb < ActiveRecord::Migration
   def self.up
     create_table "open_id_associations", :force => true do |t|
-      t.column "server_url", :binary
-      t.column "handle", :string
-      t.column "secret", :binary
-      t.column "issued", :integer
-      t.column "lifetime", :integer
-      t.column "assoc_type", :string
+      t.column "server_url", :binary, :null => false
+      t.column "handle", :string, :null => false
+      t.column "secret", :binary, :null => false
+      t.column "issued", :integer, :null => false
+      t.column "lifetime", :integer, :null => false
+      t.column "assoc_type", :string, :null => false
     end
 
     create_table "open_id_nonces", :force => true do |t|

data/examples/active_record_openid_store/lib/association.rb

@@ -1,9 +1,10 @@
 require 'openid/association'
+require 'time'
 
 class Association < ActiveRecord::Base
   set_table_name 'open_id_associations'
   def from_record
-    OpenID::Association.new(handle, secret, issued, lifetime, assoc_type)
+    OpenID::Association.new(handle, secret, Time.at(issued), lifetime, assoc_type)
   end
 end
 

data/examples/active_record_openid_store/lib/openid_ar_store.rb

@@ -6,10 +6,10 @@ require 'openid/store/interface'
 class ActiveRecordStore < OpenID::Store::Interface
   def store_association(server_url, assoc)
     remove_association(server_url, assoc.handle)    
-    Association.create(:server_url => server_url,
+    Association.create!(:server_url => server_url,
                        :handle     => assoc.handle,
                        :secret     => assoc.secret,
-                       :issued     => assoc.issued,
+                       :issued     => assoc.issued.to_i,
                        :lifetime   => assoc.lifetime,
                        :assoc_type => assoc.assoc_type)
   end
@@ -40,7 +40,7 @@ class ActiveRecordStore < OpenID::Store::Interface
   def use_nonce(server_url, timestamp, salt)
     return false if Nonce.find_by_server_url_and_timestamp_and_salt(server_url, timestamp, salt)
     return false if (timestamp - Time.now.to_i).abs > OpenID::Nonce.skew
-    Nonce.create(:server_url => server_url, :timestamp => timestamp, :salt => salt)
+    Nonce.create!(:server_url => server_url, :timestamp => timestamp, :salt => salt)
     return true
   end
   

data/examples/rails_openid/app/controllers/consumer_controller.rb

@@ -14,9 +14,15 @@ class ConsumerController < ApplicationController
 
   def start
     begin
-      oidreq = consumer.begin(params[:openid_identifier])
+      identifier = params[:openid_identifier]
+      if identifier.nil?
+        flash[:error] = "Enter an OpenID identifier"
+        redirect_to :action => 'index'
+        return
+      end
+      oidreq = consumer.begin(identifier)
     rescue OpenID::OpenIDError => e
-      flash[:error] = "Discovery failed for #{params[:openid_identifier]}: #{e}"
+      flash[:error] = "Discovery failed for #{identifier}: #{e}"
       redirect_to :action => 'index'
       return
     end
@@ -45,7 +51,7 @@ class ConsumerController < ApplicationController
     if oidreq.send_redirect?(realm, return_to, params[:immediate])
       redirect_to oidreq.redirect_url(realm, return_to, params[:immediate])
     else
-      @form_text = oidreq.form_markup(realm, return_to, params[:immediate], {'id' => 'openid_form'})
+      render :text => oidreq.html_markup(realm, return_to, params[:immediate], {'id' => 'openid_form'})
     end
   end
 
@@ -86,8 +92,8 @@ class ConsumerController < ApplicationController
         else
           pape_message << ", but the server did not report one."
         end
-        if pape_resp.auth_age
-          pape_message << "<br><b>Authentication age:</b> #{pape_resp.auth_age} seconds"
+        if pape_resp.auth_time
+          pape_message << "<br><b>Authentication time:</b> #{pape_resp.auth_time} seconds"
         end
         if pape_resp.nist_auth_level
           pape_message << "<br><b>NIST Auth Level:</b> #{pape_resp.nist_auth_level}"

data/lib/openid.rb

@@ -12,5 +12,9 @@
 # implied. See the License for the specific language governing
 # permissions and limitations under the License.
 
+module OpenID
+  VERSION = "2.1.2"
+end
+
 require "openid/consumer"
 require 'openid/server'

data/lib/openid/association.rb

@@ -28,13 +28,13 @@ module OpenID
       parsed = Util.kv_to_seq(serialized)
       parsed_fields = parsed.map{|k, v| k.to_sym}
       if parsed_fields != FIELD_ORDER
-          raise StandardError, 'Unexpected fields in serialized association'\
+          raise ProtocolError, 'Unexpected fields in serialized association'\
           " (Expected #{FIELD_ORDER.inspect}, got #{parsed_fields.inspect})"
       end
       version, handle, secret64, issued_s, lifetime_s, assoc_type =
         parsed.map {|field, value| value}
       if version != '2'
-        raise StandardError, "Attempted to deserialize unsupported version "\
+        raise ProtocolError, "Attempted to deserialize unsupported version "\
                              "(#{parsed[0][1].inspect})"
       end
 
@@ -101,7 +101,7 @@ module OpenID
       when 'HMAC-SHA256'
         CryptUtil.hmac_sha256(@secret, kv)
       else
-        raise StandardError, "Association has unknown type: "\
+        raise ProtocolError, "Association has unknown type: "\
           "#{assoc_type.inspect}"
       end
     end
@@ -111,7 +111,7 @@ module OpenID
     def make_pairs(message)
       signed = message.get_arg(OPENID_NS, 'signed')
       if signed.nil?
-        raise StandardError, 'Missing signed list'
+        raise ProtocolError, 'Missing signed list'
       end
       signed_fields = signed.split(',', -1)
       data = message.to_post_args
@@ -122,7 +122,7 @@ module OpenID
     def check_message_signature(message)
       message_sig = message.get_arg(OPENID_NS, 'sig')
       if message_sig.nil?
-        raise StandardError, "#{message} has no sig."
+        raise ProtocolError, "#{message} has no sig."
       end
       calculated_sig = get_message_signature(message)
       return calculated_sig == message_sig
@@ -190,13 +190,13 @@ module OpenID
       when 'HMAC-SHA256'
         ['DH-SHA256', 'no-encryption']
       else
-        raise StandardError, "Unknown association type #{assoc_type.inspect}"
+        raise ProtocolError, "Unknown association type #{assoc_type.inspect}"
       end
     end
 
     def self.check_session_type(assoc_type, session_type)
       if !get_session_types(assoc_type).include?(session_type)
-        raise StandardError, "Session type #{session_type.inspect} not "\
+        raise ProtocolError, "Session type #{session_type.inspect} not "\
                              "valid for association type #{assoc_type.inspect}"
       end
     end

data/lib/openid/consumer/checkid_request.rb

@@ -158,6 +158,17 @@ module OpenID
         return message.to_form_markup(@endpoint.server_url, form_tag_attrs)
       end
 
+      # Get a complete HTML document that autosubmits the request to the IDP
+      # with javascript.  This method wraps form_markup - see that method's
+      # documentation for help with the parameters.
+      def html_markup(realm, return_to=nil, immediate=false,
+                      form_tag_attrs=nil)
+        Util.auto_submit_html(form_markup(realm, 
+                                          return_to, 
+                                          immediate, 
+                                          form_tag_attrs))
+      end
+
       # Should this OpenID authentication request be sent as a HTTP
       # redirect or as a POST (form submission)?
       #

data/lib/openid/consumer/discovery.rb

@@ -57,9 +57,18 @@ module OpenID
 
     def display_identifier
       return @display_identifier if @display_identifier
-      return @claimed_id if @claimed_id.nil? or not URI.parse(@claimed_id).fragment
 
-      disp = URI.parse(@claimed_id)
+      return @claimed_id if @claimed_id.nil? 
+
+      begin
+        parsed_identifier = URI.parse(@claimed_id)
+      rescue URI::InvalidURIError
+        raise ProtocolError, "Claimed identifier #{claimed_id} is not a valid URI"
+      end
+
+      return @claimed_id if not parsed_identifier.fragment
+
+      disp = parsed_identifier
       disp.fragment = nil
 
       return disp.to_s
@@ -434,7 +443,7 @@ module OpenID
 
   def self.discover_no_yadis(uri)
     http_resp = OpenID.fetch(uri)
-    if http_resp.code != "200"
+    if http_resp.code != "200" and http_resp.code != "206"
       raise DiscoveryFailure.new(
         "HTTP Response status from identity URL host is not \"200\". "\
         "Got status #{http_resp.code.inspect}", http_resp)

data/lib/openid/consumer/idres.rb

@@ -2,6 +2,7 @@ require "openid/message"
 require "openid/protocolerror"
 require "openid/kvpost"
 require "openid/consumer/discovery"
+require "openid/urinorm"
 
 module OpenID
   class TypeURIMismatch < ProtocolError
@@ -138,7 +139,7 @@ module OpenID
 
       def verify_return_to
         begin
-          msg_return_to = URI.parse(fetch('return_to'))
+          msg_return_to = URI.parse(URINorm::urinorm(fetch('return_to')))
         rescue URI::InvalidURIError
           raise ProtocolError, ("return_to is not a valid URI")
         end
@@ -188,7 +189,7 @@ module OpenID
 
       def verify_return_to_base(msg_return_to)
         begin
-          app_parsed = URI.parse(@current_url)
+          app_parsed = URI.parse(URINorm::urinorm(@current_url))
         rescue URI::InvalidURIError
           raise ProtocolError, "current_url is not a valid URI: #{@current_url}"
         end
@@ -239,24 +240,17 @@ module OpenID
       end
 
       def create_check_auth_request
-        check_args = {}
-
-        # Arguments that are always passed to the server and not
-        # included in the signature.
-        for k in ['assoc_handle', 'sig', 'signed', 'invalidate_handle']
-          val = fetch(k, nil)
-          if !val.nil?
-            check_args[k] = val
-          end
-        end
+        signed_list = @message.get_arg(OPENID_NS, 'signed', NO_DEFAULT).split(',')
 
-        for k in signed_list
-          val = @message.get_aliased_arg(k, NO_DEFAULT)
-          check_args[k] = val
-        end
+        # check that we got all the signed arguments
+        signed_list.each {|k|
+          @message.get_aliased_arg(k, NO_DEFAULT)
+        }
 
-        check_args['mode'] = 'check_authentication'
-        return Message.from_openid_args(check_args)
+        ca_message = @message.copy
+        ca_message.set_arg(OPENID_NS, 'mode', 'check_authentication')
+
+        return ca_message
       end
 
       # Process the response message from a check_authentication
@@ -352,7 +346,7 @@ module OpenID
 
         if @endpoint.nil?
           Util.log('No pre-discovered information supplied')
-          discover_and_verify(to_match)
+          discover_and_verify(to_match.claimed_id, [to_match])
         else
           begin
             verify_discovery_single(@endpoint, to_match)
@@ -360,7 +354,7 @@ module OpenID
             Util.log("Error attempting to use stored discovery "\
                      "information: #{why.message}")
             Util.log("Attempting discovery to verify endpoint")
-            discover_and_verify(to_match)
+            discover_and_verify(to_match.claimed_id, [to_match])
           end
         end
 
@@ -376,7 +370,7 @@ module OpenID
 
         if claimed_id.nil?
           if @endpoint.nil?
-            raise StandardError, ("When using OpenID 1, the claimed ID must "\
+            raise ProtocolError, ("When using OpenID 1, the claimed ID must "\
                                   "be supplied, either by passing it through "\
                                   "as a return_to parameter or by using a "\
                                   "session, and supplied to the IdResHandler "\
@@ -414,55 +408,53 @@ module OpenID
         # Either no endpoint was supplied or OpenID 1.x verification
         # of the information that's in the message failed on that
         # endpoint.
-        begin
-          discover_and_verify(to_match)
-        rescue TypeURIMismatch
-          discover_and_verify(to_match_1_0)
-        end
+        discover_and_verify(to_match.claimed_id, [to_match, to_match_1_0])
       end
 
       # Given an endpoint object created from the information in an
       # OpenID response, perform discovery and verify the discovery
       # results, returning the matching endpoint that is the result of
       # doing that discovery.
-      def discover_and_verify(to_match)
-        Util.log("Performing discovery on #{to_match.claimed_id}")
-        _, services = OpenID.discover(to_match.claimed_id)
+      def discover_and_verify(claimed_id, to_match_endpoints)
+        Util.log("Performing discovery on #{claimed_id}")
+        _, services = OpenID.discover(claimed_id)
         if services.length == 0
           # XXX: this might want to be something other than
           # ProtocolError. In Python, it's DiscoveryFailure
           raise ProtocolError, ("No OpenID information found at "\
-                                "#{to_match.claimed_id}")
+                                "#{claimed_id}")
         end
-        verify_discovered_services(services, to_match)
+        verify_discovered_services(claimed_id, services, to_match_endpoints)
       end
 
 
-      def verify_discovered_services(services, to_match)
+      def verify_discovered_services(claimed_id, services, to_match_endpoints)
         # Search the services resulting from discovery to find one
         # that matches the information from the assertion
         failure_messages = []
         for endpoint in services
-          begin
-            verify_discovery_single(endpoint, to_match)
-          rescue ProtocolError => why
-            failure_messages << why.message
-          else
-            # It matches, so discover verification has
-            # succeeded. Return this endpoint.
-            @endpoint = endpoint
-            return
+          for to_match_endpoint in to_match_endpoints
+            begin
+              verify_discovery_single(endpoint, to_match_endpoint)
+            rescue ProtocolError => why
+              failure_messages << why.message
+            else
+              # It matches, so discover verification has
+              # succeeded. Return this endpoint.
+              @endpoint = endpoint
+              return
+            end
           end
         end
 
-        Util.log("Discovery verification failure for #{to_match.claimed_id}")
+        Util.log("Discovery verification failure for #{claimed_id}")
         failure_messages.each do |failure_message|
           Util.log(" * Endpoint mismatch: " + failure_message)
         end
 
         # XXX: is DiscoveryFailure in Python OpenID
         raise ProtocolError, ("No matching endpoint found after "\
-                              "discovering #{to_match.claimed_id}")
+                              "discovering #{claimed_id}")
       end
 
       def verify_discovery_single(endpoint, to_match)