branch: externals/url-http-oauth
commit 38157dfb3adf3f7fd44ecaa7eed738fff0b22606
Author: Thomas Fitzsimmons <fitz...@fitzsim.org>
Commit: Thomas Fitzsimmons <fitz...@fitzsim.org>
Reduce overloading of "register"
* url-http-oauth.el: Add Usage section to Commentary.
(url-http-oauth--interposed): Rename.
(url-http-oauth-configuration): Update references.
(url-http-oauth-interpose): Rename. Update references.
(url-http-oauth-ignore): Rename.
(url-http-oauth-get-bearer): Update error message.
---
url-http-oauth.el | 43 +++++++++++++++++++++++--------------------
1 file changed, 23 insertions(+), 20 deletions(-)
diff --git a/url-http-oauth.el b/url-http-oauth.el
index 4852bab2f3..5ccf6488dc 100644
--- a/url-http-oauth.el
+++ b/url-http-oauth.el
@@ -26,13 +26,17 @@
;; Installation:
;;
;; M-x package-install RET url-http-oauth RET
+;;
+;; Usage:
+;;
+;; See url-http-oauth-demo.el.
;;; Code:
(require 'url-auth)
(require 'url-http)
(require 'url-util)
-(defvar url-http-oauth--registered-oauth-urls nil
+(defvar url-http-oauth--interposed nil
"A hash table mapping URL strings to lists of OAuth 2.0 configuration.")
(defun url-http-oauth-url-string (url)
@@ -46,7 +50,7 @@
(defun url-http-oauth-configuration (url)
"Return a configuration list if URL needs OAuth 2.0, nil otherwise.
URL is either a URL object or a URL string."
- (when url-http-oauth--registered-oauth-urls
+ (when url-http-oauth--interposed
(let* ((url-no-query (url-parse-make-urlobj
(url-type url)
nil nil
@@ -55,19 +59,19 @@ URL is either a URL object or a URL string."
(car (url-path-and-query url))
nil nil t))
(key (url-http-oauth-url-string url-no-query)))
- (gethash key url-http-oauth--registered-oauth-urls))))
+ (gethash key url-http-oauth--interposed))))
;; Maybe if RFC 8414, "OAuth 2.0 Authorization Server Metadata",
;; catches on, authorization-url and access-token-url can be made
;; optional and their values retrieved automatically. As of early
;; 2023, RFC 8414 is not consistently implemented yet.
-(defun url-http-oauth-register-resource (url
- authorization-url
- access-token-url
- client-identifier
- &optional
- client-secret-required)
- "Tell Emacs that to access URL, it needs to use OAuth 2.0.
+(defun url-http-oauth-interpose (url
+ authorization-url
+ access-token-url
+ client-identifier
+ &optional
+ client-secret-required)
+ "Arrange for Emacs to use OAuth 2.0 to access URL.
URL will be accessed by Emacs's `url' library with a suitable
\"Authorization\" header containing \"Bearer <token>\".
AUTHORIZATION-URL and ACCESS-TOKEN-URL will be used to acquire
@@ -76,9 +80,8 @@ AUTHORIZATION-URL and ACCESS-TOKEN-URL are either objects or
strings. CLIENT-IDENTIFIER is a string identifying an Emacs
library or mode to the server. CLIENT-SECRET-REQUIRED is the
symbol `prompt' if a client secret is required, nil otherwise."
- (unless url-http-oauth--registered-oauth-urls
- (setq url-http-oauth--registered-oauth-urls
- (make-hash-table :test #'equal)))
+ (unless url-http-oauth--interposed
+ (setq url-http-oauth--interposed (make-hash-table :test #'equal)))
(let ((key (url-http-oauth-url-string url))
(authorization (url-http-oauth-url-string authorization-url))
(access-token-object (url-http-oauth-url-object access-token-url)))
@@ -88,14 +91,14 @@ symbol `prompt' if a client secret is required, nil
otherwise."
((eq client-secret-required nil) nil)
(t (error
"Unrecognized client-secret-required value"))))
- url-http-oauth--registered-oauth-urls)))
+ url-http-oauth--interposed)))
-(defun url-http-oauth-unregister-resource (url)
- "Tell Emacs not to use OAuth 2.0 when accessing URL.
+(defun url-http-oauth-ignore (url)
+ "Arrange for Emacs not to use OAuth 2.0 when accessing URL.
+This function does the opposite of `url-http-oauth-interpose'.
URL is either an objects or a string."
- (when url-http-oauth--registered-oauth-urls
- (remhash (url-http-oauth-url-string url)
- url-http-oauth--registered-oauth-urls)))
+ (when url-http-oauth--interposed
+ (remhash (url-http-oauth-url-string url) url-http-oauth--interposed)))
(defvar url-http-response-status)
(defvar auth-source-creation-prompts)
@@ -195,7 +198,7 @@ URL is a parsed object."
(or bearer-current
(let ((url-list (url-http-oauth-configuration url)))
(unless url-list
- (error "%s is not registered with url-http-oauth"
+ (error "%s is not interposed by url-http-oauth"
(url-http-oauth-url-string url)))
(let* ((response-url
(read-from-minibuffer
