From b10fc5b5887287faca60c39a5a62e36de1de7b75 Mon Sep 17 00:00:00 2001 From: Lennart Date: Mon, 19 Jul 2021 17:59:47 +0200 Subject: [PATCH] provide^Wupdate docs of package web --- web/error.go | 9 +++------ web/main.go | 34 +++++++++++++++++++++------------- web/module.go | 6 +++--- web/request.go | 7 +++++-- web/response.go | 18 ++++++++++-------- web/session.go | 8 ++++---- 6 files changed, 46 insertions(+), 36 deletions(-) diff --git a/web/error.go b/web/error.go index 474a94e..42ab123 100644 --- a/web/error.go +++ b/web/error.go @@ -1,6 +1,6 @@ package web -// HTTPError as a response, with data +// HTTPError is returned in HTTP error responses. type HTTPError struct { Message string `json:"message" example:"invalid format"` Error string `json:"error,omitempty" example:""` @@ -8,10 +8,7 @@ type HTTPError struct { } const ( - // APIErrorInvalidRequestFormat const for api error with invalid request format APIErrorInvalidRequestFormat = "Invalid Request Format" - // APIErrorInternalDatabase const for api error with problem with database - APIErrorInternalDatabase = "Internal Database Error" - // APIErrorNotFound const for api error with not found object - APIErrorNotFound = "Not found" + APIErrorInternalDatabase = "Internal Database Error" + APIErrorNotFound = "Not found" ) diff --git a/web/main.go b/web/main.go index d3ae4d8..539cf87 100644 --- a/web/main.go +++ b/web/main.go @@ -1,3 +1,12 @@ +/* +Package web implements common functionality for web APIs using Gin and Gorm. + +Modules + +Modules provide functionality for a web server. A module is a function executed +before starting a server, accessing the Service and the Gin Engine. Each Service +maintains a list of modules. When it runs, it executes all of its modules. +*/ package web import ( @@ -13,8 +22,7 @@ import ( "gorm.io/gorm" ) -// Service to store Configuration and Webserver wide objects -// (like DB Connection) +// A Service stores configuration of a server. type Service struct { // config Listen string `toml:"listen"` @@ -36,32 +44,32 @@ type Service struct { modules []ModuleRegisterFunc } -// Run to startup all related web parts -// (e.g. configure the server, metrics, and finally bind routing) -func (config *Service) Run() error { +// Run creates, configures, and runs a new gin.Engine using its registered +// modules. +func (s *Service) Run() error { gin.EnableJsonDecoderDisallowUnknownFields() gin.SetMode(gin.ReleaseMode) r := gin.New() // catch crashed r.Use(gin.Recovery()) - if config.AccessLog { + if s.AccessLog { r.Use(gin.Logger()) log.Debug("request logging enabled") } - config.LoadSession(r) - config.Bind(r) + s.LoadSession(r) + s.Bind(r) - if config.ACME.Enable { - if config.Listen != "" { + if s.ACME.Enable { + if s.Listen != "" { log.Panic("For ACME / Let's Encrypt it is not possible to set `listen`") } m := autocert.Manager{ Prompt: autocert.AcceptTOS, - HostPolicy: autocert.HostWhitelist(config.ACME.Domains...), - Cache: autocert.DirCache(config.ACME.Cache), + HostPolicy: autocert.HostWhitelist(s.ACME.Domains...), + Cache: autocert.DirCache(s.ACME.Cache), } return autotls.RunWithManager(r, &m) } - return r.Run(config.Listen) + return r.Run(s.Listen) } diff --git a/web/module.go b/web/module.go index e73e8db..8adad94 100644 --- a/web/module.go +++ b/web/module.go @@ -6,15 +6,15 @@ import ( "github.com/gin-gonic/gin" ) -// ModuleRegisterFunc format of module which registered to WebService +// A ModuleRegisterFunc is a module. type ModuleRegisterFunc func(*gin.Engine, *Service) -// ModuleRegister used on start of WebService +// ModuleRegister adds f to ws's list of modules. func (ws *Service) ModuleRegister(f ModuleRegisterFunc) { ws.modules = append(ws.modules, f) } -// Bind WebService to gin.Engine +// Bind executes all of ws's modules with r. func (ws *Service) Bind(r *gin.Engine) { for _, f := range ws.modules { f(r, ws) diff --git a/web/request.go b/web/request.go index 3c812fc..6d45ddb 100644 --- a/web/request.go +++ b/web/request.go @@ -6,9 +6,11 @@ import ( "time" ) -// JSONRequest easy get request for json +// JSONRequest issues a GET request to the specified URL and reads the returned +// JSON into value. See json.Unmarshal for the rules for converting JSON into a +// value. func JSONRequest(url string, value interface{}) error { - var netClient = &http.Client{ + netClient := &http.Client{ Timeout: time.Second * 20, } @@ -18,6 +20,7 @@ func JSONRequest(url string, value interface{}) error { } err = json.NewDecoder(resp.Body).Decode(&value) + resp.Body.Close() if err != nil { return err } diff --git a/web/response.go b/web/response.go index 7726fe3..a73bd56 100644 --- a/web/response.go +++ b/web/response.go @@ -5,19 +5,21 @@ import ( ) const ( - // ContentTypeJSON content type of json ContentTypeJSON = "application/json" - // ContentTypeJS content type of javascript - ContentTypeJS = "application/javascript" - // ContentTypeXML content type of xml - ContentTypeXML = "text/xml" - // ContentTypeYAML content type of yaml + ContentTypeJS = "application/javascript" + ContentTypeXML = "text/xml" ContentTypeYAML = "text/yaml" - // ContentTypeHTML content type of html ContentTypeHTML = "text/html" ) -// Response give +// Response sends an HTTP response. +// +// statusCode is the respone's status. +// +// If the request's Content-Type is JavaScript, JSON, YAML, or XML, it returns +// data serialized as JSONP, JSON, YAML, or XML, respectively. If the +// Content-Type is HTML, it returns the HTML template templateName rendered with +// data. func Response(ctx *gin.Context, statusCode int, data interface{}, templateName string) { switch ctx.ContentType() { case ContentTypeJS: diff --git a/web/session.go b/web/session.go index 0dbd77b..1ac918f 100644 --- a/web/session.go +++ b/web/session.go @@ -6,8 +6,8 @@ import ( "github.com/gin-gonic/gin" ) -// LoadSession module to start Session Handling in WebService -func (config *Service) LoadSession(r *gin.Engine) { - store := cookie.NewStore([]byte(config.Session.Secret)) - r.Use(sessions.Sessions(config.Session.Name, store)) +// LoadSessions starts session handling for s. +func (s *Service) LoadSession(r *gin.Engine) { + store := cookie.NewStore([]byte(s.Session.Secret)) + r.Use(sessions.Sessions(s.Session.Name, store)) }