From 6ec91280b2993e3b3731c71a7d2a762f41f189eb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marko=20Tikvi=C4=87?= Date: Wed, 11 Jan 2017 14:10:26 +0100 Subject: [PATCH] working on documentation --- auth_utility.go | 15 ++++++++---- json_utility.go | 74 +++++++++++++++++++++++++++++---------------------------- list_config.go | 34 +++++++++++++------------- 3 files changed, 65 insertions(+), 58 deletions(-) diff --git a/auth_utility.go b/auth_utility.go index c82de4d..1675b54 100644 --- a/auth_utility.go +++ b/auth_utility.go @@ -16,18 +16,20 @@ const saltSize = 32 const appName = "korisnicki-centar" const secret = "korisnicki-centar-api" +// TokenClaims are JWT token claims. type TokenClaims struct { Username string `json:"username"` Role string `json:"role"` jwt.StandardClaims } +// CredentialsStruct is an instace of username/password values. type CredentialsStruct struct { Username string `json:"username"` Password string `json:"password"` } -// generateSalt returns a random string of 'saltSize' length to be used for hashing. +// generateSalt returns a string of random characters of 'saltSize' length. func generateSalt() (salt string, err error) { rawsalt := make([]byte, saltSize) @@ -42,6 +44,7 @@ func generateSalt() (salt string, err error) { // HashString hashes input string with SHA256 algorithm. // If the presalt parameter is not provided HashString will generate new salt string. +// Returns hash and salt string or an error if it fails. func HashString(str string, presalt string) (hash, salt string, err error) { // chech if message is presalted if presalt == "" { @@ -73,8 +76,8 @@ func HashString(str string, presalt string) (hash, salt string, err error) { return hash, salt, nil } -// CreateAPIToken creates JWT token encoding username, role, -// expiration date and issuer claims in it. +// CreateAPIToken returns JWT token with encoded username, role, expiration date and issuer claims. +// It returns an error if it fails. func CreateAPIToken(username, role string) (string, error) { var apiToken string var err error @@ -100,7 +103,8 @@ func CreateAPIToken(username, role string) (string, error) { return apiToken, nil } -// RefreshAPIToken prolongs JWT token's expiration date. +// RefreshAPIToken prolongs JWT token's expiration date for one week. +// It returns new JWT token or an error if it fails. func RefreshAPIToken(tokenString string) (string, error) { var newToken string tokenString = strings.TrimPrefix(tokenString, "Bearer ") @@ -127,6 +131,7 @@ func RefreshAPIToken(tokenString string) (string, error) { } // ParseAPIToken parses JWT token claims. +// It returns a pointer to TokenClaims struct or an error if it fails. func ParseAPIToken(tokenString string) (*TokenClaims, error) { if ok := strings.HasPrefix(tokenString, "Bearer "); ok { tokenString = strings.TrimPrefix(tokenString, "Bearer ") @@ -147,7 +152,7 @@ func ParseAPIToken(tokenString string) (*TokenClaims, error) { return claims, nil } -// secretFunc returns byte slice of 'secret'. +// secretFunc returns byte slice of API secret keyword. func secretFunc(token *jwt.Token) (interface{}, error) { return []byte(secret), nil } diff --git a/json_utility.go b/json_utility.go index 5457131..eab04a9 100644 --- a/json_utility.go +++ b/json_utility.go @@ -11,7 +11,7 @@ import ( ) var mu = &sync.Mutex{} -var allPayloads []payloadBuff +var payloads []payloadBuff type LangMap map[string]map[string]string @@ -41,6 +41,7 @@ type payloadBuff struct { Fields []Field `json:"fields"` Correlations []CorrelationField `json:"correlationFields"` IdField string `json:"idField"` + // Data can only hold slices of any type. It can't be used for itteration Data interface{} `json:"data"` } @@ -57,35 +58,34 @@ type Payload struct { Data interface{} `json:"data"` } -// NewPayload returs payload for provided table. +// NewPayload returs a payload sceleton for provided table. func NewPayload(r *http.Request, table string) Payload { var pload Payload pload.Method = r.Method + " " + r.URL.Path if table != "" { pload.Params = make(map[string]string, 0) - pload.Lang = loadTranslations(table) - pload.Fields = loadFields(table) - pload.IdField = loadIdField(table) - pload.Correlations = loadCorrelations(table) + pload.Lang = translations(table) + pload.Fields = fields(table) + pload.IdField = id(table) + pload.Correlations = correlations(table) } return pload } -// DeliverPayload writes payload to w. +// DeliverPayload encodes payload to w. func DeliverPayload(w http.ResponseWriter, payload Payload) { json.NewEncoder(w).Encode(payload) payload.Data = nil } -// loadTranslations loads translations for a payload of the given data type. -func loadTranslations(id string) []Translation { - translations := make([]Translation, 0) +// translations returns a slice of translations for a payload/table of ptype type. +func translations(ptype string) []Translation { + var translations []Translation - for _, pload := range allPayloads { - if pload.Type == id { + for _, pload := range payloads { + if pload.Type == ptype { for _, t := range pload.Lang { - //translations[t.Language] = t.FieldsLabels translations = append(translations, Translation{ Language: t.Language, FieldsLabels: t.FieldsLabels, @@ -97,12 +97,12 @@ func loadTranslations(id string) []Translation { return translations } -// loadFields loads fields for a payload of the given data type. -func loadFields(id string) []Field { - fields := make([]Field, 0) +// fields returns a slice of fields for a payload/table of ptype type. +func fields(ptype string) []Field { + var fields []Field - for _, pload := range allPayloads { - if pload.Type == id{ + for _, pload := range payloads { + if pload.Type == ptype { for _, f := range pload.Fields { fields = append(fields, f) } @@ -112,44 +112,46 @@ func loadFields(id string) []Field { return fields } -// loadIdField loads ID field for a payload of the given data type. -func loadIdField(id string) string { - for _, pload := range allPayloads { - if pload.Type == id { +// id returns the name of ID field of a payload/table of ptype type. +func id(ptype string) string { + for _, pload := range payloads { + if pload.Type == ptype { return pload.IdField } } return "" } -// loadCorrelations loads correlations field for a payload of the given data type. -func loadCorrelations(id string) []CorrelationField { - resp := make([]CorrelationField, 0) +// correlations returns a slice of correlation fields for a payload/table of ptype type. +func correlations(ptype string) []CorrelationField { + var corr []CorrelationField - for _, pload := range allPayloads { - if pload.Type == id { - for _, f := range pload.Correlations { - resp = append(resp, f) + for _, pload := range payloads { + if pload.Type == ptype { + for _, c := range pload.Correlations { + corr = append(corr, c) } } } - return resp + return corr } -// InitTables loads all payloads in the memory. +// InitTables loads all payloads in the payloads variable. +// Returns an error if it fails. func InitTables(db *ora.Ses, project string) error { jsonbuf, _ := fetchJSON(db, EqualQuotes(project)) mu.Lock() defer mu.Unlock() - json.Unmarshal(jsonbuf, &allPayloads) - if len(allPayloads) == 0 { + json.Unmarshal(jsonbuf, &payloads) + if len(payloads) == 0 { return errors.New("tables config is corrupt") } return nil } -// fetchJSON fetches JSON configuration file from TABLES_CONFIG table. +// fetchJSON returns a byte slice of JSON configuration file from TABLES_CONFIG table. +// Returns an error if it fails. func fetchJSON(db *ora.Ses, project string) ([]byte, error) { stmt, err := db.Prep(`SELECT JSON_CLOB @@ -180,8 +182,8 @@ func fetchJSON(db *ora.Ses, project string) ([]byte, error) { return bytes, nil } -// DecodeJSON decodes JSON data from r to v and returns any error -// that happens during decoding process. +// DecodeJSON decodes JSON data from r to v. +// Returns an error if it fails. func DecodeJSON(r io.Reader, v interface{}) error { return json.NewDecoder(r).Decode(v) } diff --git a/list_config.go b/list_config.go index 8a1a58f..3f9d2da 100644 --- a/list_config.go +++ b/list_config.go @@ -1,8 +1,6 @@ package webutility -import ( - "gopkg.in/rana/ora.v3" -) +import "gopkg.in/rana/ora.v3" type ListOptions struct { GlobalFilter bool `json:"globalFilter"` @@ -93,7 +91,8 @@ type ListConfig struct { Details ListDetails `json:"details"` } -// GetListConfig returns list configuration for the given object type for the front-end application. +// GetListConfig returns list configuration for the provided object type for the front-end application +// or an error if it fails. func GetListConfig(db *ora.Ses, objType string) (ListConfig, error) { resp := newDefaultList(objType) var err error @@ -115,7 +114,8 @@ func GetListConfig(db *ora.Ses, objType string) (ListConfig, error) { return resp, nil } -// GetListConfigObjectIDField returns ID field for the given object type. +// GetListConfigObjectIDField takes in database connection and an object type and it returns the +// ID field name for the provided object type. func GetListConfigObjectIDField(db *ora.Ses, otype string) string { var resp string var err error @@ -145,7 +145,7 @@ func GetListConfigObjectIDField(db *ora.Ses, otype string) string { return resp } -// newDefaultList returns default configuration for the given object type. +// newDefaultList returns default configuration for the provided object type. func newDefaultList(objType string) ListConfig { list := ListConfig{ ObjectType: objType, @@ -174,7 +174,7 @@ func newDefaultList(objType string) ListConfig { return list } -// setListParams sets the default parameters of the provided configuration list for the given object type. +// setListParams sets the default parameters of the provided configuration list for the provided object type. func setListParams(db *ora.Ses, list *ListConfig, objType string) error { var err error var stmt *ora.Stmt @@ -212,7 +212,7 @@ func setListParams(db *ora.Ses, list *ListConfig, objType string) error { return nil } -// getListNavigation returns list navigation node slice for the given objectType. +// getListNavigation returns list navigation node slice for the provided objectType. func getListNavigation(db *ora.Ses, listObjType string) ([]ListNavNode, error) { resp := make([]ListNavNode, 0) var err error @@ -250,7 +250,7 @@ func getListNavigation(db *ora.Ses, listObjType string) ([]ListNavNode, error) { return resp, nil } -// getListActions returns list actions for the given objectType. +// getListActions returns list actions for the provided object type. func getListActions(db *ora.Ses, objType string) (ListActions, error) { var resp ListActions var err error @@ -286,7 +286,7 @@ func getListActions(db *ora.Ses, objType string) (ListActions, error) { return resp, nil } -// getListFiters returns list filter slice for the given object type. +// getListFiters returns list filter slice for the provided object type. func getListFilters(db *ora.Ses, objType string) ([]ListFilter, error) { resp := make([]ListFilter, 0) filtersFields, err := getFilterFieldsAndPosition(db, objType) @@ -353,7 +353,7 @@ type _filter struct { Type string } -// getFiltersByFilterField returns filter slice for the given filter field. +// getFiltersByFilterField returns filter slice for the provided filter field. func getFiltersByFilterField(db *ora.Ses, filtersField string) ([]_filter, error) { resp := make([]_filter, 0) var err error @@ -386,7 +386,7 @@ func getFiltersByFilterField(db *ora.Ses, filtersField string) ([]_filter, error return resp, nil } -// getFilterDropdownConfig returns dropdown menu for the given filter field. +// getFilterDropdownConfig returns dropdown menu for the provided filter field. func getFilterDropdownConfig(db *ora.Ses, filtersField string) (Dropdown, error) { var resp Dropdown var err error @@ -435,7 +435,7 @@ func sortFilters(filters []ListFilter) { } } -// getListGraph return list graph slice for the given object type. +// getListGraph return list graph slice for the provided object type. func getListGraph(db *ora.Ses, objType string) ([]ListGraph, error) { resp := make([]ListGraph, 0) var err error @@ -470,7 +470,7 @@ func getListGraph(db *ora.Ses, objType string) ([]ListGraph, error) { return resp, nil } -// getListOptions returns list options for the given object type. +// getListOptions returns list options for the provided object type. func getListOptions(db *ora.Ses, objType string) (ListOptions, error) { var resp ListOptions var err error @@ -508,7 +508,7 @@ func getListOptions(db *ora.Ses, objType string) (ListOptions, error) { return resp, nil } -// getListParent returns list parent node slice for the given object type. +// getListParent returns list parent node slice for the provided object type. func getListParent(db *ora.Ses, objType string) ([]ListParentNode, error) { resp := make([]ListParentNode, 0) var err error @@ -542,7 +542,7 @@ func getListParent(db *ora.Ses, objType string) ([]ListParentNode, error) { return resp, nil } -// getListPivot list pivot slice for the given object type. +// getListPivot list pivot slice for the provided object type. func getListPivot(db *ora.Ses, objType string) ([]ListPivot, error) { resp := make([]ListPivot, 0) var err error @@ -577,7 +577,7 @@ func getListPivot(db *ora.Ses, objType string) ([]ListPivot, error) { return resp, nil } -// getListDetails returns list details for the given object type. +// getListDetails returns list details for the provided object type. func getListDetails(db *ora.Ses, objType string) (ListDetails, error) { var resp ListDetails var err error -- 1.8.1.2