Files
summercms/modules/towel/README.md

94 lines
4.2 KiB
Markdown

# towel
Request-scoped actor, organization, collection and locale values carried through `context.Context`.
`import "git.golem15.com/golem15/summercms/modules/towel"`
**Name:** You carry it everywhere and it marks your spot; it carries the actor, organization and locale through each request.
## Overview
`towel` replaces the request-global state that WinterCMS reads through facades (the current locale, the acting user) with explicit values on the request context. Middleware stores a value once, and any code further down the call chain that receives the context reads it back without a global lookup. [surf](../surf/README.md) sets the locale from `Accept-Language` (or the signed-in user's preferred locale) and the organization for every request, [phrasebook](../phrasebook/README.md) reads the locale when it translates, and [cabana](../cabana/README.md) sets it while localizing admin schemas.
## Role in the framework
A dependency-free leaf for request-scoped values. `surf` sets them, and `phrasebook`, `cabana` and plugin code read them. It replaces WinterCMS facades for per-request state, so it has to be importable by any module without cycles.
Use cases:
- Read the acting user or organization in a service without passing them through every call.
- Translate in the request's locale from deep inside a plugin.
- Set a locale explicitly in a job or a test.
## Features
- Five independent string values, each with a setter and a getter: actor (`towel.WithActor`, `towel.Actor`), organization (`towel.WithOrganization`, `towel.Organization`), collection (`towel.WithCollection`, `towel.Collection`), locale (`towel.WithLocale`, `towel.Locale`) and client address (`towel.WithClientIP`, `towel.ClientIP`).
- Unexported context key types, so no other package can read or overwrite the values by accident.
- Getters return `(value, ok)`: a value that was set to an empty string is distinguishable from one that was never set.
- Nil-safe: a setter given a nil context starts from `context.Background()`, and a getter given a nil context reports `false`.
## Usage
```go src=modules/towel/example_test.go#withAcmeScope
// withAcmeScope tags every request with the organization and collection it serves.
func withAcmeScope(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
ctx := towel.WithOrganization(r.Context(), "acme")
ctx = towel.WithCollection(ctx, "blog")
next.ServeHTTP(w, r.WithContext(ctx))
})
}
```
```go src=modules/towel/example_test.go#listPosts
func listPosts(w http.ResponseWriter, r *http.Request) {
org, _ := towel.Organization(r.Context())
locale, ok := towel.Locale(r.Context())
if !ok {
locale = "en"
}
fmt.Fprintf(w, "posts for %s in %s\n", org, locale)
}
```
```go src=modules/towel/example_test.go#ExampleWithLocale
// surf sets the locale from Accept-Language; here the test sets it.
req := httptest.NewRequest(http.MethodGet, "/api/blog/posts", nil)
req = req.WithContext(towel.WithLocale(req.Context(), "pl"))
rec := httptest.NewRecorder()
withAcmeScope(http.HandlerFunc(listPosts)).ServeHTTP(rec, req)
fmt.Print(rec.Body.String())
// Without a locale the handler falls back to English.
rec = httptest.NewRecorder()
withAcmeScope(http.HandlerFunc(listPosts)).ServeHTTP(rec, httptest.NewRequest(http.MethodGet, "/api/blog/posts", nil))
fmt.Print(rec.Body.String())
// Output:
// posts for acme in pl
// posts for acme in en
```
## API reference
| Identifier | Description |
|------------|-------------|
| `towel.WithActor` / `towel.Actor` | Store and read the acting user or client identifier. |
| `towel.WithOrganization` / `towel.Organization` | Store and read the organization (tenant) the request belongs to. |
| `towel.WithCollection` / `towel.Collection` | Store and read the collection the request operates on. |
| `towel.WithLocale` / `towel.Locale` | Store and read the locale used for translations and localized responses. |
| `towel.WithClientIP` / `towel.ClientIP` | Store and read the request's client address for code below the HTTP layer, such as a token resolver logging a failed attempt. |
## Dependencies
- SummerCMS modules: none.
- Third-party: none.
- Standard library: `context`.
## Testing
```sh
go test ./modules/towel/...
```
The tests exercise plain contexts and need no external services.