From 5f261045d4c116bed249eb478473cec82d2a259b Mon Sep 17 00:00:00 2001
From: colin <colin@cicadas.surf>
Date: Sat, 11 May 2024 12:49:31 -0700
Subject: Add: README.org

---
 README.org                | 87 +++++++++++++++++++++++++++++++++++++++++++++++
 examples/kitchensink.lisp |  2 +-
 2 files changed, 88 insertions(+), 1 deletion(-)
 create mode 100644 README.org

diff --git a/README.org b/README.org
new file mode 100644
index 0000000..2007cfb
--- /dev/null
+++ b/README.org
@@ -0,0 +1,87 @@
+* WEEKEND: another HTTP endpoint building library
+
+With ~WEEKEND~, endpoints are classes defined with the metaclass
+~endpoint~.
+
+The ~endpoint~ metaclass provides a number of class-level slots which
+specify the HTTP method and the route that the class is meant to
+handle.
+
+Compiling the endpoint class automatically builds and registers a
+hunchentoot handler. Recompiling the class removes the old handler and
+builds a new one. 
+
+Instance slots of an ~endpoint~ class hold data necessary to process
+the request. If a slot is defined with an ~:initarg~, then that slot's
+value is meant to be supplied by the HTTP request, be through embedded
+"route variables", query parameters, or fields in a structured request
+body.
+
+Any slot defined without an ~:initarg~ is meant to have its
+value supplied by some stage in the handler protocol.
+
+The handler protocol is used to control the handling of requests. All
+endpoint classes are required to specialize the ~weekend:handle~
+method. Optionally they may also specialize the ~weekend:authenticate~
+and ~weekend:authorize~ methods.
+
+Before ~handle~ is called, ~authorize~ is called, and before
+~authorize~ is called, ~authenticate~ is called. If either
+~authenticate~ or ~authorize~ return ~NIL~, then the appropriate HTTP
+error is returned to the client. Otherwise ~handle~ is assumed to have
+all it needs to produce the content to be returned to the requesting
+client.
+
+** Examples
+
+See [[./examples][examples]] for a few examples.
+
+** Advantages of the Approach
+
+OOPyness is an advantage.  For example: you can easily recycle
+authentication and authorization by creating mix-in classes on which
+~authorize~ and ~authenticate~ are specialized. Anytime you want to
+add a new endpoint that must be authorized in a particular way, it is
+as easy as adding your mix-in to your new endpoint's superclasses.
+
+The same thing applies to establishing and dis-establishing database
+connections - you simply specialize ~handle~'s ~:around~ method, or
+~:before~ and ~:after~ methods, on your endpoint class.
+
+If you want special processing on your endpoint classes themselves,
+you can sublcass the ~endpoint~ metaclass and specialize
+~intstantiate-instance~ methods.
+
+For example, if you would prefer every endpoint to be be prefixed by a
+particular route string, you can transform the ~route-parts~ field
+before they are processed by ~endpoint~'s ~instantiate-instance~
+method.
+
+** Disadvantages of the Approach
+
+WEEKEND can be be a little verbose. You are free to define your own
+class-defining macros.
+
+This version of weekend is strongly tied to Hunchentoot.
+
+** An example
+
+Suppose you want a page that simply returns "hello":
+
+#+begin_src lisp
+
+(defclass hello ()
+  ()
+  (:metaclass weekend:endpoint)
+  (:method :get)
+  (:route-parts "hello")
+  (:content-type "text/plain"))
+
+(defmethod weekend:handle ((req hello))
+  "Hello!")
+
+
+
+
+
+#+end_src
diff --git a/examples/kitchensink.lisp b/examples/kitchensink.lisp
index 788334d..00a7f25 100644
--- a/examples/kitchensink.lisp
+++ b/examples/kitchensink.lisp
@@ -13,7 +13,7 @@
     :reader name
     :initarg :name
     :initform (wknd::slot-required 'file 'name)))
-  (:documentation "Servies files in the weekend/examples dir.")
+  (:documentation "Serves files in the weekend/examples dir.")
   (:metaclass wknd::endpoint)
   (:method . :get)
   (:route-parts "file" +fname+)
-- 
cgit v1.2.3