complete interface docs

pkg/op/server.go

@@ -42,23 +42,28 @@ func (e StatusError) Is(err error) bool {
 }
 
 type Request[T any] struct {
-	Method string
-	URL    *url.URL
-	Header http.Header
-	Form   url.Values
-	Data   *T
+	Method   string
+	URL      *url.URL
+	Header   http.Header
+	Form     url.Values
+	PostForm url.Values
+	Data     *T
 }
 
 func newRequest[T any](r *http.Request, data *T) *Request[T] {
 	return &Request[T]{
-		Method: r.Method,
-		URL:    r.URL,
-		Header: r.Header,
-		Form:   r.Form,
-		Data:   data,
+		Method:   r.Method,
+		URL:      r.URL,
+		Header:   r.Header,
+		Form:     r.Form,
+		PostForm: r.PostForm,
+		Data:     data,
 	}
 }
 
+// ClientRequest is a Request with a verified client attached to it.
+// Methods the recieve this argument may assume the client was authenticated,
+// or verified to be a public client.
 type ClientRequest[T any] struct {
 	*Request[T]
 	Client Client
@@ -102,6 +107,28 @@ type Redirect struct {
 	Params url.Values
 }
 
+// Server describes the inferface that needs to be implemented to serve
+// openID Connect and Oauth2 standard requests.
+//
+// Methods are called after the HTTP route is resolved and
+// the request body is parsed into the Request's Data field.
+// When a method is called, it can be assumed that required fields,
+// as described in their relavant standard, are validated already.
+// The Response Data field may be of any type to allow flexibilty
+// to extend responses with custom fields. There are however requirements
+// in the standards regarding the repsonse models. Where applicable
+// the method documentation gives a recommodated type which can be used
+// directly or extended upon.
+//
+// In short it is the scope of this framework to:
+//   - Route requests to their methods;
+//   - Parse request data into a type that represents the model from the standards;
+//   - Validate required fields in the request;
+//   - Provide utility functions that help implementors build the response;
+//
+// It is in the scope of the implementor:
+//   - Handle the request data to obtain or modify state in their storage / database;
+//   - Implement the business logic that is needed to build the response;
 type Server interface {
 	// Health should return a status of "ok" once the Server is listining.
 	// The recommended Response Data type is [Status].
@@ -208,6 +235,8 @@ type Server interface {
 	// The recommended Response Data type is [jose.JSOMWebKeySet].
 	Keys(context.Context, *Request[struct{}]) (*Response, error)
 
+	// mustImpl forces implementations to embed the UnimplementedServer for forward
+	// compatibilty with the interface.
 	mustImpl()
 }