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 WithMiddleware ile 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üz app.Handle ile 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.
Bir request, collage'ın span, metric ve panic recovery'den oluşan koruması içinde önce Config.Plugins içindeki plugin'lerin middleware'lerinden liste sırasıyla, sonra app.Use middleware'lerinden register sırasıyla geçer. Routing önce static mount'lara ve WithMiddleware ile mount edilmiş app.Handle prefix'lerine bakar, geri kalan her şeyi router'a verir; router da bir page, onun fragment path'lerinden birini, bir document ya da bir action seçer. Düz app.Handle ile mount edilmiş bir handler middleware'den önce, korumanın içinde eşleşir ve middleware olmadan çalışır.tarayıcıcollage korumasıspan · metric · panic recoveryplugin middleware'leriConfig.Plugins, liste sırasıylaapp.Use middleware'leriregister sırasıylaapp.Handledüzroutingstatic mountapp.HandleWithMiddlewarerouterönce prefix ile eşleşirpage ya dadocumentaction
Her request collage'ın koruması içinde çalışır: span'i, metric'leri ve bir panic'i 500'e çeviren panic recovery. Bunun içinde önce Config.Plugins içindeki plugin'lerin middleware'leri liste sırasıyla, sonra app.Use middleware'leri register edildikleri sırayla çalışır; app.RegisterPlugin ile eklenen bir plugin, çağrının yapıldığı yerde durur. Bunlardan herhangi biri request'e kendisi cevap verip onu orada durdurabilir. Geçen request route edilir: önce bir static mount'a ya da WithMiddleware ile mount edilmiş bir app.Handle'ın prefix'ine bakılır, gerisini router alır. Düz app.Handle ile mount edilmiş bir handler ise zincirin hiç içinde değildir: request'leri middleware'den önce, yine korumanın içinde eşleşir ve doğrudan ona gider.

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:

  • %2F iç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 413 ile cevap verir. Middleware body'yi buffer'layıp yerine yeni bir reader koymuş olsa da (io.ReadAll, ardından io.NopCloser) böyledir.
  • app.Handle ile mount edilmiş bir handler'a dokunulmaz. Bir plugin'in Host.Handle prefix'i ise Server.MaxBodyBytes ile 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 da Incremental(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.Vary ile 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. Asla Cookie'nin ya da Authorization'ı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.Varied ile okuyun. Cache'lenebilir bir page'de tek bir render birçok okuyucuya sunulur. Bu yüzden middleware'inizin context.WithValue ile 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. Bir Vary değ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 Vary header'ı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-store bir response'ta ayrı tutulacak bir şey yoktur. Header'ın adı, middleware'inizin yazdığı bir Vary'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 bir app.Handle handler'ı. Routing'den sonra, örneğin bir data handler'dan çağrılırsa Vary çalışıyormuş gibi yapmaz, collage.ErrVaryTooLate döner. collage'ın sunmadığı bir request'te çağrılırsa collage.ErrVaryOutsideRequest döner.
  • Middleware'inizin set ettiği bir cookie response'u private yapar. Response'u, cache header'ları yazıldığında zaten bir Set-Cookie taşıyan cache'lenebilir bir page Cache-Control: private, no-store ile ve Vary olmadan 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 limitispan ve metric'ler
cachepanic 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 onu WithMiddleware() 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 varken app.Handle("/api/", ...) çağrısı collage.ErrMountShadowsRoute ile reddedilir.
  • Çakışan iki handler ya da çakışan bir handler ile bir static mount da collage.ErrMountConflict ile 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:

  1. CMS, değişen entry ile /api/hooks/cms'i çağırır.
  2. 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üzden app.Handle üzerinden tarayıcıya açılan bir POST'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 kendi WithMaxBodyBytes değ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.RenderFragment ya da collage.RenderPage dönebilir.
  • Başarılı olduğunda ActionResult.InvalidateTags ile 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.Handle ile 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.MaxBytesReader ile 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ı uygulama collage.ErrMountShadowsRoute ile 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ı.