From 1748b65cade426b4c13551556ae8d306e744c05e Mon Sep 17 00:00:00 2001 From: dtookey Date: Tue, 1 Aug 2023 13:34:08 -0400 Subject: [PATCH] updated a bunch of docs --- servlet/Router.go | 24 ++++++++++++++++++++++++ servlet/config.go | 20 +++++++++++++++++++- servlet/dynamicRoute.go | 24 ++++++++++++++++++++++++ servlet/server.go | 34 ++++++++++++++++++++++++++++++++++ servlet/templates.go | 35 +++++++++++++++++++++++++++++++++++ 5 files changed, 136 insertions(+), 1 deletion(-) diff --git a/servlet/Router.go b/servlet/Router.go index 05855c0..1be9ec7 100644 --- a/servlet/Router.go +++ b/servlet/Router.go @@ -14,6 +14,30 @@ type ( Routes []*VinegarWebRoute } + // VinegarWebRoute defines a single route in the router. + // It contains the following fields: + // + //Pattern - A regexp.Regexp instance that matches against the request URL path. + // + //Handler - A VinegarHandlerFunction to call when the route matches a request. + // + //Cache - An optional vinegarUtil.Cache instance to enable caching for this route. + // + //VinegarWebRoute is used to define custom routes to handle requests in the + //VinegarWebRouter. Routes should be added to the router using: + // + // router.AddRoute(route) + // + //The router will match incoming requests against route patterns in order. + //When a match is found, the Handler is executed to handle the request. + // + //Example usage: + // + // route := VinegarWebRoute{ + // Pattern: regexp.MustCompile("/users"), + // Handler: myUserHandler, + // } + // router.AddRoute(&route) VinegarWebRoute struct { Pattern *regexp.Regexp Handler VinegarHandlerFunction diff --git a/servlet/config.go b/servlet/config.go index 53f89c3..a4c9ee4 100644 --- a/servlet/config.go +++ b/servlet/config.go @@ -23,7 +23,6 @@ type ( // // So when loading a JSON config, the "ConfigType" field must be // set to one of these constant values like "Text" or "Image". - ConfigType string // ConfigEntry defines a single route configuration entry. @@ -43,6 +42,25 @@ type ( UseBuiltinCache bool } + //Config holds the configuration for creating a VinegarWebServlet instance + //from a JSON file. It contains: + // + //ListeningAddress - The address to listen on as a string like ":8080" + // + //Routes - A slice of ConfigEntry structs, each representing a route. + // + //It is loaded from JSON like: + // + // + // config, err := LoadConfig(configFilePath) + // + //Then used when creating the servlet: + // + // servlet := NewServlet(conf.ListeningAddress) + // // Add routes based on conf.Routes + // + //So Config allows declaring all VinegarWebServlet routes, options, etc + //in a JSON file for easy loading. Config struct { ListeningAddress string Routes []ConfigEntry diff --git a/servlet/dynamicRoute.go b/servlet/dynamicRoute.go index 3101fd0..3b114eb 100644 --- a/servlet/dynamicRoute.go +++ b/servlet/dynamicRoute.go @@ -7,6 +7,30 @@ import ( ) type ( + + //ApiRoute provides a way to define API routes that handle multiple HTTP methods. + // + //It contains: + // + //VinegarRoute - The base VinegarWebRoute that defines the URL pattern to match. + // + //HttpMethodRoutes - A pointer to a map of HTTP method string to handler function. + // + //Usage: + // + //1. Create a new ApiRoute, providing a VinegarHttpServlet and URL pattern: + // + // route := NewApiRoute(serv, "/api/users") + // + //2. Add handler functions for each supported HTTP method: + // + // route.RegisterHttpMethodHandler(http.MethodGet, handleGet) + // route.RegisterHttpMethodHandler(http.MethodPost, handlePost) + // + //3. The route will now match the pattern "/api/users" and call the right + // handler function based on the HTTP method used in the request. + // + //4. If an unsupported HTTP method is used, a 404 error will be returned. ApiRoute struct { VinegarRoute *VinegarWebRoute HttpMethodRoutes *map[string]VinegarHandlerFunction diff --git a/servlet/server.go b/servlet/server.go index dbe4207..a38b4d4 100644 --- a/servlet/server.go +++ b/servlet/server.go @@ -25,6 +25,40 @@ type ErrorResponse struct { } type ( + + // VinegarWebServlet is the main server struct that handles HTTP requests and routing. + // It contains the following key fields: + // + //Port - The TCP port to listen on for incoming requests. Should be a string like ":8080". + // + //Router - A VinegarWebRouter instance that handles routing requests to handlers. + // + //ErrorRoutes - A map of status code to TemplateRoute for custom error pages. + // + //interrupts - A channel used to signal shutdown/interrupts to the server. + // + //errors - A channel that the server writes errors to. + // + //The main methods are: + // + //ServeHTTP - Handles all incoming requests. Calls Router.RouteRequest to handle routing. + // + //AddErrorRoute - Adds a custom error route for the given status code. + // + //Start - Starts the HTTP server listening on Port. Returns any errors. + // + //Shutdown - Shuts down the server by sending a signal on interrupts. + // + //SendError - Helper to send an error response with custom status code and error template. + // + //Typical usage: + // + // srv := NewServlet(":8080") + // srv.AddErrorRoute(404, notFoundRoute) + // srv.Router.AddRoute(someRoute) + // srv.Start() + // // ... + // srv.Shutdown() VinegarWebServlet struct { Port string Router VinegarWebRouter diff --git a/servlet/templates.go b/servlet/templates.go index 68f38a2..698a07e 100644 --- a/servlet/templates.go +++ b/servlet/templates.go @@ -12,6 +12,41 @@ import ( ) type ( + + //TemplateManager handles loading and rendering templates. + //It contains the following fields: + // + //templatePath - The base path to load template files from. + // + //componentPath - The base path to load template components from. + // + //templates - A map of template name to parsed *template.Template. + // + //components - A map of component name to template.HTML content. + // + //mixins - A map of mixin name to content string. + // + //Templates - A slice of all template names that were loaded. + // + //The main methods are: + // + //NewTemplateManager - Constructor to create a new instance. + // + //RenderTemplate - Renders a template by name and returns the output. + // + //GetComponent - Fetches a component by name. + // + //AddMixin - Adds a new mixin value by name. + // + //AddMixinFromFile - Loads a mixin from a file. + // + //RenderAllToFile - Renders all templates to files in a directory. + // + //Typical usage: + // + // tm := NewTemplateManager("templates", "components") + // output := tm.RenderTemplate("index.tmpl") + // tm.AddMixin("title", "My Page") TemplateManager struct { templatePath string componentPath string