{"id":19772173,"url":"https://github.com/zerodha/simplesessions","last_synced_at":"2025-08-26T00:20:07.060Z","repository":{"id":34429210,"uuid":"143250203","full_name":"zerodha/simplesessions","owner":"zerodha","description":"simplesessions is a Go session management library that is completely agnostic of HTTP libraries and frameworks, backend stores, and even cookie jars.","archived":false,"fork":false,"pushed_at":"2025-07-01T07:35:48.000Z","size":186,"stargazers_count":68,"open_issues_count":1,"forks_count":12,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-08-18T09:47:33.004Z","etag":null,"topics":["session","session-cookie","session-handler","session-management","session-manager","session-store","sessions"],"latest_commit_sha":null,"homepage":"https://pkg.go.dev/github.com/zerodha/simplesessions","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/zerodha.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2018-08-02T06:11:01.000Z","updated_at":"2025-07-01T07:35:52.000Z","dependencies_parsed_at":"2024-06-01T09:42:58.294Z","dependency_job_id":"1d410305-28c2-49f3-8aa2-04761df77391","html_url":"https://github.com/zerodha/simplesessions","commit_stats":{"total_commits":65,"total_committers":7,"mean_commits":9.285714285714286,"dds":"0.29230769230769227","last_synced_commit":"cc187ffc259d257e9ecb0b4f24144c75f08f2543"},"previous_names":["zerodha/simplesessions","vividvilla/simplesessions"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/zerodha/simplesessions","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodha%2Fsimplesessions","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodha%2Fsimplesessions/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodha%2Fsimplesessions/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodha%2Fsimplesessions/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/zerodha","download_url":"https://codeload.github.com/zerodha/simplesessions/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/zerodha%2Fsimplesessions/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":272150887,"owners_count":24882246,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-25T02:00:12.092Z","response_time":1107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["session","session-cookie","session-handler","session-management","session-manager","session-store","sessions"],"created_at":"2024-11-12T05:05:38.969Z","updated_at":"2025-08-26T00:20:07.041Z","avatar_url":"https://github.com/zerodha.png","language":"Go","readme":"\u003ca href=\"https://zerodha.tech\"\u003e\u003cimg src=\"https://zerodha.tech/static/images/github-badge.svg\" align=\"right\" /\u003e\u003c/a\u003e\n\n# simplesessions\nsimplesessions is a \"pure\" Go session library that is completely agnostic of HTTP libraries and frameworks, backend stores, and even cookie jars.\n\n## Why?\nMost session libraries are highly opinionated and hard-wired to work with `net/http` handlers (or other 3rd party libraries like `fasthttp`) and take liberties on how session data should be encoded and stored. simplesessions takes a pragmatic approach, where everything from HTTP request and cookie handling to data encoding and session storage are plugged in as simple callback functions. Moreover, most session libraries treat data as `strings` losing type information. simplessions provides a way to maintain primitive types such as `int`, `string` etc.\n\n## Features\n1. Framework/network library agnostic.\n2. Simple API and with support for primitive data types. Complex types can be stored using own encoding/decoding.\n3. Pre-built redis/postgres/in-memory/securecookie stores that can be separately installed.\n4. Multiple session instances with custom handlers and different backend stores.\n\n## Installation\nInstall `simplesessions` and all [available stores](/stores).\n\n```shell\ngo get -u github.com/zerodha/simplesessions/v3\n\n# Install the requrired store: memory|redis|postgres|securecookie\ngo get -u github.com/zerodha/simplesessions/stores/redis/v3\ngo get -u github.com/zerodha/simplesessions/stores/postgres/v3\n```\n\n# Stores\nSessions can be stored to any backend by implementing the [store](/store.go) interface. The following stores are bundled.\n\n* [redis](/stores/redis)\n* [postgres](/stores/postgres)\n* [in-memory](/stores/memory)\n* [secure cookie](/stores/securecookie)\n\n# Usage\nCheck the [examples](/examples) directory for complete examples.\n\n## Connecting a store\nStores can be registered to a session instance by using `Use` method. Check individual [Stores](#stores) docs for more details.\n\n```go\nsess := simplesessions.New(simplesessions.Options{})\nsess.UseStore(store.New())\n```\n\n## Connecting an HTTP handler\nAny HTTP library can be connected to simplesessions by registering the get and set cookie hooks using `SetCookieHooks()`. The below example shows a simple `net/http` usecase. Another example showing `fasthttp` can be found [here](/examples).\n\n```go\nvar sessMan *simplesessions.Manager\n\nfunc getCookie(name string, r interface{}) (*http.Cookie, error) {\n\t// Get read interface registered using `Acquire` method in handlers.\n\trd := r.(*http.Request)\n\n\t// Send cookie for received cookie name from request.\n\t// Note that other networking libs and frameworks should\n\t// also send back cookie in net/http cookie format.\n\t// If cookie is not found for given cookie name then\n\t// `http.ErrNoCookie` should be returned.\n\t// Cookie name is what you set while creating session manager\n\t// with custom options (`Options.CookieName`). Defaults to `session`.\n\tcookie, err := rd.Cookie(name)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\n\treturn cookie, nil\n}\n\nfunc setCookie(cookie *http.Cookie, w interface{}) error {\n\t// Get write interface registered using `Acquire` method in handlers.\n\twr := w.(http.ResponseWriter)\n\n\t// net/http cookie is returned which can be\n\t// used to set cookie for current request.\n\t// Note that other network libraries or\n\t// framework will also receive cookie as\n\t// net/http cookie and it has to set cookie accordingly.\n\thttp.SetCookie(wr, cookie)\n\treturn nil\n}\n\nfunc handler(w http.ResponseWriter, r *http.Request) {\n\t// Use method `Acquire` to acquire a session before you access the session.\n\t// Acquire takes read, write interface and context respectively.\n\t// Read interface sent to callback registered with get cookie hook\n\t// and write interface is sent to callback registered with write cookie hook\n\t// set using `SetCookieHooks()` method.\n\t//\n\t// Optionally `context` can be sent which is usually request context where acquire\n\t// session will get previously loaded session. This is useful if you have multiple\n\t// middlewares accessing sessions. New sessions will be created in first middleware which\n\t// does `Acquire` and will be reused in other places.\n\t//\n\t// If `Options.EnableAutoCreate` is set to True then if session doesn't exist it will\n\t// be immediately created and returned. Bydefault its set to False so if session doesn't\n\t// exist then `ErrInvalidSession` error is returned.\n\tsess, err := sessMan.Acquire(nil, r, w)\n\n\t// If session doesn't exist then create new session.\n\t// In a traditional login flow you can create a new session once user completes the login flow.\n\tif err == simplesessions.ErrInvalidSession {\n\t\tsess, err = sessMan.NewSession(r, w)\n\t}\n\n\t// Use 'Set` or `SetMulti` to set a field for session.\n\terr = sess.Set(\"somekey\", \"somevalue\")\n\terr = sess.SetMulti(map[string]interface{}{\n\t\t\"k1\": \"v1\",\n\t\t\"k2\": \"v2\",\n\t})\n\n\t// Use `Get` method to get a field from current session. The result will be an interface\n\t// so you can use helper methods like\n\t// `String', `Int`, `Int64`, `UInt64`, `Float64`, `Bytes`, `Bool`.\n\tval, err := sess.String(sess.Get(\"somekey\"))\n\tfmt.Println(\"val=\", val)\n\n\t// Use `GetAll` to get map of all fields from session.\n\t// The result is map of string and interface you can use helper methods to type cast it.\n\tall, err := sess.GetAll()\n\tfmt.Println(\"all=\", all)\n\n\t// Use `GetMulti` to get values for given fields from session.\n\t// The result is map of string and interface you can use helper methods to type cast it.\n\t// If key is not there then store should ideally send `nil` value for given key.\n\tvals, err := sess.GetMulti(\"somekey\", \"someotherkey\")\n\tfmt.Println(\"vals=\", vals)\n\n\t// Use `Delete` to delete a field from session.\n\terr = sess.Delete(\"somekey\")\n\n\t// Use `Clear` to empty the session but to keep the session alive.\n\terr = sess.Clear()\n\n\t// Use `Destroy` to clear session from store and cookie.\n\terr = sess.Destroy()\n\n\tfmt.Fprintf(w, \"success\")\n}\n\nfunc main() {\n\t// Create a session manager with custom options like cookie name,\n\t// cookie domain, is secure cookie etc. Check `Options` struct for more options.\n\tsessMan := simplesessions.New(simplesessions.Options{\n\t\t// If set to true then `Acquire()` method will create new session instead of throwing\n\t\t// `ErrInvalidSession` when the session doesn't exist. By default its set to false.\n\t\tEnableAutoCreate: false,\n\t\tCookie: simplesessions.CookieOptions{\n\t\t\t// Name sets http cookie name. This is also sent as cookie name in `GetCookie` callback.\n\t\t\tName: \"session\",\n\t\t\t// Domain sets hostname for the cookie. Domain specifies allowed hosts to receive the cookie.\n\t\t\tDomain: \"example.com\",\n\t\t\t// Path sets path for the cookie. Path indicates a URL path that must exist in the requested URL in order to send the cookie header.\n\t\t\tPath: \"/\",\n\t\t\t// IsSecure marks the cookie as secure cookie (only sent in HTTPS).\n\t\t\tIsSecure: true,\n\t\t\t// IsHTTPOnly marks the cookie as http only cookie. JS won't be able to access the cookie so prevents XSS attacks.\n\t\t\tIsHTTPOnly: true,\n\t\t\t// SameSite sets allows you to declare if your cookie should be restricted to a first-party or same-site context.\n\t\t\tSameSite: http.SameSiteDefaultMode,\n\t\t\t// Expires sets absolute expiration date and time for the cookie.\n\t\t\t// If both Expires and MaxAge are sent then MaxAge takes precedence over Expires.\n\t\t\t// Cookies without a Max-age or Expires attribute – are deleted when the current session ends\n\t\t\t// and some browsers use session restoring when restarting. This can cause session cookies to last indefinitely.\n\t\t\tExpires: time.Now().Add(time.Hour * 24),\n\t\t\t// Sets the cookie's expiration in seconds from the current time, internally its rounder off to nearest seconds.\n\t\t\t// If both Expires and MaxAge are sent then MaxAge takes precedence over Expires.\n\t\t\t// Cookies without a Max-age or Expires attribute – are deleted when the current session ends\n\t\t\t// and some browsers use session restoring when restarting. This can cause session cookies to last indefinitely.\n\t\t\tMaxAge: time.Hour * 24,\n\t\t},\n\t})\n\n\t// Create a new store instance and attach to session manager\n\tsessMan.UseStore(memory.New())\n\t// Register callbacks for read and write cookie.\n\t// Get cookie callback should get cookie based on cookie name and\n\t// sent back in net/http cookie format.\n\t// Set cookie callback should set cookie it received for received cookie name.\n\tsessMan.SetCookieHooks(getCookie, setCookie)\n\n\t// Initialize the handler.\n\thttp.HandleFunc(\"/\", handler)\n}\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodha%2Fsimplesessions","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzerodha%2Fsimplesessions","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzerodha%2Fsimplesessions/lists"}