From b81c98785a9ad0262434f19f3840e60f9b8927a6 Mon Sep 17 00:00:00 2001 From: Martin Geno Date: Fri, 28 Apr 2017 10:27:36 +0200 Subject: [PATCH] [DOC] add godoc comments --- README.md | 22 +++++++++++----------- cmd/stock/main.go | 1 + http/bindapi.go | 2 ++ http/good_temp.go | 1 + lib/database/database.go | 24 +++++++++++++++++------- lib/http/io.go | 2 +- lib/http/permission.go | 3 ++- lib/log/log.go | 3 +-- lib/worker/worker.go | 7 +++++++ models/config.go | 32 +++++++++++++++++++++++--------- models/good.go | 7 +++++++ models/main.go | 2 ++ runtime/auth.go | 8 ++++++++ runtime/cache_worker.go | 4 ++++ runtime/good_release.go | 1 + runtime/main.go | 2 ++ runtime/productcache.go | 2 ++ test/testrest.go | 10 +++++++--- 18 files changed, 99 insertions(+), 34 deletions(-) create mode 100644 models/main.go create mode 100644 runtime/main.go diff --git a/README.md b/README.md index 946d191..a4f6bfd 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,20 @@ # Stock-Microservice This is a microservice cutted out of a [Monolith](https://gitlab.com/matthiasstock/monolith). -[![Build Status](https://travis-ci.org/genofire/hs_master-kss-monolith.svg?branch=master)](https://travis-ci.org/genofire/hs_master-kss-monolith) [![Coverage Status](https://coveralls.io/repos/github/genofire/hs_master-kss-monolith/badge.svg?branch=master)](https://coveralls.io/github/genofire/hs_master-kss-monolith?branch=master) +[![Build Status](https://travis-ci.org/genofire/hs_master-kss-monolith.svg?branch=master)](https://travis-ci.org/genofire/hs_master-kss-monolith) [![Coverage Status](https://coveralls.io/repos/github/genofire/hs_master-kss-monolith/badge.svg?branch=master)](https://coveralls.io/github/genofire/hs_master-kss-monolith?branch=master) [![GoDoc](https://godoc.org/github.com/genofire/hs_master-kss-monolith?status.svg)](https://godoc.org/github.com/genofire/hs_master-kss-monolith) ## Features of this stock mircoservice * The main functionality of the microservice is to store the goods with their storage location and a time stamp, when they where stored. * Functionality of the admin frontend -** Add new goods to the stock -** Manually remove a single goods from the stock, for example when they are rancid -** Remove single goods from the stock, when they are send to a costumer -** Block goods from the stock, when a costumer added them to hie cart + * Add new goods to the stock + * Manually remove a single goods from the stock, for example when they are rancid + * Remove single goods from the stock, when they are send to a costumer + * Block goods from the stock, when a costumer added them to hie cart * Functionality of the costumer frontend -** Show the store with a traffic light food labelling -** A stock of more then seven goods corresponds to the colour green (sufficient amount of goods) -** A stock between four and seven goods corresponds to the colour orange (moderate amount of goods) -** A stock between zero and three goods corresponds to the colour red (slim amount of goods) + * Show the store with a traffic light food labelling + * A stock of more then seven goods corresponds to the colour green (sufficient amount of goods) + * A stock between four and seven goods corresponds to the colour orange (moderate amount of goods) + * A stock between zero and three goods corresponds to the colour red (slim amount of goods) * Optional Features -** Admin frontend: display of a statistic on how many goods where convexed and manually removed from the stock during the last month -** Traffic light food labelling for each good, which indicates whether the good is too old \ No newline at end of file + * Admin frontend: display of a statistic on how many goods where convexed and manually removed from the stock during the last month + * Traffic light food labelling for each good, which indicates whether the good is too old diff --git a/cmd/stock/main.go b/cmd/stock/main.go index 7e14947..49e7d45 100644 --- a/cmd/stock/main.go +++ b/cmd/stock/main.go @@ -1,3 +1,4 @@ +// The cmd binary of the microservice to run package main import ( diff --git a/http/bindapi.go b/http/bindapi.go index a2003aa..f38c54a 100644 --- a/http/bindapi.go +++ b/http/bindapi.go @@ -1,3 +1,4 @@ +// all api routes of this microservice package http import ( @@ -5,6 +6,7 @@ import ( "goji.io/pat" ) +// bind all API routes to webserver func BindAPI(router *goji.Mux) { router.HandleFunc(pat.Get("/api/status"), status) router.HandleFunc(pat.Get("/api/good/:productid"), listGoods) diff --git a/http/good_temp.go b/http/good_temp.go index 58894ce..b3dd626 100644 --- a/http/good_temp.go +++ b/http/good_temp.go @@ -8,6 +8,7 @@ import ( "text/template" ) +// path to the svg image templaes to show availablity of a given good var GoodAvailablityTemplate string func tempProcent(value, max int) int { diff --git a/lib/database/database.go b/lib/database/database.go index ea445a6..52f2a49 100644 --- a/lib/database/database.go +++ b/lib/database/database.go @@ -10,18 +10,28 @@ import ( "github.com/genofire/hs_master-kss-monolith/lib/log" ) +// Database connection for writing +var Write *gorm.DB + +// Database connection for reading +var Read *gorm.DB + var ( - Write *gorm.DB - Read *gorm.DB - config *Config + config *Config runtime []interface{} ) +// configuration for the database connection type Config struct { - Type string - Connection string + // type of database: current support sqlite and postgres + // (by request other could be enabled) + Type string + // connection configuration + Connection string + // maybe create another connection just for reading ReadConnection string - Logging bool + // enable logging the generated sql string + Logging bool } // Function to open a database and set the given configuration @@ -56,7 +66,7 @@ func Open(c Config) (err error) { return } -//Function to safely close the database +// Function to safely close the database func Close() { Write.Close() Write = nil diff --git a/lib/http/io.go b/lib/http/io.go index c6782d5..b9d5514 100644 --- a/lib/http/io.go +++ b/lib/http/io.go @@ -29,4 +29,4 @@ func Write(w http.ResponseWriter, data interface{}) { } w.Header().Set("Content-Type", "application/json") w.Write(js) -} \ No newline at end of file +} diff --git a/lib/http/permission.go b/lib/http/permission.go index 8efe8bf..1cfe634 100644 --- a/lib/http/permission.go +++ b/lib/http/permission.go @@ -4,9 +4,10 @@ package http import "net/http" +// format of a function to bind it for the middleware handler type HasPermission func(string, int) (bool, error) -//Function to evaluate the permission and implent an error handling +// Function to evaluate the permission and implent an error handling // Input: http response writer w, pointer to htto request r, bool variable HasPermission perm, int variable permission (form) func PermissionHandler(h func(w http.ResponseWriter, r *http.Request), perm HasPermission, permission int) func(w http.ResponseWriter, r *http.Request) { return func(w http.ResponseWriter, r *http.Request) { diff --git a/lib/log/log.go b/lib/log/log.go index 6fa8db8..0d73258 100644 --- a/lib/log/log.go +++ b/lib/log/log.go @@ -9,10 +9,9 @@ import ( logger "github.com/Sirupsen/logrus" ) +// current logger with configuration var Log *logger.Logger -type Logger logger.Entry - // Function to initiate a new logger func init() { Log = logger.New() diff --git a/lib/worker/worker.go b/lib/worker/worker.go index 2353ce2..286f90d 100644 --- a/lib/worker/worker.go +++ b/lib/worker/worker.go @@ -1,13 +1,16 @@ +// A little lib for cronjobs to run it in background package worker import "time" +// a struct which handle the job type Worker struct { every time.Duration run func() quit chan struct{} } +// create a new Worker with timestamp run every and his function func NewWorker(every time.Duration, f func()) (w *Worker) { w = &Worker{ every: every, @@ -17,6 +20,8 @@ func NewWorker(every time.Duration, f func()) (w *Worker) { return } +// start the worker +// please us it as a goroutine: go w.Start() func (w *Worker) Start() { ticker := time.NewTicker(w.every) for { @@ -29,6 +34,8 @@ func (w *Worker) Start() { } } } + +// stop the worker func (w *Worker) Close() { close(w.quit) } diff --git a/models/config.go b/models/config.go index 827f0ea..1d03496 100644 --- a/models/config.go +++ b/models/config.go @@ -9,31 +9,45 @@ import ( "github.com/genofire/hs_master-kss-monolith/lib/log" ) -//Config the config File of this daemon +//config file of this daemon (for more the config_example.conf in git repository) type Config struct { - WebserverBind string `toml:"webserver_bind"` - Webroot string `toml:"webroot"` - Database database.Config `toml:"database"` - GoodRelease GoodReleaseConfig `toml:"good_release"` - CacheClean CacheWorkerConfig `toml:"cache_clean"` - GoodAvailablityTemplate string `toml:"good_availablity_template"` + // address on which the api and static content webserver runs + WebserverBind string `toml:"webserver_bind"` + + // path to deliver static content + Webroot string `toml:"webroot"` + + Database database.Config `toml:"database"` + GoodRelease GoodReleaseConfig `toml:"good_release"` + CacheClean CacheWorkerConfig `toml:"cache_clean"` + + // path to the svg image templaes to show availablity of a given good + GoodAvailablityTemplate string `toml:"good_availablity_template"` + + // URLs to other microservices MicroserviceDependencies struct { Product string `toml:"product"` Permission string `toml:"permission"` } `toml:"microservice_dependencies"` } +//config of worker to clean caches from values of other microservice type CacheWorkerConfig struct { + // run worker every ... Every Duration + // remove cache which is not used since .. After Duration } +//config of worker to release looked goods after a time type GoodReleaseConfig struct { - After Duration `toml:"after"` + // run worker every ... Every Duration `toml:"every"` + // unlock which is not used since .. + After Duration `toml:"after"` } -// ReadConfigFile reads a config model from path of a yml file +//reads a config model from path of a yml file func ReadConfigFile(path string) *Config { config := &Config{} file, err := ioutil.ReadFile(path) diff --git a/models/good.go b/models/good.go index f1fca0b..c3c5bd8 100644 --- a/models/good.go +++ b/models/good.go @@ -9,6 +9,7 @@ import ( "github.com/genofire/hs_master-kss-monolith/lib/database" ) +// this stock microservice manage goods type Good struct { ID int64 ProductID int64 @@ -25,18 +26,24 @@ type Good struct { Sended bool } +// generate database select which filtered locked goods func (g *Good) FilterAvailable(db *gorm.DB) *gorm.DB { return db.Model(g).Where("locked_secret == '' OR locked_secret is NULL") } +// lock the good, on a way, that it could not be used by other users func (g *Good) Lock(secret string) { now := time.Now() g.LockedSecret = secret g.LockedAt = &now } + +// is this good locked? func (g *Good) IsLock() bool { return len(g.LockedSecret) > 0 } + +// unlock the good, that it could be usered again func (g *Good) Unlock(secret string) error { if g.LockedSecret == secret { g.LockedSecret = "" diff --git a/models/main.go b/models/main.go new file mode 100644 index 0000000..a6a97ad --- /dev/null +++ b/models/main.go @@ -0,0 +1,2 @@ +// a package to store all the struct +package models diff --git a/runtime/auth.go b/runtime/auth.go index 176e60d..78f45a8 100644 --- a/runtime/auth.go +++ b/runtime/auth.go @@ -8,12 +8,19 @@ import ( "github.com/genofire/hs_master-kss-monolith/lib/log" ) +// url to the microservice which manage the permissions var PermissionURL string +// type of permission type Permission int +// some permission (see Permission) const ( + // has the user the permission to create need goods of a product + // e.g. if a good received and now availablity to sell PermissionCreateGood = 1 + // has the user the permission to delete need goods of a product + // e.g. if a good become rancid and has to remove from stock PermissionDeleteGood = 2 ) @@ -49,6 +56,7 @@ func init() { permissionCache = make(map[string]*permissionMicroServiceCache) } +// check if the client with the session string has a permissions (see Permission) func HasPermission(session string, p Permission) (bool, error) { _, ok := permissionCache[session] if !ok { diff --git a/runtime/cache_worker.go b/runtime/cache_worker.go index 868b4d4..70067e3 100644 --- a/runtime/cache_worker.go +++ b/runtime/cache_worker.go @@ -7,8 +7,10 @@ import ( "github.com/genofire/hs_master-kss-monolith/models" ) +// config of the cache worker var CacheConfig models.CacheWorkerConfig +// command which is runned in the cache worker func CleanCache() { before := time.Now().Add(-CacheConfig.After.Duration) // Cache if product exists @@ -24,6 +26,8 @@ func CleanCache() { } } } + +// create a worker to clean the caches which stored from other microservice func NewCacheWorker() (w *worker.Worker) { return worker.NewWorker(CacheConfig.Every.Duration, CleanCache) } diff --git a/runtime/good_release.go b/runtime/good_release.go index 723a2cd..fd0742f 100644 --- a/runtime/good_release.go +++ b/runtime/good_release.go @@ -8,6 +8,7 @@ import ( "github.com/genofire/hs_master-kss-monolith/models" ) +// create a worker to unlock goods which are locked by clients func NewGoodReleaseWorker(grc models.GoodReleaseConfig) *worker.Worker { return worker.NewWorker(grc.Every.Duration, func() { goodRelease(grc.After.Duration) diff --git a/runtime/main.go b/runtime/main.go new file mode 100644 index 0000000..4826849 --- /dev/null +++ b/runtime/main.go @@ -0,0 +1,2 @@ +// some functionality to handle it in background which is intermeshed +package runtime diff --git a/runtime/productcache.go b/runtime/productcache.go index ed785af..79e6da1 100644 --- a/runtime/productcache.go +++ b/runtime/productcache.go @@ -8,6 +8,7 @@ import ( "github.com/genofire/hs_master-kss-monolith/lib/log" ) +// url to the microservice which manage the products var ProductURL string type boolMicroServiceCache struct { @@ -21,6 +22,7 @@ func init() { productExistCache = make(map[int64]boolMicroServiceCache) } +// check on the other microservice if the product exists func ProductExists(id int64) (bool, error) { if cache, ok := productExistCache[id]; ok { return cache.Value, nil diff --git a/test/testrest.go b/test/testrest.go index d2a1383..b493608 100644 --- a/test/testrest.go +++ b/test/testrest.go @@ -1,3 +1,4 @@ +// A little lib to easy create everything for running virtual api package test // Request an easy manager to test REST-API @@ -16,7 +17,7 @@ import ( var srv *http.Server -//Init to initialisieren an API +//initialisieren an API test api func Init(t *testing.T) (assertion *assert.Assertions, router *goji.Mux) { assertion = assert.New(t) database.Open(database.Config{ @@ -35,15 +36,18 @@ func Init(t *testing.T) (assertion *assert.Assertions, router *goji.Mux) { return } +// close just the static webserver (with test files of other microservice) func CloseServer() { srv.Close() } +// close everything func Close() { database.Close() srv.Close() } +// handle a test client session with cookies type Request struct { req *http.Request cookies []*http.Cookie @@ -55,7 +59,7 @@ func NewSession(router *goji.Mux) *Request { return &Request{router: router} } -// JSONRequest send request to router +// send request to router and recieve the api answer func (r *Request) JSONRequest(method string, url string, body interface{}) (jsonResult interface{}, res *http.Response) { jsonObj, _ := json.Marshal(body) req, _ := http.NewRequest(method, url, bytes.NewReader(jsonObj)) @@ -75,7 +79,7 @@ func (r *Request) JSONRequest(method string, url string, body interface{}) (json return } -// Clean to clean the current session +// clean the current session func (r *Request) Clean() { r.cookies = nil }