{"id":13414112,"url":"https://github.com/syntaqx/cookie","last_synced_at":"2025-12-26T06:02:13.134Z","repository":{"id":246588417,"uuid":"821565392","full_name":"syntaqx/cookie","owner":"syntaqx","description":"Cookies, but with structs, for happiness.","archived":false,"fork":false,"pushed_at":"2024-07-29T05:16:25.000Z","size":377,"stargazers_count":108,"open_issues_count":0,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-07-31T20:53:31.492Z","etag":null,"topics":["cookie","helper","unmarshal"],"latest_commit_sha":null,"homepage":"","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/syntaqx.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","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},"funding":{"github":["syntaqx"]}},"created_at":"2024-06-28T20:51:23.000Z","updated_at":"2024-07-30T17:11:58.000Z","dependencies_parsed_at":"2024-06-28T21:58:14.650Z","dependency_job_id":"e17c4da1-d415-420a-b769-124275b27364","html_url":"https://github.com/syntaqx/cookie","commit_stats":null,"previous_names":["syntaqx/cookie"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntaqx%2Fcookie","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntaqx%2Fcookie/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntaqx%2Fcookie/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/syntaqx%2Fcookie/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/syntaqx","download_url":"https://codeload.github.com/syntaqx/cookie/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243642088,"owners_count":20323954,"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","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":["cookie","helper","unmarshal"],"created_at":"2024-07-30T20:01:58.004Z","updated_at":"2025-12-26T06:02:08.083Z","avatar_url":"https://github.com/syntaqx.png","language":"Go","funding_links":["https://github.com/sponsors/syntaqx"],"categories":["Utilities","公用事业公司"],"sub_categories":["Utility/Miscellaneous","实用程序/Miscellaneous"],"readme":"# cookie\n\n[![Go](https://github.com/syntaqx/cookie/actions/workflows/go.yml/badge.svg)](https://github.com/syntaqx/cookie/actions/workflows/go.yml)\n[![Go Reference](https://pkg.go.dev/badge/github.com/syntaqx/cookie.svg)](https://pkg.go.dev/github.com/syntaqx/cookie)\n[![Go Report Card](https://goreportcard.com/badge/github.com/syntaqx/cookie)](https://goreportcard.com/report/github.com/syntaqx/cookie)\n[![codecov](https://codecov.io/gh/syntaqx/cookie/graph/badge.svg?token=2YEeUinfQe)](https://codecov.io/gh/syntaqx/cookie)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)  \n\n![Social Preview](./.github/repository-open-graph-template.png)\n\nCookies, but with structs, for happiness.\n\n## Overview\n\n`cookie` is a Go package designed to make handling HTTP cookies simple and\nrobust, and simplifying the process of parsing them into your structs. It\nsupports standard data types, custom data types, and signed cookies to ensure\ndata integrity.\n\n## Features\n\n- **Easy to use**: Simple API for managing cookies in your web applications.\n- **Struct-based cookie values**: Easily get cookies into your structs.\n- **Custom type support**: Extend cookie parsing with your own data types.\n- **Signed cookies**: Ensure the integrity of your cookies with HMAC signatures.\n- **No external dependencies**: Just pure standard library goodness.\n\n## Installation\n\n```bash\ngo get github.com/syntaqx/cookie\n```\n\n## Basic Usage\n\nThe `cookie` package provides a `DefaultManager` that can be used to plug and\nplay into your existing applications:\n\n```go\ncookie.Get(r, \"DEBUG\")\ncookie.GetSigned(r, \"Access-Token\")\ncookie.Set(w, \"DEBUG\", \"true\", cookie.Options{})\ncookie.Set(w, \"Access-Token\", \"token_value\", cookie.Options{Signed: true})\ncookie.SetSigned(w, \"Access-Token\", \"token_value\")\n```\n\nOr Populate a struct:\n\n```go\ntype RequestCookies struct {\n  Theme       string    `cookie:\"THEME\"`\n  Debug       bool      `cookie:\"DEBUG,unsigned\"`\n  AccessToken string    `cookie:\"Access-Token,signed\"`\n}\n\nvar c RequestCookies\ncookie.PopulateFromCookies(r, \u0026c)\n```\n\nIn order to sign cookies however, you must provide a signing key:\n\n```go\nsigningKey := []byte(\"super-secret-key\")\ncookie.DefaultManager = cookie.NewManager(\n  cookie.WithSigningKey(signingKey),\n)\n```\n\n\u003e [!TIP]\n\u003e Cookies are stored in plaintext by default (unsigned). A signed cookie is used\n\u003e to ensure the cookie value has not been tampered with. This is done by\n\u003e creating a [HMAC][] signature of the cookie value using a secret key. Then,\n\u003e when the cookie is read, the signature is verified to ensure the cookie value\n\u003e has not been modified.\n\u003e\n\u003e It is still recommended that sensitive data not be stored in cookies, and that\n\u003e HTTPS be used to prevent cookie [replay attacks][].\n\n## Advanced Usage: Manager\n\nFor more advanced usage, you can create a `Manager` to handle your cookies,\nrather than relying on the `DefaultManager`:\n\n```go\nmanager := cookie.NewManager()\n```\n\nYou can optionally provide a signing key for signed cookies:\n\n```go\nsigningKey := []byte(\"super-secret-key\")\nmanager := cookie.NewManager(\n  cookie.WithSigningKey(signingKey),\n)\n```\n\n[HMAC]: https://en.wikipedia.org/wiki/HMAC\n[replay attacks]: https://en.wikipedia.org/wiki/Replay_attack\n\n### Setting Cookies\n\nUse the `Set` method to set cookies. You can specify options such as path,\ndomain, expiration, and whether the cookie should be signed.\n\n```go\nerr := manager.Set(w, \"DEBUG\", \"true\", cookie.Options{})\nerr := manager.Set(w, \"Access-Token\", \"token_value\", cookie.Options{Signed: true})\n```\n\n### Getting Cookies\n\nUse the Get method to retrieve unsigned cookies and GetSigned for signed cookies.\n\n```go\nvalue, err := manager.Get(r, \"DEBUG\")\nvalue, err := manager.GetSigned(r, \"Access-Token\")\n```\n\n### Populating Structs from Cookies\n\nUse `PopulateFromCookies` to populate a struct with cookie values. The struct\nfields should be tagged with the cookie names.\n\n```go\ntype RequestCookies struct {\n  Theme       string    `cookie:\"THEME\"`\n  Debug       bool      `cookie:\"DEBUG,unsigned\"`\n  AccessToken string    `cookie:\"Access-Token,signed\"`\n  NotRequired string    `cookie:\"NOT_REQUIRED,omitempty\"`\n}\n\nvar c RequestCookies\nerr := manager.PopulateFromCookies(r, \u0026c)\n```\n\n\u003e [!TIP]\n\u003e By default, the `PopulateFromCookies` method will return an error if a\n\u003e required cookie is missing. You can use the `omitempty` tag to make a field\n\u003e optional.\n\n### Supporting Custom Types\n\nTo support custom types, register a custom handler with the Manager.\n\n```go\nimport (\n  \"reflect\"\n  \"github.com/gofrs/uuid/v5\"\n  \"github.com/syntaqx/cookie\"\n)\n\n...\n\nmanager := cookie.NewManager(\n  cookie.WithSigningKey(signingKey),\n  cookie.WithCustomHandler(reflect.TypeOf(uuid.UUID{}), func(value string) (interface{}, error) {\n    return uuid.FromString(value)\n  }),\n)\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntaqx%2Fcookie","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsyntaqx%2Fcookie","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsyntaqx%2Fcookie/lists"}