Site kurmak18 dk okuma
Middleware ve kendi API'niz
app.Use ile standart net/http middleware'leri, collage.Vary ile bir header'a bağlı cache key'leri ve app.Handle ile kendi http.Handler'ınız.
collage page render eder. Bir Go programının HTTP üzerinden yaptığı diğer işleri, yani API'yi, authentication'ı, dil seçimini ve rate limiting'i her zamanki gibi kendiniz yazarsınız. Bu kodu iki noktadan birine bağlarsınız:
- Kendi handler'ınıza gelenler dışında her request'in etrafında çalışan middleware'e.
- Bir prefix'in altındaki her request'e cevap veren ve kendi middleware'ini getiren kendi handler'ınıza.
Middleware: app.Use
if err := app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("X-Frame-Options", "DENY")
next.ServeHTTP(w, r)
})
}); err != nil {
return err
}
Middleware standart func(http.Handler) http.Handler imzasına sahiptir. Bu yüzden net/http için yazılmış her middleware hiç değişmeden çalışır. İlk register edilen middleware en dıştakidir. collage add middleware loadUser bir middleware yazar ve onu var olanlardan sonra register eder.
Diğer bütün register işlemleri gibi bu da uygulama başlamadan önce yapılmalıdır. Uygulama başladıktan sonra app.Usecollage.ErrAppStarted döner.
Middleware'in nerede çalıştığıyla ilgili iki nokta var:
- Routing'den önce. Middleware her request'i görür: page'leri, document'ları, action'ları, mount edilmiş static dosyaları, bir plugin'in handler'larını ve
WithMiddlewareile mount edilmiş bir handler'ı. 404 ile biten request'ler de buna dahildir. Middleware bir request'e 401 ya da redirect ile kendisi cevap verebilir. Bu durumda arkasındaki hiçbir şey çalışmaz. Düzapp.Handleile mount edilmiş bir handler bunun istisnasıdır: ona hiçbir middleware olmadan cevap verilir (aşağıda). - Framework'ün koruması içinde. Middleware, collage'ın span'i, metric'leri ve panic recovery'si içinde çalışır.
app.Handler()'ı kendi middleware'inizle sarmaktan farkı budur. Middleware'inizdeki bir panic bağlantıyı koparmaz, normal hata yolunda sıradan bir 500'e dönüşür. Middleware'in kendisinin cevap verdiği bir request de diğer request'ler gibi sayılır.
Plugin'lerin middleware'i ve sizinki
Bir plugin'in middleware'i, plugin'in register edildiği yerde register edilmiş sayılır. Config.Plugins içindeki plugin'ler collage.New'da register edilir. Bu yüzden onların middleware'i app.Use ile eklenen her şeyin dışındadır ve kendi aralarında liste sırasıyla çalışır.
Sizin middleware'iniz de bu sayede onların request context'ine koyduklarını okur: session'ı, bir flash mesajını. Giriş yapmış kullanıcıyı her request'te bir kez yüklemek tek bir middleware'dir:
app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
id := session.FromContext(r.Context()).Get(session.UserKey)
user, err := users.Active(r.Context(), id) // devre dışı bir hesap için nil
if err != nil {
http.Error(w, "unavailable", http.StatusServiceUnavailable)
return
}
next.ServeHTTP(w, r.WithContext(withUser(r.Context(), user)))
})
})
Sizin middleware'inizin koyduğunu okuması gereken bir plugin, örneğin o kullanıcıya göre sınırlama yapan bir rate limit, ondan sonra app.RegisterPlugin ile register edilir. Middleware'i çağrının yapıldığı yere girer: kendisinden önce app.Use ile eklenenlerin içine, sonra eklenenlerin dışına.
app.Use(loadUser)
app.RegisterPlugin(ratelimit.New(ratelimit.Options{KeyFunc: userID}))
RegisterPlugin, template fonksiyonu ekleyen bir plugin'i reddeder. Böyle bir plugin Config.Plugins içinde olmalıdır.
Bir plugin'in bir stream üzerinden gönderdiği fragment (elagoht/live, elagoht/websocket) da bu zincirden geçer, fragment'in kendi path'ine gelen bir request olarak: /admin/'i koruyan bir middleware /admin/stats'ı /_live/stream/?f=/admin/stats'tan uzak tutar, next'i çağırmak yerine cevap veren bir middleware o okuyucunun fragment'i almasını engeller ve bir rate limit her push'u sayar. Stream'in kendi middleware'inin context'e koyduğu şey taşınmaz; middleware'iniz fragment'in path'i için yeniden çalışır. Bkz. Plugin yazmak.
Path'ler önce temizlenir
Dot segment'ler ya da çift slash içeren bir path (/a/../b, /a//b, /a/./b), middleware ve plugin'ler dahil hiçbir şey onu okumadan önce temiz yazımına redirect edilir. GET ve HEAD için 301, body taşıyan bir metot için 308 kullanılır; query korunur.
Bu yüzden /_collage/'ı atlayan ya da /admin/'i koruyan bir middleware /_collage/../admin ile hiç karşılaşmaz. Bir prefix kontrolü, router'ın route edeceği path'in kontrolüdür.
Encode edilmiş bir slash router için bir ayırıcı değildir. Bu yüzden:
%2Fiçeren bir path hiçbir route'a ulaşmaz ve router ona 404 ile cevap verir.- Aynı zamanda temiz olmayan bir path (
/blog/%2Fhello)/blog/hello'ya temizlenmez; middleware'iniz çalışmadan önce 404 ile cevaplanır. - Middleware'iniz decode edilmiş
r.URL.Path'i okur ve orada/public%2Fsecret,/public/secret'tir.
Bunların hiçbiri bir route'a ulaşmaz, ama metrikleriniz onları görür. Temiz path redirect'i, temizlenmesi gereken bir path'teki encoded slash için 404 ve hiçbir route'un asla eşleşemeyeceği bir path için router'ın 404'ü (/a%2fb, bir NUL, bozuk percent-encoding), tarayıcı bot'unun gönderdiği path yerine sınırlı bir etiket altında, diğer her request gibi süreleri ölçülür, trace edilir ve sayılır: collage.RouteInfo tür olarak "rejected", ad olarak "normalise" bildirir, Metrics.HTTPResponse'a boş bir path verilir ve request span'i http.path taşımaz. Bir %2f 404'ü decode edilmiş path'i altında sayılmaz.
Sondaki slash router'ındır, middleware'in değil
Her route'un tek bir yazımı vardır ve router öbürünü yönlendirir; ama bunu sizin middleware'inizden sonra yapar, middleware path'i geldiği gibi görür. Bir page'in öbür yazımı kendi tek yazımına 301 olur; bir document'ınki de öyle, bir action'ınki ise method'u ve body'yi koruyan bir 308 olur. Bu yüzden /admin/delete/'e post edilen bir form /admin/delete'e yeniden post edilir. Document'lar ve action'lar, app.URL ve {{actionURL}}'in kurduğu gibi, her iki TrailingSlash modunda da sondaki slash olmadan yazılır; yalnızca page'ler Config.TrailingSlash'i izler.
Belirli bir path'i koruyan bir middleware için sonuç şudur: kanonik yazımı karşılaştırın ya da önce slash'i kırpın (strings.TrimSuffix(r.URL.Path, "/")) ve mümkün olduğunda /admin/ gibi bir prefix tercih edin. Yalnızca "/admin/delete" üzerinden yapılan bir kontrol /admin/delete/ ile atlatılır: handler o yazımda çalışmaz, ama middleware yine de gelen request'i değerlendirir.
Body middleware'den önce sınırlanır
Bir request'in body'si, ilk middleware çalışmadan önce sınırlanır. Sınır, request'in yönlendirildiği action'ın limitidir; diğer her şey için Server.MaxBodyBytes'tır.
- Body'yi okuyan bir middleware (bir signature kontrolü, bir logger, form'u parse eden bir method override) onu sınırlı olarak okur.
- Body'si bir middleware tarafından limitinin ötesine kadar okunmuş bir action
413ile cevap verir. Middleware body'yi buffer'layıp yerine yeni bir reader koymuş olsa da (io.ReadAll, ardındanio.NopCloser) böyledir. app.Handleile mount edilmiş bir handler'a dokunulmaz. Bir plugin'inHost.Handleprefix'i iseServer.MaxBodyBytesile sınırlanır: middleware'in içinde çalışır; bu yüzden body'si, middleware onu okumadan önce sınırlanır.
Body, uygulamada middleware olsun olmasın sınırlanır.
Data handler'lara değer aktarmak
Middleware'in request'in context'ine koyduğu değerleri data handler'lar ctx olarak alır. Oturum açmış bir kullanıcı, bir feature flag ya da bir tenant, ona ihtiyaç duyan fragment'lere bu yolla ulaşır:
type userKey struct{}
app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if user, ok := sessions.User(r); ok {
r = r.WithContext(context.WithValue(r.Context(), userKey{}, user))
}
next.ServeHTTP(w, r)
})
})
func accountData(ctx context.Context, rc *collage.RenderContext) (accountView, []string, error) {
user, ok := ctx.Value(userKey{}).(User)
if !ok {
return accountView{}, nil, nil // signed out: the fragment renders its signed-out state
}
return accountView{Name: user.Name}, nil, nil
}
Cache'e dikkat edin. Kullanıcıya göre farklı render edilen bir page URL'ye göre cache'lenmemelidir. Aksi hâlde ilk okuyucunun gördüğü versiyon herkese gösterilir. İki yol var:
- Böyle bir page'i dynamic bırakın, yani ona
Static()ya daIncremental(ttl)vermeyin (data handler'ı olan ve strateji tanımlamayan bir page zaten dynamic'tir). - Ya da neye göre değiştiğini aşağıda anlatılan
collage.Varyile cache'e bildirin.
Cache'lenmiş bir render ne okuyucunun cookie'lerini ve credential'larını, ne de middleware'inizin context'e koyduğu değerleri görür (paylaşılan bir render neyi görür): yanlışlıkla cache'lediğiniz kullanıcıya özel bir page — userKey değeri gizlendiği için — ilk okuyucunun hesabını herkese göstermek yerine herkese oturum kapalıymış gibi render edilir. Onu dynamic bırakın.
Static export request olmadan render eder, bu yüzden yazdığı dosyalar için hiçbir middleware çalışmaz. Context'ten değer okuyan bir data handler, bu değer olmadığında da doğru çalışmalıdır. Oturum açmamış bir okuyucu için bunu zaten yapması gerekir.
Build ardından her dosyanın header'larını handler üzerinden yakalayabilir ve bu request'ler middleware'den geçer:
- Trafiği sayan ya da sınırlayan bir middleware,
collage.IsCapture(r.Context())true olduğunda request'i atlar. - Header set eden middleware ise onu her zamanki gibi işler.
Bir header'a bağlı içerik: collage.Vary
Page cache'in key'i URL'dir. İçeriği bir request header'ına bağlı olan cache'lenmiş bir page, ilk hangi versiyonu render edildiyse onu herkese sunar. Bu header Accept-Language, bir cihaz sınıfı ya da bir A/B grubu olabilir. Middleware'den çağrılan collage.Vary, cache key'ine yeni bir boyut ekler:
app.Use(func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
lang := "en"
if strings.HasPrefix(r.Header.Get("Accept-Language"), "tr") {
lang = "tr"
}
if err := collage.Vary(r, "Accept-Language", lang); err != nil {
app.Logger().Error("vary", "error", err)
}
next.ServeHTTP(w, r)
})
})
Bir fragment'in data handler'ı değeri collage.Varied ile geri okur:
func languageData(ctx context.Context, rc *collage.RenderContext) (string, []string, error) {
lang, _ := collage.Varied(ctx, "Accept-Language") // "tr" or "en"
return greeting(lang), nil, nil
}
- Key'e ham header değil, sizin çözümlediğiniz değer girer. Tarayıcılar tercihlerini yüz farklı şekilde yazar:
tr-TR,tr;q=0.9,tr,tr-TR. Bunların hepsi aynı page'dir. Header'ı, page'lerinizin gerçekten farklılaştığı birkaç değere indirin. Cache de o sayıda entry tutar. AslaCookie'nin ya daAuthorization'ın kendisine göre vary etmeyin: bu değer memory'de tutulur ve her warm render ile yeniden gönderilir. - Değeri context'ten değil,
collage.Variedile okuyun. Cache'lenebilir bir page'de tek bir render birçok okuyucuya sunulur. Bu yüzden middleware'inizincontext.WithValueile request context'ine koyduğu bir değer o render'dan gizlenir: aksi hâlde ilk okuyucunun değeri olur ve geri kalan herkes için donar. BirVarydeğeri okunabilir çünkü key'in içindedir ve her değerin kendi cache'lenmiş page'i vardır. Bkz. paylaşılan bir render neyi görür. - Header'ın adı response'un
Varyheader'ına eklenir. Böylece sizinle okuyucu arasındaki bir CDN ya da proxy de versiyonları birbirinden ayrı tutar. Bu header yalnızca public olarak cache'lenebilen response'larda set edilir.no-storebir response'ta ayrı tutulacak bir şey yoktur. Header'ın adı, middleware'inizin yazdığı birVary'nin yanına eklenir, onun yerine geçmez. Vary'yi middleware'den çağırın. Middleware bittiğinde ve routing başladığında bildirimler kapanır. Bu, her route için geçerlidir: cache'lenen ya da cache'lenmeyen bir page, bir document, bir action, bir mount ya da birapp.Handlehandler'ı. Routing'den sonra, örneğin bir data handler'dan çağrılırsaVaryçalışıyormuş gibi yapmaz,collage.ErrVaryTooLatedöner. collage'ın sunmadığı bir request'te çağrılırsacollage.ErrVaryOutsideRequestdöner.- Middleware'inizin set ettiği bir cookie response'u private yapar. Response'u, cache header'ları yazıldığında zaten bir
Set-Cookietaşıyan cache'lenebilir bir pageCache-Control: private, no-storeile veVaryolmadan gönderilir; böylece bir CDN, bir okuyucunun cookie'sini herkes için tutmaz. Page burada yine cache'lenir; bkz. Caching. Her request'te cookie set eden bir middleware her page'i CDN'de private yapar: onu yalnızca gerektiği yerde set edin. - Aynı header'ı iki kez bildirirseniz son değer geçerli olur.
Dil seçimi de bu yolla yapılır. collage locale'i yalnızca URL'den seçer, Accept-Language'ı okumayı size bırakır. Tarayıcıyı middleware'den /tr'ye redirect edebilirsiniz. Ya da her dil için tek bir URL render edip bunu Vary ile bildirebilirsiniz. Ayrıntılar için Link'ler ve locale'ler sayfasına bakın.
Kendi handler'ınız: app.Handle
api := http.NewServeMux()
api.HandleFunc("GET /api/users/{id}", getUser)
api.HandleFunc("POST /api/users", createUser)
if err := app.Handle("/api/", api); err != nil {
return err
}
Path'i prefix ile başlayan her request, path'i değiştirilmeden handler'ınıza gider. Yani getUser/api/users/42'yi görür. Handler'ınız farklı bir path bekliyorsa onu http.StripPrefix ile sarın.
Herhangi bir http.Handler kullanabilirsiniz: http.ServeMux, chi, bir gRPC gateway ya da bir reverse proxy.
collage bu handler'a hiçbir şey eklemez. Handler'ın neyi kabul edeceğine, ne kadarını okuyacağına ve neyi cache'leyeceğine siz karar verirsiniz.
| Handler'ın almadıkları | Handler'ın her request gibi aldıkları |
|---|---|
| request forgery kontrolü | plugin'lerin request hook'ları |
| body boyutu limiti | span ve metric'ler |
| cache | panic koruması |
sizin ya da bir plugin'in middleware'i (WithMiddleware() ile mount edilmedikçe) | temiz path'e redirect ve encode edilmiş slash için 404 |
temel X-Content-Type-Options ve X-Frame-Options header'ları | |
| graceful shutdown sırasında bitmesinin beklenmesi |
Handler'ın döndüğü bir 5xx, plugin'lerin error hook'larına collage.ErrHandlerFailed olarak bildirilir. 4xx cevapları ise handler'ın kendi sorumluluğundadır.
İstemedikçe middleware yok
app.Handle ile mount edilmiş bir handler için hiçbir middleware çalışmaz: ne app.Use ile eklenenler ne de herhangi bir plugin'inki. Session, flash, i18n, consent, secure, ratelimit, basicauth, fail2ban, accesslog, redirects, tenant, compress ve development toolbar'ı da buna dahildir.
Handler sizin, middleware'i de sizin. Bir API'nin authentication konusunda kendi fikri vardır: sitenin session cookie'si değil, bir bearer token. Kendi rate limit'i ve kendi hata formatı da vardır. Sitenin consent banner'ı, development toolbar'ı ya da Vary: Cookie header'ı da onun istediği şeyler değildir. Bu yüzden handler'ı, collage olmadan da yapacağınız gibi, istediği middleware'lerle sarın:
api := http.NewServeMux()
api.HandleFunc("GET /api/users/{id}", getUser)
// requireToken is yours, below; perClientLimit stands for any net/http rate
// limiter — golang.org/x/time/rate behind a map, httprate, tollbooth.
if err := app.Handle("/api/", requireToken(perClientLimit(api))); err != nil {
return err
}
func requireToken(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if !validToken(r.Header.Get("Authorization")) {
http.Error(w, `{"error":"unauthorized"}`, http.StatusUnauthorized)
return
}
next.ServeHTTP(w, r)
})
}
Sitenin middleware'ine gerçekten dayanan bir handler, onu collage.WithMiddleware() ile geri ister. Bu middleware, örneğin onu korumak için register ettiğiniz bir basicauth plugin'i, okuyucunun session'ı, zaten yapılandırdığınız bir rate limit ya da app.Use middleware'inizin context'e koyduğu bir değer olabilir. Bu handler, zincirin içinde tam bir page gibi ve aynı sırayla çalışır:
if err := app.Handle("/admin/api/", adminAPI, collage.WithMiddleware()); err != nil {
return err
}
Düz bir mount'un sorumluluğunu hiçbir plugin üstlenemez. Bütün siteyi kapsayan bir ban, bir IP allowlist'i, bir bakım sayfası ya da bir access log onu kapsamaz. Bunun için onu WithMiddleware() ile mount edin ya da mux'ınızın etrafına kendi middleware'inizi koyun. Özellikle:
- elagoht/fail2ban düz bir mount'a gelen yoklamaları yine sayar, çünkü request hook'u her request için çalışır. Ama ban'lı bir istemciye verdiği 403 cevabı bir middleware'dir. Bu yüzden o istemci, login brute force'unun genellikle yapıldığı yer olan
/api/'ye tam erişimini korur. - elagoht/basicauth ve elagoht/ratelimit onu korumaz, elagoht/session'ın session'ı da onun request'lerinde bulunmaz.
- elagoht/accesslog onun trafiğini log'lamaz.
- Prefix'inin altındaki bir elagoht/redirects kuralı çalışmaz.
- elagoht/tenant'ın tenant'ı onun context'inde bulunmaz.
Bunlardan birine dayanan bir mount, çağrısında collage.WithMiddleware() ister: o olmadan, sitenin bir basicauth ya da rate limit ile korunması mount'u korumaz.
Hangi request'lerin middleware'i atlayacağına, path temizlendikten sonra, routing'in kullandığı eşleşmeyle karar verilir. Bu yüzden middleware'i atlayan bir request yalnızca o handler'a ulaşabilir. Path'leri yeniden yazan middleware'ler için bunun iki sonucu vardır:
- Bir request'in path'ini düz bir mount'un prefix'inin içine yeniden yazan bir middleware artık ona ulaşamaz: yeniden yazılan request, zincirin ilettiği her şey gibi route edilir ve 404 olur. Hedefi
WithMiddleware()ile mount edin. - Bir path'i düz bir mount'un prefix'inin dışına yeniden yazan bir middleware (
/api/legacy'yi bir page'e) artık onun için çalışmaz: mount request'i önce sahiplenir. Bir middleware'in onun request'lerini görmesi gerekiyorsa onuWithMiddleware()ile mount edin.
Bir plugin'in kendi endpoint'leri (bir live-reload stream'i, bir OAuth callback'i, bir Prometheus /metrics'i, bir Open Graph görseli) Host.Handle ile mount edilir ve bunlar her zaman middleware'in içinde çalışır. Sitenin bir parçasıdırlar; session'ı okuyabilir ya da önlerindeki bir basicauth'a dayanabilirler.
Prefix'ler ve çakışmalar
Prefix / ile başlamalıdır ve tek başına / olamaz (collage.ErrInvalidPrefix). /.well-known/… sorun değildir; yalnızca nokta ile başlayan her segment de öyle. Reddedilen şey bir . ya da .. segment'i ve çift slash'tir (/a/./b/, /a//b/): temiz path redirect'i bunları bir handler'a sorulmadan önce kaldırır, bu yüzden böyle bir prefix hiçbir zaman eşleşemez; hata hangisi olduğunu söyler.
/ile biterse altındaki her path'i üstlenir.- Sonunda
/yoksa tek bir tam path'tir ve yalnızca o path'e cevap verir:app.Handle("/metrics", h),/metrics'i sunar,/metrics/x'i sunmaz.
/'deki bir handler bütün page'lerin bütün request'lerini alırdı. Gerçekten istediğiniz buysa app.Handler()'ı kendi mux'ınızın içine koyun.
Bir prefix, collage'ın route ettiği hiçbir şeyi kapsayamaz:
/api/count'ta bir action varkenapp.Handle("/api/", ...)çağrısıcollage.ErrMountShadowsRouteile reddedilir.- Çakışan iki handler ya da çakışan bir handler ile bir static mount da
collage.ErrMountConflictile reddedilir.
Bu kontrol uygulama başlarken çalışır. Bu yüzden hangisinin önce register edildiği önemli değildir. Hatayı app.ListenAndServe ve app.Start döner.
Kontrol yalnızca literal path'leri karşılaştırır. Prefix'in altında eşleşebilecek dinamik bir pattern'i göremez. Örneğin /{rest...}'te catch-all bir page ve /api/'de bir handler varsa /api/users URL'si handler'a gider. Bir prefix mount ettiğinizde bu ödünü kabul etmiş olursunuz.
API'nizden invalidate etmek
Handler'ınız da cache'teki page'leri diğer her şey gibi invalidate edebilir. Bir API çağrısı içeriği değiştirdiğinde, o içerikten oluşturulan page'lerin bildirdiği tag'leri invalidate edin:
func updatePost(app *collage.App, posts *store.Posts) http.HandlerFunc {
return func(w http.ResponseWriter, r *http.Request) {
slug := r.PathValue("slug")
if err := posts.Update(r.Context(), slug, r.Body); err != nil {
http.Error(w, err.Error(), http.StatusBadRequest)
return
}
if err := app.InvalidateTags(r.Context(), "post:"+slug, "blog:posts"); err != nil {
app.Logger().Error("invalidate", "slug", slug, "error", err)
}
w.WriteHeader(http.StatusNoContent)
}
}
app.InvalidateTagsN aynı işi yapar ve ek olarak tag'lerin kaç cache entry'sine ulaştığını döner. Bu sayı bir webhook'un response'unda ya da bir log satırında işe yarar.
En yaygın örnek bir CMS webhook'udur:
- CMS, değişen entry ile
/api/hooks/cms'i çağırır. - Handler webhook'un imzasını kontrol eder ve o entry'nin tag'ini invalidate eder.
Yalnızca o entry'nin page'leri ve aynı tag'i taşıyan collage.Cached değerleri yeniden render edilir. Ayrıntılar için Caching sayfasına bakın.
Ne zaman bunun yerine action kullanmalı
app.Handle, page'lerinizle ilgisi olmayan kod içindir: kendi authentication'ı olan bir API, proxy'lediğiniz bir servis ya da zaten kullandığınız bir router. Siteye ait bir endpoint için bir action kullanın:
- Bir form post'u ya da page'lerinizden birinden yapılan bir
fetch(). Action request forgery token'ını kontrol eder, handler etmez. Bu yüzdenapp.Handleüzerinden tarayıcıya açılan birPOST'u, başka herhangi bir site okuyucunuz adına gönderebilir. - Sınırlanması gereken her şey. Bir action'ın body'si
Server.MaxBodyBytes(varsayılan 4 MiB) ya da action'ın kendiWithMaxBodyBytesdeğeri ile sınırlanır. - Bir fragment ya da page ile cevap veren bir endpoint, örneğin bir form'un değişen kısmı ya da bir validation hatası. Action
collage.RenderFragmentya dacollage.RenderPagedönebilir. - Başarılı olduğunda
ActionResult.InvalidateTagsile cache'teki page'leri invalidate eden bir endpoint. - Sitenin her locale'inde bulunması gereken bir URL. Action'ın path'leri, page'in path'leri gibi locale'e göre tanımlanır.
count := collage.NewAction("count").
WithPath("en", "/api/count").
WithMethods(http.MethodPost).
WithHandler(func(context.Context, *collage.RenderContext) (*collage.ActionResult, error) {
result, err := collage.JSON(http.StatusOK, countResponse{Count: store.Increment()})
if err != nil {
return nil, err
}
result.InvalidateTags = []string{store.CountTag}
return result, nil
}).
Build()
Bu, collage new'un oluşturduğu projedeki sayaçtır. Forgery token'ı isteyen ve sayacı gösteren page'i invalidate eden bir JSON endpoint'idir. Token gönderemeyen bir servisten gelen webhook için WithoutCSRF() ile tanımlanmış bir action da body limitinden yararlanmaya devam eder.
Örnek: bir ekibin iş listesi
Her üyenin giriş yaptığı ve bir rolü olduğu bir ekip iş listesi düşünün: admin ekibin her görevini, member ise yalnızca kendisine atanmış görevleri değiştirebilir. Page'ler ekibin görevlerini gösterir. Ekibin komut satırı aracının zaten konuştuğu bir JSON API de olduğu gibi kalır. Bu sayfanın üç konusu burada buluşur:
- kimin sorduğunu her request'te bir kez bulan tek bir middleware;
- middleware'in içinde,
app.Handleile mount edilen mevcut API; - API'nin, değiştirdiği listenin tag'ini invalidate etmesi.
Kim soruyor, her request'te bir kez
Middleware ya bir API token'ını ya da session cookie'sini okur ve kullanıcıyı, kendine ait bir tipteki key ile request'in context'ine koyar:
type User struct {
ID string
TeamID string
Role string // "admin" or "member"
ByToken bool // signed in with an API token, not the session cookie
}
// Users is your own data layer.
type Users interface {
BySession(ctx context.Context, cookie string) (User, bool, error)
ByToken(ctx context.Context, token string) (User, bool, error)
}
type userKey struct{}
// UserFrom returns the signed-in user; false for a reader who is not.
func UserFrom(ctx context.Context) (User, bool) {
user, ok := ctx.Value(userKey{}).(User)
return user, ok
}
// loadUser resolves who is asking once per request. Pages, actions and the
// API behind it read the result with UserFrom.
func loadUser(users Users) func(http.Handler) http.Handler {
return func(next http.Handler) http.Handler {
return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
var (
user User
ok bool
err error
)
if token, bearer := strings.CutPrefix(r.Header.Get("Authorization"), "Bearer "); bearer {
user, ok, err = users.ByToken(r.Context(), token)
user.ByToken = true
} else if cookie, cerr := r.Cookie("sid"); cerr == nil {
user, ok, err = users.BySession(r.Context(), cookie.Value)
}
if err != nil {
http.Error(w, "unavailable", http.StatusServiceUnavailable)
return
}
if ok {
r = r.WithContext(context.WithValue(r.Context(), userKey{}, user))
}
next.ServeHTTP(w, r)
})
}
}
Middleware routing'den önce çalıştığı için aynı sorgu bir page'e, bir action'a ve mount edilmiş API'ye aynı şekilde hizmet eder. Arkasındaki hiçbir şey okuyucunun kim olduğunu veritabanına yeniden sormaz. API bunu yalnızca aşağıda WithMiddleware() ile mount edildiği için alır: düz bir app.Handle mount'unda hiçbir middleware çalışmaz ve UserFrom orada kimseyi bulamaz.
Olduğu gibi mount edilen API
type Task struct {
ID string
TeamID string
AssigneeID string
Title string
Done bool
}
// Tasks is your own data layer.
type Tasks interface {
Get(ctx context.Context, id string) (Task, bool, error)
SetDone(ctx context.Context, id string, done bool) error
ByTeam(ctx context.Context, teamID string) ([]Task, error)
}
// taskAPI is the JSON API the team's command-line tool already talks to.
func taskAPI(app *collage.App, tasks Tasks) http.Handler {
api := http.NewServeMux()
api.HandleFunc("PATCH /api/tasks/{id}", func(w http.ResponseWriter, r *http.Request) {
user, ok := UserFrom(r.Context())
if !ok || !user.ByToken {
http.Error(w, "token required", http.StatusUnauthorized)
return
}
task, found, err := tasks.Get(r.Context(), r.PathValue("id"))
if err != nil {
http.Error(w, "unavailable", http.StatusServiceUnavailable)
return
}
if !found || task.TeamID != user.TeamID {
http.NotFound(w, r)
return
}
if user.Role != "admin" && task.AssigneeID != user.ID {
http.Error(w, "not your task", http.StatusForbidden)
return
}
var body struct {
Done bool `json:"done"`
}
// collage does not bound a mounted handler's body; this is ours to do.
if err := json.NewDecoder(http.MaxBytesReader(w, r.Body, 1<<16)).Decode(&body); err != nil {
http.Error(w, "bad request", http.StatusBadRequest)
return
}
if err := tasks.SetDone(r.Context(), task.ID, body.Done); err != nil {
http.Error(w, "unavailable", http.StatusServiceUnavailable)
return
}
if err := app.InvalidateTags(r.Context(), "team:"+task.TeamID+":tasks"); err != nil {
app.Logger().Error("invalidate", "task", task.ID, "error", err)
}
w.WriteHeader(http.StatusNoContent)
})
return api
}
İçindeki her kontrol, app.Handle'ın yaptığı ve yapmadığı şeylerden gelir:
- Cookie değil, token. Handler'da request forgery kontrolü yoktur. Bu yüzden handler'ın session cookie'sine dayanarak kabul ettiği bir yazma işlemi korumasızdır. Onun üzerinden tarayıcıya açık bir
POST'u da başka herhangi bir site okuyucu adına gönderebilir. API yalnızca token ile giriş yapılmış request'leri kabul eder; page'ler görevleri forgery token'ını kontrol eden bir action üzerinden değiştirir. - Body elle sınırlanır. collage mount edilmiş bir handler'ın body'sine dokunmaz, bu yüzden handler onu kendisi
http.MaxBytesReaderile sarar. - Rol, verinin olduğu yerde kontrol edilir. Middleware yalnızca kimin sorduğunu söyler; o kullanıcının neyi değiştirebileceğine API karar verir.
- Action'lar
/api/dışında durur. Bir prefix bir route'u kapsayamaz. Bu yüzden bu mount'un yanında/api/tasks/new'de bir action olsaydı uygulamacollage.ErrMountShadowsRouteile başlamazdı.
API'nin invalidate ettiği liste
İş listesi fragment'i kullanıcıyı context'ten okur ve ekibin listesini, ekibe ait bir tag ile data cache'te tutar:
var teamTasksKey = collage.NewKey[[]Task]("team-tasks")
// taskListData feeds the task list fragment. The page has no declared
// strategy, so it is dynamic and sees the user; the list itself is shared
// by everyone on the team and fresh until the API changes it.
func taskListData(tasks Tasks) func(context.Context, *collage.RenderContext) ([]Task, []string, error) {
return func(ctx context.Context, rc *collage.RenderContext) ([]Task, []string, error) {
user, ok := UserFrom(ctx)
if !ok {
return nil, nil, nil // signed out: the fragment links to the sign-in page
}
list, err := collage.Cached(rc, teamTasksKey.With(user.TeamID), 0,
[]string{"team:" + user.TeamID + ":tasks"},
func(ctx context.Context) ([]Task, error) { return tasks.ByTeam(ctx, user.TeamID) })
return list, nil, err
}
}
func taskList(tasks Tasks) *collage.Fragment {
return collage.NewFragment("task-list", "fragments/task-list.html").
WithData(collage.LoadTagged(taskListData(tasks))).
Build()
}
Page kullanıcıya göre render edildiği için dynamic kalır. Arkasındaki liste bütün ekip için aynıdır, bu yüzden bir kez çekilir ve paylaşılır: sıfır ttl, onu tag'i invalidate edilene kadar taze tutar.
Komut satırı aracı bir görevi tamamlandı olarak işaretlediğinde API'nin InvalidateTags çağrısı o ekibin listesini stale olarak işaretler. Sonraki render'a eski liste hemen sunulur; bu sırada arka planda tek bir çekme işlemi onu yeniler. Bu işlem bittikten sonraki bir request değişikliği görür (nasıl davranır). Diğer ekiplerin listelerine dokunulmaz.
Hepsini bağlamak için iki çağrı yeter:
if err := app.Use(loadUser(users)); err != nil {
return err
}
if err := app.Handle("/api/", taskAPI(app, tasks), collage.WithMiddleware()); err != nil {
return err
}
collage.WithMiddleware() API'yi zincirin içine koyar. Böylece loadUser ve her plugin'in middleware'i onun için de çalışır: Güvenlik sayfasının eklediği rate limit, onun yazma request'lerini de sayar. O olmadan her çağrı 401 token required ile cevaplanırdı, çünkü kullanıcıyı context'e koyan olmazdı.