README
¶
GoSession
This is quick session for net/http in GoLang.
This package is perhaps the best implementation of the session mechanism, at least it tries to become one.
Important note This package is designed to work with the standard net/http package and has not been tested with other http packages by the developer.
Contents
What are sessions and why are they needed
A session on a site is a good method of identifying a site user.
A session is often used to authorize a user and retain their identity until the user closes the browser page.
While the user is working with the site, he saves cookies with a unique identifier, by this identifier one can distinguish one user from another and the server can store special data for a particular user.
User data received during the session period can be used for authorization, marketing and many other cases when it is necessary to collect, process and analyze data about a specific user.
A session is an efficient method of interacting with a user.
⬆ back to top - ⬆ back to the chapter
How to connect GoSession
In your project folder, initialize the Go-module with the command
go mod init your_app_name
Download and install GoSession
go get github.com/Kwynto/gosession
Now you can add the GoSession package to your Go-code file, for example in main.go
import "github.com/Kwynto/gosession"
⬆ back to top - ⬆ back to the chapter
How to use GoSession
To use the GoSession package, you need to import it into your code.
import "github.com/Kwynto/gosession"
All operations for working with sessions must be called from handlers.
Each time you start working with the session store, you need to call gosession.Start(w *http.ResponseWriter, r *http.Request), since this function returns the identifier of the store and allows you to access the elements of the store through the identifier.
id := gosession.Start(&w, r)
You need to call the gosession.Start(w *http.ResponseWriter, r *http.Request) function from the handler
func rootHandler(w http.ResponseWriter, r *http.Request) {
id := gosession.Start(&w, r) // Get the storage ID for a specific user
html := "<html><head><title>Title</title></head><body>%s</body></html>"
fmt.Fprintf(w, html, id)
}
Alternatively, you can use the gosession.StartSecure(w *http.ResponseWriter, r *http.Request) function instead of gosession.Start(w, r).
The StartSecure() function replaces the session ID each time it is accessed, which reduces the possibility of ID hijacking.
The use of these functions is exactly the same.
id := gosession.StartSecure(&w, r)
You need to call the gosession.StartSecure() function from the handler
func rootHandler(w http.ResponseWriter, r *http.Request) {
id := gosession.StartSecure(&w, r) // Get the storage ID for a specific user
html := "<html><head><title>Title</title></head><body>%s</body></html>"
fmt.Fprintf(w, html, id)
}
Once you have a store ID, you can write variables to the store, read them, and delete them.
Recording is done using the Set(name string, value interface{}) method
id.Set("name variable", anyVariable)
In the handler it looks like this
func writeHandler(w http.ResponseWriter, r *http.Request) {
name := "username"
username := "JohnDow"
id := gosession.Start(&w, r)
id.Set(name, username)
html := "<html><head><title>Title</title></head><body>OK</body></html>"
fmt.Fprint(w, html)
}
Reading is done by Get(name string) interface{} method for one variable
and the GetAll() Session method to read all session variables
anyVariable := id.Get("name variable")
allVariables := id.GetAll()
In the handler it looks like this
func readHandler(w http.ResponseWriter, r *http.Request) {
name := "username"
var username interface{}
id := gosession.Start(&w, r)
username = id.Get(name) // Reading the "username" variable from the session for a specific user
html := "<html><head><title>Title</title></head><body>%s</body></html>"
fmt.Fprintf(w, html, username)
}
or so
func readHandler(w http.ResponseWriter, r *http.Request) {
var tempStr string = ""
id := gosession.Start(&w, r)
allVariables := id.GetAll() // Reading the entire session for a specific client
for i, v := range allVariables {
tempStr = fmt.Sprint(tempStr, i, "=", v, "<br>")
}
html := "<html><head><title>Title</title></head><body>%s</body></html>"
fmt.Fprintf(w, html, tempStr)
}
Removing an entry from a session of a specific client is carried out using the Remove(name string) method
id.Remove("name variable")
In the handler it looks like this
func removeHandler(w http.ResponseWriter, r *http.Request) {
id := gosession.Start(&w, r)
id.Remove("name variable") // Removing a variable from a specific client session
html := "<html><head><title>Title</title></head><body>OK</body></html>"
fmt.Fprint(w, html)
}
Removing the entire session of a specific client is done using the Destroy(w *http.ResponseWriter) method
id.Destroy(&w)
In the handler it looks like this
func destroyHandler(w http.ResponseWriter, r *http.Request) {
id := gosession.Start(&w, r)
id.Destroy(&w) // Deleting the entire session of a specific client
html := "<html><head><title>Title</title></head><body>OK</body></html>"
fmt.Fprint(w, html)
}
GoSession allows you to change its settings with the SetSettings(setings GoSessionSetings) function,
which is used outside of the handler, for example, inside the main() function
var mySetingsSession = gosession.GoSessionSetings{
CookieName: gosession.GOSESSION_COOKIE_NAME,
Expiration: gosession.GOSESSION_EXPIRATION,
TimerCleaning: gosession.GOSESSION_TIMER_FOR_CLEANING,
}
gosession.SetSetings(mySetingsSession) // Setting session preferences
GoSession has 3 constants available for use
const (
GOSESSION_COOKIE_NAME string = "SessionId" // Name for session cookies
GOSESSION_EXPIRATION int64 = 43_200 // Max age is 12 hours.
GOSESSION_TIMER_FOR_CLEANING time.Duration = time.Hour // The period of launch of the mechanism of cleaning from obsolete sessions
)
The remaining functions, types and variables in GoSession are auxiliary and are used only within the package.
⬆ back to top - ⬆ back to the chapter
Examples of using
Example 1:
This is a simple authorization example and it shows the use of the write and read session variables functions, as well as deleting the entire session.
Download the GoSession project to your computer:
git clone https://github.com/Kwynto/gosession.git
Go to the example folder or open this folder in your IDE.
cd ./gosession/pkg/example1
Install GoSession
go get github.com/Kwynto/gosession
Run:
go mod tidy
Start the server:
go run .
Visit site
Example 2:
This example shows a primitive way to collect information about user actions. You can collect any public user data, as well as track user actions, and then save and process this data.
Download the GoSession project to your computer:
git clone https://github.com/Kwynto/gosession.git
Go to the example folder or open this folder in your IDE.
cd ./gosession/pkg/example2
Install GoSession
go get github.com/Kwynto/gosession
Run:
go mod tidy
Start the server:
go run .
Visit site
Now you can follow the links on this site and see how the site saves and shows your browsing history.
Example 3:
This example shows a simple, realistic site that uses the session mechanism.
Download the GoSession project to your computer:
git clone https://github.com/Kwynto/gosession.git
Go to the example folder or open this folder in your IDE.
cd ./gosession/pkg/example3
Install GoSession
go get github.com/Kwynto/gosession
Run:
go mod tidy
Start the server:
go run ./cmd/web/
Visit site
Now you can follow the links on this site.
⬆ back to top - ⬆ back to the chapter
About the package
GoSession has a description of its functionality in a README.md file and internal documentation.
GoSession is tested and has a performance check.
You can use the GoSession tests and documentation yourself.
Download the GoSession project to your computer:
git clone https://github.com/Kwynto/gosession.git
Go to the project folder:
cd ./gosession
Check out the documentation
Look at the documentation in two steps.
First, in the console, run:
godoc -http=:8080
And then in your web browser navigate to the uri:
The godoc utility may not be present in your Go build and you may need to install it
command go get -v golang.org/x/tools/cmd/godoc
For Debian Linux users (Ubuntu, Mint and others): You may need to install the tools with the sudo apt install golang-golang-x-tools command
You can also use Go's standard functionality to view documentation in the console via go doc.
For example:
go doc Start
If your IDE is good enough, then the documentation for functions and methods will be available from your code editor.
Testing
Run tests:
go test -v
Run tests showing code coverage:
go test -cover -v
You can view code coverage in detail in your web browser.
To do this, you need to sequentially execute two commands in the console:
go test -coverprofile="coverage.out" -v
go tool cover -html="coverage.out"
Performance
You can look at code performance tests:
go test -benchmem -bench="." gosession.go gosession_test.go
The slowest of all functions is cleaningSessions(), but this should not scare you, as it is a utility function and is rarely executed. This function does not affect the performance of the entire mechanism, it is only needed to clean up the storage from lost sessions.
⬆ back to top - ⬆ back to the chapter
About the author
The author of the project is Constantine Zavezeon (Kwynto).
You can contact the author by e-mail: kwynto@mail.ru
The author accepts proposals for participation in open source projects,
as well as willing to accept job offers.
If you want to offer me a job, then first I ask you to read this.
Documentation
¶
Overview ¶
This is quick session for net/http in golang. This package is perhaps the best implementation of the session mechanism, at least it tries to become one.
Index ¶
Constants ¶
Variables ¶
This section is empty.
Functions ¶
func SetSetings ¶
func SetSetings(setings GoSessionSetings)
The SetSetings(settings) sets new settings for the session mechanism. setings - gosession.GoSessionSetings public type variable for setting new session settings
Types ¶
type GoSessionSetings ¶
The GoSessionSetings type describes the settings for the session system
type Session ¶
type Session map[string]interface{}
The Session type contains variables defined for session storage for each client.
type SessionId ¶
type SessionId string
The SessionId type is the session identifier
func Start ¶
func Start(w *http.ResponseWriter, r *http.Request) SessionId
The Start(w, r) function starts the session and returns the SessionId to the handler for further use of the session mechanism. This function must be run at the very beginning of the http.Handler
func StartSecure ¶
func StartSecure(w *http.ResponseWriter, r *http.Request) SessionId
The StartSecure(w, r) function starts the session or changes the session ID and sets new cookie to the client. This function must be run at the very beginning of the http.Handler
func (SessionId) Destroy ¶
func (id SessionId) Destroy(w *http.ResponseWriter)
The Destroy(w) SessionId-method to remove the entire client session
func (SessionId) Get ¶
The Get(name) SessionId-method to get a specific client variable from the session system. name - session variable name
func (SessionId) GetAll ¶
The GetAll() SessionId-method to get all client variables from the session system
Source Files