Skip to content

Commit

Permalink
move: readme doc / examples to package godoc / examples
Browse files Browse the repository at this point in the history
vipul-sharma20 committed Jun 28, 2022
1 parent 47ca2dd commit 1b29d48
Showing 7 changed files with 175 additions and 181 deletions.
175 changes: 3 additions & 172 deletions Readme.md
Original file line number Diff line number Diff line change
@@ -1,176 +1,7 @@
# vcore

Golang Common utility functions
Golang Common utility functions.

## vcore/errors
Documentation [here][doc]

The errors package is a wrapper around the brilliant [pkg/errors](https://github.com/pkg/errors) library.
The major difference between [pkg/errors](https://github.com/pkg/errors) and this library is support for the following:

* Wrapping of an error into a custom error so as to add a stacktrace.
* Allows creation of errors with a stack which have no cause(nil cause).
* Every error created supports the `fatality` interface which is meant to inform us if the error is fatal or not.
* Every error created supports the `tagged` interface which returns any tags(`map[string]string`) associated with an error.
* The stacktrace of the error will return the stactrace starting from the deepest cause.

### Basic Usage

#### Create Error without cause:

This error is non-fatal. As marked by the last bool flag.

```go
errors.NewError("Error without a cause", nil, false)
```

#### Create Error with a cause:

```go
cause := errors.NewError("Error without a cause", nil, false)
errWithCause := errors.NewError("Error with a cause", cause, false)
```

#### Check if an error is fatal

```go
cause := errors.NewError("Error without a cause", nil, false)
if cause.Fatal{
fmt.Println("This error is fatal.")
}
```

#### Get the stacktrace of the error and print it:

```go
cause := errors.NewError("Error without a cause", nil, false)
errWithCause := errors.NewError("Error with a cause", cause, false)
fmt.Println(errWithCause.Stacktrace())
```

Alternatively,

```go
cause := errors.NewError("Error without a cause", nil, false)
errWithCause := errors.NewError("Error with a cause", cause, false)
errWithCause.PrintStackTrace()
```

## vcore/crypto

The crypto module is meant to help services implement various cryptographic functions with ease.
Current features include -

1. Encryption of []byte and string. Supported techniques -
- AES-256-GCM
2. Decryption of []byte. Supported techniques -
- AES-256-GCM

AES-256 is PCI DSS compliant, as it is a recognised industry standard encryption.

This module exports the following functions -
1. EncryptBytes: Encrypt a bytearray. Example usage -
``` go
x := []byte("hello world")
enc := EncryptBytes(x)
fmt.Println(enc)
```
2. EncryptString: Encrypt a string. Example usage -
``` go
x := "hello world"
enc := EncryptString(x)
fmt.Println(enc)
```
3. DecryptBytes: Decrypt a bytearray. Example usage -
``` go
y := []byte{180, 27, 0, 28, 249, 65, 157, 217, 78, 134, 227, 25, 135, 180, 197, 2, 170, 235, 128, 7, 99, 202, 202, 210, 149, 75, 209, 157, 114, 129, 236, 206, 62, 132, 175, 42, 26, 224, 26}
p := DecryptBytes(y)
fmt.Println(string(p))
```

### Key management

Vault is used to generate the encrypted data key when an environment/client is set up. The encrypted data key is passed to vcore as an environment variable.
Vcore then calls Vault APIs to decrypt the data key and proceed with the encryption/decryption.

### Environment Variables needed

The following environment variables are needed to utilize the crypto module -
``` sh
export VAULT_URI="http://localhost:8200"
export VAULT_ROLE_ID="****"
export VAULT_SECRET_ID="****"
export VAULT_APPROLE_MOUNTPATH="approle"
export ENCRYPTED_DATA_KEY="****"
export VAULT_DATA_KEY_NAME="datakey-name"
```

Note: the above environment variables are just examples, set up vault and replace the actual values above.

## vcore/log

The log package is a basic wrapper on the standard log package in Go's stdlib.
The log package logs to STDOUT and supports log levels(`int`).

The log levels currently supported are:

* 0 - ERROR
* 1 - WARN
* 2 - INFO
* 3 - DEBUG
* 4 - TRACE

To log using this package, one needs to use an instance of the `log.Logger` struct.

The `log.Logger` struct supports the following methods which can be used to log messages:

* `log.Trace(args ...interface{})`
* `log.Tracef(format string, args ...interface{})`
* `log.Debug(args ...interface{})`
* `log.Debugf(format string, args ...interface{})`
* `log.Info(args ...interface{})`
* `log.Infof(format string, args ...interface{})`
* `log.Warn(args ...interface{})`
* `log.Warnf(format string, args ...interface{})`
* `log.Error(err error, args ...interface{})`
* `log.Errorf(err error, format string, args ...interface{})`

Each of these methods are wrappers that correspond to a log level. This enforces the user to take cognizance of the log
level of whatever they are attempting to log.

To set the log level on a `log.Logger` struct, make use of the `log.SetLevel(level int)` function.

### Default Logger

To quickly start logging messages, make use of the default logger(default level `WARN`). This can be done by simply
calling the functions stated above.

Eg. To add a trace log

```go
headers := make(map[string]string)
for k := range req.Header {
headers[strings.ToLower(k)] = req.Header.Get(k)
}
log.SetLevel(log.DEBUG)
log.Tracef("Headers: %s", headers)
```

Here, we directly make use of the default logger. Please note, since the log level is set to DEBUG here, this trace message will not be logged.

### Custom Logger

```go
customLogger := log.Logger{log.DEBUG}
customLogger.Debug("This is a debug message")
```

## vcore/transport

### vcore/transport/amqp
### vcore/transport/redis

## vcore/utils

The vcore/utils package contains basic utility functions and file utilies for downloading, reading and writing to files.

## vcore/vorm
[doc]: https://pkg.go.dev/github.com/Vernacular-ai/vcore
12 changes: 9 additions & 3 deletions crypto/decrypt.go
Original file line number Diff line number Diff line change
@@ -87,10 +87,16 @@ func DecryptB64ToBytesWithDataKey(data string, dataKey string, clientId string)
Decryption functions without data key
*/

// Decrypt a byte array
// Deprecated - to be removed in future releases - use DecryptBytesWithDataKey instead
// Decrypt a byte array Deprecated - to be removed in future releases - use
// DecryptBytesWithDataKey instead
//
// This function accepts an incoming byte array, decrypts it using AES-256 decryption and returns the result in bytes
// This function accepts an incoming byte array, decrypts it using AES-256
// decryption and returns the result in bytes
//
// Example usage:
// y := []byte{180, 27, 0, 28, 249, 65, 157, 217, 78, 134, 227, 25, 135, 180, 197, 2, 170, 235, 128, 7, 99, 202, 202, 210, 149, 75, 209, 157, 114, 129, 236, 206, 62, 132, 175, 42, 26, 224, 26}
// p := DecryptBytes(y)
// fmt.Println(string(p))
func DecryptBytes(cipherData []byte) (data []byte, err error) {
gcm, err := newCipherAESGCMObject("", "")
if gcm == nil || err != nil {
20 changes: 16 additions & 4 deletions crypto/encrypt.go
Original file line number Diff line number Diff line change
@@ -67,10 +67,16 @@ func EncryptToB64StringWithDataKey(data string, dataKey string, clientId string)
Encryption functions without data key
*/

// Encrypt a byte array
// Deprecated - to be removed in future releases - use EncryptBytesWithDataKey instead
// Encrypt a byte array (deprecated)
// to be removed in future releases, use EncryptBytesWithDataKey instead
//
// This function accepts an incoming byte array, encrypts it using AES-256 decryption and returns the result in bytes
// This function accepts an incoming byte array, encrypts it using AES-256
// decryption and returns the result in bytes
//
// Example usage:
// x := []byte("hello world")
// enc := EncryptBytes(x)
// fmt.Println(enc)
func EncryptBytes(data []byte) (encryptedBytes []byte, err error) {
gcm, err := newCipherAESGCMObject("", "")
if gcm == nil || err != nil {
@@ -94,7 +100,13 @@ func EncryptBytes(data []byte) (encryptedBytes []byte, err error) {

// Encrypt a byte array
//
// This function accepts an incoming string, encrypts it using EncryptBytes func and returns the result in bytes
// This function accepts an incoming string, encrypts it using EncryptBytes
// func and returns the result in bytes
//
// Example usage:
// x := "hello world"
// enc := EncryptString(x)
// fmt.Println(enc)
func EncryptString(data string) (byteData []byte, err error) {
// Convert incoming string to bytes
byteData = []byte(data)
34 changes: 33 additions & 1 deletion crypto/main.go
Original file line number Diff line number Diff line change
@@ -1,4 +1,36 @@
// A module to help with cryptographic requirements like encryption and hashing
// The crypto module is meant to help services implement various cryptographic
// functions with ease.
//
// Current features
//
// 1. Encryption of []byte and string.
//
// Supported techniques: AES-256-GCM
//
// 2. Decryption of []byte.
//
// Supported techniques: AES-256-GCM
//
// AES-256 is PCI DSS compliant, as it is a recognised industry standard
// encryption.
//
// Key management
//
// Vault is used to generate the encrypted data key when an environment/client is set up. The encrypted data key is passed to vcore as an environment variable.
// Vcore then calls Vault APIs to decrypt the data key and proceed with the encryption/decryption.
//
// Environment Variables needed
//
// The following environment variables are needed to utilize the crypto module:
//
// export VAULT_URI="http://localhost:8200"
// export VAULT_ROLE_ID="****"
// export VAULT_SECRET_ID="****"
// export VAULT_APPROLE_MOUNTPATH="approle"
// export ENCRYPTED_DATA_KEY="****"
// export VAULT_DATA_KEY_NAME="datakey-name"
//
// Note: the above environment variables are just examples, set up vault and replace the actual values above.
package crypto

import (
46 changes: 46 additions & 0 deletions errors/errors.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,49 @@
// The errors package is a wrapper around the brilliant
// https://github.com/pkg/errors library. The major difference between
// https://github.com/pkg/errors and this library is support for the following:
//
// • Wrapping of an error into a custom error so as to add a stacktrace.
//
// • Allows creation of errors with a stack which have no cause(nil cause).
//
// • Every error created supports the `fatality` interface which is meant to inform us if the error is fatal or not.
//
// • Every error created supports the `tagged` interface which returns any tags(`map[string]string`) associated with an error.
//
// • The stacktrace of the error will return the stactrace starting from the deepest cause.
//
// Create Error without cause
//
// This error is non-fatal. As marked by the last bool flag.
//
// errors.NewError("Error without a cause", nil, false)
//
// Create Error with a cause
//
// Embedding a cause with the error.
// cause := errors.NewError("Error without a cause", nil, false)
// errWithCause := errors.NewError("Error with a cause", cause, false)
//
// Check if an error is fatal
//
// Sample below:
// cause := errors.NewError("Error without a cause", nil, false)
// if cause.Fatal{
// fmt.Println("This error is fatal.")
// }
//
// Get the stacktrace of the error and print it
//
// Sample below:
// cause := errors.NewError("Error without a cause", nil, false)
// errWithCause := errors.NewError("Error with a cause", cause, false)
// fmt.Println(errWithCause.Stacktrace())
//
// Alternatively,
//
// cause := errors.NewError("Error without a cause", nil, false)
// errWithCause := errors.NewError("Error with a cause", cause, false)
// errWithCause.PrintStackTrace()
package errors

import (
66 changes: 66 additions & 0 deletions log/levels.go
Original file line number Diff line number Diff line change
@@ -1,3 +1,69 @@
// The log package is a basic wrapper on the standard log package in Go's
// stdlib. The log package logs to STDOUT and supports log levels(int).
//
// Log levels
//
// • 0 - ERROR
//
// • 1 - WARN
//
// • 2 - INFO
//
// • 3 - DEBUG
//
// • 4 - TRACE
//
// To log using this package, one needs to use an instance of the log.Logger
// struct.
//
// The log.Logger struct supports the following methods which can be used to
// log messages:
//
// log.Trace(args ...interface{})
// log.Tracef(format string, args ...interface{})
//
// log.Debug(args ...interface{})
// log.Debugf(format string, args ...interface{})
//
// log.Info(args ...interface{})
// log.Infof(format string, args ...interface{})
//
// log.Warn(args ...interface{})
// log.Warnf(format string, args ...interface{})
//
// log.Error(err error, args ...interface{})
// log.Errorf(err error, format string, args ...interface{})
//
// Each of these methods are wrappers that correspond to a log level. This
// enforces the user to take cognizance of the log level of whatever they are
// attempting to log.
//
// To set the log level on a log.Logger struct, make use of the
// log.SetLevel(level int) function.
//
// Default Logger
//
// To quickly start logging messages, make use of the default logger(default
// level WARN). This can be done by simply calling the functions stated above.
//
// Eg. To add a trace log
//
// headers := make(map[string]string)
// for k := range req.Header {
// headers[strings.ToLower(k)] = req.Header.Get(k)
// }
// log.SetLevel(log.DEBUG)
// log.Tracef("Headers: %s", headers)
//
// Here, we directly make use of the default logger. Please note, since the log
// level is set to DEBUG here, this trace message will not be logged.
//
// Custom Logger
//
// Sample code to create a custom logger
//
// customLogger := log.Logger{log.DEBUG}
// customLogger.Debug("This is a debug message")
package log

import (
Loading

0 comments on commit 1b29d48

Please sign in to comment.