Genişletmek90 dk okuma
Plugin kullanmak
Bir plugin'in neler yapabildiği, bir plugin'in nasıl register edilip yapılandırıldığı ve ne işe yaradıklarına göre gruplanmış, yayımlanmış kırk altı plugin.
Plugin, sizin oluşturup uygulamanıza verdiğiniz sıradan bir Go değeridir. Uygulamanın ne yaptığını izleyebilir ve ürettiği şeylerin bir kısmını değiştirebilir. Ancak router'a, cache'e ya da template kümesine erişemez. Ona dar bir yetenek kümesi verilir, fazlası verilmez.
Plugin yükleyen bir mekanizma da, plugin yayımlayacağınız bir registry de yoktur. Plugin, import ettiğiniz bir Go modülüdür ve diğer tüm bağımlılıklar gibi binary'nizin içine derlenir.
Bir plugin neler yapabilir
Bir plugin'in yaptığı her şey, ya kendi seçtiği bir hook'tan ya da başlangıçta ona verilen bir yetenekten geçer. Bu ikisiyle bir plugin şunları yapabilir:
- Render edilen çıktıyı yeniden yazabilir. Bir page'in HTML'ini, bir sitemap'in ya da bir JSON document'ın gövdesini, sunulmadan ve cache'e yazılmadan önce değiştirebilir. Bir minifier bu şekilde çalışır.
- Page render edilmeden önce head'e hoist ederek page'e katkıda bulunabilir: bir structured data bloğu, bir meta tag ya da bir preload ipucu ekleyebilir.
- Template fonksiyonları ekleyebilir. Eklenen fonksiyonları her template çağırabilir.
- Mount edilen her dosya sistemini dönüştürebilir. Böylece bir mount'un sunduğu dosyalar, örneğin, zaten minify edilmiş olur.
- Kendine ait page'ler, document'lar ve mount'lar register edebilir. Bir görsel optimize edici plugin, link verdiği yeniden boyutlandırılmış görselleri kendi mount'undan sunar.
- Kendine ait bir handler sunabilir. Bu bir event stream ya da bir WebSocket olabilir. Plugin, bir page'in fragment path'lerini render edip bu bağlantı üzerinden gönderebilir.
- Invalidation'lardan haberdar olabilir. Cache'teki page'leri az önce invalidate edilen tag'leri alır; böylece bir CDN'deki kopyaları temizleyebilir ya da güncel bir fragment gönderebilir.
- Hataları gözlemleyebilir. Her hatayı, pipeline'ın hangi aşamasında oluştuğu bilgisiyle birlikte alır.
- Her request'i sarmalayabilir. Bunu kendi middleware'iyle yapar.
Config.Pluginsiçindeki bir plugin'in middleware'i,app.Use'un eklediği her şeyin dışındadır ve listedeki sırayla çalışır; böylece sizin middleware'iniz onun request context'ine koyduğunu okur.RegisterPluginile register edilen bir plugin'in middleware'i ise kendisinden önce eklenen middleware'in içinde kalır. v0.67.0'dan beri uygulamanın düzapp.Handleile mount ettiği bir handler bunun istisnasıdır: onun için hiçbir plugin'in middleware'i çalışmaz. Bkz. Middleware ve kendi API'niz. - Çıktıyı denetleyip finding raporlayabilir. Finding'ler development'ta page'in üzerinde gösterilir, static build'in raporunda listelenir ve error seviyesinde build'i başarısız kılar.
- Programınızın çalıştırdığı komutlar ekleyebilir.
collage newile oluşturulan bir projede bunlargo run . <command>ile çalışır. Bkz. collage CLI.
Aşağıda bu hook'ların bir page request'inin izlediği yolda nerede durduğunu ve request dışında çalışan iki hook'u görebilirsiniz:
Bunların her birinin plugin tarafından nasıl göründüğünü Plugin yazmak sayfasında bulabilirsiniz. collage plugin add ile kurulabilen bir plugin yazmak için repository sözleşmesine bakın.
Bir plugin'i register etmek
v0.58.0'dan beri. Bir plugin'i, projenin dizininde tek komutla ekleyebilirsiniz:
collage plugin add elagoht/minimizer
elagoht/minimizer, github.com/Elagoht/collage-minimizer demektir. Komut modülü indirir, import'u ve constructor çağrısını plugin'in istediği yere plugins.go'ya yazar, plugins-config.json'a da boş bir "elagoht/minimizer": {} bölümü ekler: yani varsayılanlar. Bu plugin'in ihtiyaç duyduğu başka bir plugin varsa onu önce ekler. Ardından plugin'in sizden hâlâ neye ihtiyaç duyduğunu yazdırır (v0.68.0'dan beri): setup notunu, eklediği template fonksiyonlarını ve dokümantasyonunun adresini. Birkaç plugin eklendiğinde bunlar en sonda, "What each plugin needs from you" başlığı altında birlikte yazdırılır.
Bir hata olursa her dosya olduğu gibi kalır. Kaldırmak da aynı şekilde, tersi yönde yapılır. Bölümde ayar varsa kaybolmasın diye yazdırılır:
collage plugin del elagoht/minimizer
Tek komutta birden fazla plugin verilebilir, her biri ayrı işlenir: başarısız olan geri alınır, diğerleri kalır. @ ile yazılan paket, tek ad altında toplanmış plugin'lerdir; collage new da aynısını --with ile alır:
collage plugin add elagoht/session elagoht/flash elagoht/validate
collage plugin add @prod
collage new mysite --with @blog,@prod
Paketler (@prod, @site, @blog, @forms, @live, @ops) ve içerikleri CLI referansında.
collage new ile oluşturulan projede plugins.go hazır gelir ve main.go onu uygulamaya verir:
func plugins() []collage.Plugin {
return []collage.Plugin{
minimizer.New(minimizer.Options{}),
}
}
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{Root: "templates"},
Plugins: plugins(),
})
Dosya sizindir: sırayı değiştirebilir ya da bir plugin'e seçeneklerini Go ile verebilirsiniz (sitemap.New(sitemap.Options{...})). add ve del yalnızca girdileri bütün olarak ekler ve çıkarır. Eski bir proje bu dosyayı ilk add'inde alır. Komut da main.go'ya konacak Plugins: plugins(), satırını yazdırır.
Başkasının plugin'i de aynı şekilde, module path'iyle eklenir: collage plugin add gitlab.com/you/stamp. Bir repository'nin eklenebilmesi için neye sahip olması gerektiği plugin yazarlarının sayfasında, komutun kendisi ise CLI referansında anlatılır.
Elle bağlamak
Komut, sizin yazamayacağınız hiçbir şey yazmaz. Plugin listesini başka bir yolla kuran bir proje için elle bağlamak da geçerli yol olarak kalır. Plugin ayrı bir modüldür. Modülü projeye ekleyin, plugin'i oluşturun ve Config.Plugins'e koyun:
go get github.com/Elagoht/collage-minimizer
import minimizer "github.com/Elagoht/collage-minimizer"
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{Root: "templates"},
Plugins: []collage.Plugin{minimizer.New(minimizer.Options{})},
})
Plugin ayar alıyorsa bölümünü plugins-config.json'a kendiniz ekleyin.
İkinci bir yol da vardır: New'dan sonra çağrılan app.RegisterPlugin.
if err := app.RegisterPlugin(jsonld.New(jsonld.Options{})); err != nil {
log.Fatal(err)
}
Config.Plugins'i tercih edin. Bazı plugin'lerin, uygulama kurulurken devreye girmesi gerekir. Örneğin bir template fonksiyonu eklemek ya da mount edilen dosya sistemlerini sarmalamak için. Bu işler New içinde yapılır. Böyle bir plugin, isteğe bağlı bir Configure aşaması implement eder. RegisterPlugin bu plugin'i kabul edip asıl önemli kısmı sessizce atlamaz. Onun yerine plugin'i adıyla belirterek collage.ErrConfigurerRegisteredLate ile reddeder.
Config.Plugins ise her plugin için çalışır, bu yüzden varsayılan olarak onu kullanın.
RegisterPlugin şu durumlarda da reddeder:
| Hata | Ne zaman |
|---|---|
ErrAppStarted | Uygulama zaten başlamıştır: Handler, ListenAndServe, Start, DispatchCommands ya da bir render çalışmıştır. Başarısız olan başlatmalar da buna dahildir. Bir plugin'in Init'inde başarısız olan başlatma v0.11.0'dan, başka herhangi bir nedenle başarısız olan başlatma v0.12.0'dan beri sayılır. |
ErrDuplicatePlugin | Aynı ada sahip başka bir plugin zaten vardır. |
nil bir plugin ya da Name() değeri boş olan bir plugin de, bunu söyleyen bir hatayla reddedilir; v0.60.0'dan beri ikisinin de kendine ait bir sentinel'i yoktur. Config.Plugins içindeki plugin'ler de aynı şekilde kontrol edilir. Bu durumda hatayı New döndürür.
Sıra önemlidir
Plugin'ler register edildikleri sırayla çalışır. Önce Config.Plugins içindekiler slice'taki sırayla, ardından RegisterPlugin ile eklenenler çağrı sırasıyla çalışır. Çıktıyı değiştiren hook'larda her plugin, kendinden önceki plugin'in ürettiği çıktıyı görür. Page'e bir şey ekleyen plugin, genellikle çıktıyı sıkıştıran plugin'den önce gelmelidir. Böylece eklenen içerik de sıkıştırılır.
Yayımlanmış dört plugin nerede duracağını söyler: elagoht/compress response body'lerini yeniden yazan her plugin'den önce, elagoht/health bir request'i reddedebilen ya da ona cevap verebilen her plugin'den önce, elagoht/jobs işinin kullandığı plugin'lerden sonra, elagoht/devtoolbar ise en sona gelir.
Kapıyı tutan plugin'lerin de kendi sırası vardır. Middleware, request'i plugin'lerin listelendiği sırayla sarar, ilki en dışta. Bu yüzden bunları kullanan bir site önce elagoht/accesslog'u (yalnızca gözlemler; ilk sırada her reddi eksiksiz loglar), sonra elagoht/health'i, sonra elagoht/fail2ban'ı, sonra elagoht/ratelimit'i, sonra da elagoht/basicauth'u listeler; böylece reddedilen bir parola tahmini, bcrypt kontrolünün bedeli ödenmeden önce sayılır. collage plugin add bunların sırasını değiştirmez.
Plugin'leri yapılandırmak
Ayar alan bir plugin, ayarlarını Config.PluginConfig'ten okur. Bu alan, plugin'in adını key olarak kullanan bir map[string]json.RawMessage'tır. Plugin adları modül path'leri gibi yazılır, örneğin elagoht/minimizer. Böylece key ile plugin aynı identifier'ı paylaşır.
En yaygın yöntem, programınızın yanında duran bir JSON dosyasıdır. collage new ile oluşturulan bir projede boş bir plugins-config.json dosyası bulunur ve proje bu dosyayı env.PluginConfig(files) ile zaten yükler. Çalışma dizininde dosya varsa o okunur, yoksa binary'nin embed ettiği kopya. Böylece dosya olmadan deploy edilen bir binary ayarlarını korur. Scaffold edilmiş bir projenin dışında LoadPluginConfig yalnızca dosyayı okur:
{
"elagoht/minimizer": { "js": true },
"elagoht/jsonld": { "siteName": "The Wire" }
}
pluginConfig, err := collage.LoadPluginConfig("plugins-config.json")
if err != nil {
log.Fatal(err)
}
app, err := collage.New(&collage.Config{
Template: collage.TemplateConfig{Root: "templates"},
Plugins: []collage.Plugin{minimizer.New(minimizer.Options{}), jsonld.New(jsonld.Options{})},
PluginConfig: pluginConfig,
})
Dosya yoksa LoadPluginConfig hata vermez, nil bir map döndürür. Hiçbir şeyi yapılandırmayan bir deploy'un, bunu belirtmek için boş bir dosyaya ihtiyacı olmamalıdır. Dosya varsa ama okunamıyorsa ya da bir JSON object değilse, bu bir hatadır.
Bu mekanizma JSON dosyalarına bağlı değildir. LoadPluginConfig yalnızca bir kolaylıktır ve framework onu hiçbir zaman kendisi çağırmaz. PluginConfig'i YAML'dan, environment variable'lardan ya da Go sabitlerinden doldurabilirsiniz:
PluginConfig: map[string]json.RawMessage{
"elagoht/minimizer": json.RawMessage(`{"js": true}`),
},
Hangi yolla doldurursanız doldurun, beş kural geçerlidir:
- Bölüm yoksa varsayılanlar kullanılır. Bölümü olmayan bir plugin, tam olarak constructor'ının kurduğu hâliyle çalışır.
- Bölüm, varsayılanların üzerine decode edilir.
{"js": true}tek bir ayarı açar, diğerlerini olduğu gibi bırakır. Bölümdeki bir liste, varsayılan listeyle eleman eleman birleştirilmez, onun yerini bütünüyle alır (v0.61.2'den beri). Bir map ise kendi girdilerini varsayılan map'e ekler. Belirli bir plugin'in ayarları nasıl birleştirdiği, o plugin'in README'sinde yazar. - Plugin'in tanımadığı bir key uygulamanın başlamasını engeller (v0.61.0'dan beri):
collage: elagoht/robots: unknown key "dissallow" in plugins-config.json. Eskiden yanlış yazılmış ya da plugin'in adını değiştirdiği bir key sessizce yok sayılır, ayar da varsayılanında kalırdı. Key'ler hâlâ büyük küçük harf ayırmadan eşleşir. Hatanın adını verdiği key'i silin ya da plugin'in README'sinde yazan adla değiştirin. - Süreler string olarak yazılır:
time.ParseDuration'ın okuduğu biçimde,"10s"ya da"1h30m". Çıplak bir sayı, key'inin adı verilerek reddedilir —"banTime": write a duration as a string such as "10s", not 3600— çünkü aksi hâlde nanosaniye olarak okunurdu. - Register edilmiş hiçbir plugin'e karşılık gelmeyen bir key, uygulamanın başlamasını engeller ve
collage.ErrUnknownPluginConfigdöner. Bu kontrol olmasaydı,"elagoht/minimzer"gibi bir yazım hatası plugin'i varsayılan ayarlarında bırakırdı ve siz plugin'in yapılandırıldığından emin olurdunuz. KontrolNewiçinde değil, uygulama başlarken yapılır. ÇünküRegisterPluginNew'dan sonra da plugin ekleyebilir.
Var olan ama decode edilemeyen bir bölüm de hatadır. Örneğin plugin'in boolean beklediği yerde bir string varsa, plugin bu bölümü okuduğunda hata oluşur ve mesaj, değeri decode edilemeyen key'in adını verir.
Yayımlanmış plugin'ler
Framework ile birlikte kırk altı plugin yayımlanmıştır. Aşağıda ne işe yaradıklarına göre gruplanmışlardır. Her biri ayrı bir modüldür ve her birinin tam referans niteliğinde kendi README'si vardır. Aşağıdaki bilgiler bir plugin'i kurmanız için yeterlidir.
| Grup | Plugin'ler |
|---|---|
| SEO ve keşfedilebilirlik | jsonld, meta, ogimage, sitemap, robots, feed, redirects, indexnow |
| İçerik | markdown, highlight, toc, search, i18n |
| Form'lar ve state | validate, honeypot, flash, session, uploads |
| Güvenlik | secure, ratelimit, basicauth, oauth, fail2ban, consent |
| Canlı güncellemeler | live, websocket, client |
| Asset'ler ve teslimat | minimizer, opti-image, bundle, favicon, compress, cdnpurge, offline, deploy |
| Operasyon ve development | htmlcheck, devtoolbar, accesslog, prometheus, otel, analytics, tenant, errortrack, health, jobs, gesso |
Plugin olmayan library'ler grupların ardından listelenir.
Çoğu site bir gruptan değil, ne olduğundan yola çıkar. Aşağıda sık görülen üç başlangıç noktası vardır; her plugin aşağıdaki kendi bölümüne bağlanır:
| Ne kuruyorsunuz | Başlangıç | Size ne sağlarlar |
|---|---|---|
| Bir blog | markdown, highlight, toc, feed, sitemap, robots, meta, jsonld, ogimage, search | Markdown ile yazılan, kodu renklendirilmiş ve içindekiler tablosu olan yazılar, okuyucular için bir feed, arama motorlarının ve link preview'larının okuduğu bilgiler ve static olarak build edilen sitede arama. @blog; toc, feed, ogimage ve arama motorlarına yönelik olanları tek komutla ekler; markdown, highlight ve search'ü kendiniz ekleyin. |
| Bir ürün kataloğu | jsonld, meta, sitemap, opti-image, i18n, cdnpurge, compress, minimizer | Product structured data, plugin'in kendi mount'undan sunulan yeniden boyutlandırılmış ürün görselleri, her locale için çeviriler ve bir ürünün tag'leri invalidate edildiğinde CDN'deki kopyaların temizlenmesi. |
| Rolleri olan çok kullanıcılı bir web uygulaması | session, oauth, validate, flash, honeypot, uploads, secure, ratelimit, fail2ban, live | Bir kimlik sağlayıcısıyla giriş, session'da tutulan giriş yapmış kullanıcı, denetlenip cevaplanan form'lar, içeriğine göre denetlenen upload'lar, sınırlanan ya da ban'lenen kötüye kullanım ve page'in güncel tutulan kısımları. Roller sizindir: app.Use ile eklenen bir middleware, plugin'in request context'ine koyduğu session'ı okur; Plugin'lerin middleware'i ve sizinki bunu gösterir. |
@prod, bunlardan herhangi birinin production'da istediği her şeyi ekler. Paketler CLI referansında listelenir.
SEO ve keşfedilebilirlik
Bir arama motorunun, bir feed okuyucunun ya da bir link preview'ının okudukları: structured data, bir page'in paylaşılırken okunan tag'leri, sitemap ve robots.txt, feed'ler, eski adresler ve nereye gittikleri, arama motorlarına neyin değiştiğini bildirmek.
elagoht/jsonld
github.com/Elagoht/collage-jsonld, document'ın head'ine schema.org structured data yazar.
import "github.com/Elagoht/collage-jsonld"
Plugins: []collage.Plugin{jsonld.New(jsonld.Options{})},
{
"elagoht/jsonld": {
"siteName": "The Wire",
"searchURL": "https://thewire.example/search?q={query}"
}
}
Plugin register edildiğinde, siteName ayarlanmışsa her page'e site genelinde geçerli bir WebSite node'u ekler; node'un url'i uygulamanın origin'idir (collage.BaseURL). Başka hiçbir şey eklemez, çünkü plugin bir page'in ne hakkında olduğunu bilemez. Bunu page'in kendisi, makaleyi çeken data handler'dan bildirir:
func loadArticle(ctx context.Context, rc *collage.RenderContext) (*Article, []string, error) {
article, err := client.Article(ctx, rc.Param("slug"))
if err != nil {
return nil, nil, err
}
jsonld.Emit(rc, jsonld.Article{
Headline: article.Title,
DatePublished: article.PublishedAt,
AuthorName: article.Author,
})
return article, []string{"article:" + article.Slug}, nil
}
Configureaşaması yoktur, bu yüzdenRegisterPluginde bu plugin'i kabul eder. v0.3.0siteURL'i kaldırdı: onun yerine uygulamanınBaseURL'ünü ayarlayın.Emitmevcut node'lara ekleme yapar ve plugin register edilmiş olsun ya da olmasın çalışır. Node'lar schema.org tipine veKeyalanına göre key'lenir. Bu yüzden iç içe bir fragment'inArticle'ı, daha dıştaki bir fragment'te tanımlananArticle'ın yerini alır. Farklı tipteki node'ların ise hepsi çıktıda yer alır.- Aynı tipten birden fazla node için her birine bir
Keyverin (v0.4.0).Keypage'e yazılmaz: döngü içindejsonld.Emit(rc, jsonld.Person{Key: p.Slug, Name: p.Name})her kişiyi korur.Keyverilmezse sonrakiPersonöncekinin yerini alır.IDayrı bir alandır:"@id"olarak yazılır, bu yüzden yalnızca gerçek bir IRI'niz varsa verin. - Tipli node'lar Google Search'ün structured data galerisindeki her özelliği kapsar (v0.6.0): sayfalar (
WebSite, türleriyleWebPage,ProfilePage,BreadcrumbList,ItemList), yazı (Article,NewsArticle,BlogPosting,Blog,DiscussionForumPosting,QAPage,FAQPage), kişi ve kurumlar (Person,Organization,LocalBusiness,EmployerAggregateRating),Event, ticaret (kargo ve iadeyleProduct,SoftwareApplication,VacationRental,Review,AggregateRating), medya (VideoObject,ImageObject,Movie,Recipe,HowTo) ve eğitim ve veri (Course,Quiz,MathSolver,Dataset,JobPosting). Ortak parçalar —Agent,Offer,Money,Rating,PostalAddress,GeoCoordinates— her node'da aynı anlama gelir. Bunların dışındaki her şey içinjsonld.Rawkullanılır.jsonld.Rawgeçersiz JSON'u reddeder. - Bir
Event'in konumu birPlace, birOnlineURLya da karma bir etkinlik için ikisi birden olur. Saatleri kendi ofsetiyle yazılır: duvar saati biçimindeki bir zamanıtime.Parseile değil (UTC demektir), etkinliğin saat dilimindetime.ParseInLocationile okuyun. - Marshal edilemeyen bir node, page'i başarısız kılmaz, yalnızca atlanır; log'a tipini adlandıran bir uyarı düşülür.
Layout'unuzda {{hoist "head"}} bulunması gerekir. Bkz. aşağıdaki bölüm.
elagoht/meta
github.com/Elagoht/collage-meta, bir page'in paylaşılırken ve index'lenirken okunan tag'lerini head'ine yazar: Open Graph, Twitter card'ları, canonical URL, meta description ve page'in çevirileri.
import "github.com/Elagoht/collage-meta"
BaseURL: "https://example.com",
Plugins: []collage.Plugin{meta.New(meta.Options{
SiteName: "The blog",
DefaultImage: "/static/share.png",
})},
meta.Set(rc, meta.Page{
Title: article.Title,
Description: article.Dek,
Image: article.Cover,
Type: meta.Article,
Published: article.PublishedAt,
})
{
"elagoht/meta": {
"siteName": "The blog",
"defaultImage": "/static/share.png",
"twitterSite": "@example",
"locales": { "en": "en_US", "tr": "tr_TR" },
"noAlternates": false
}
}
- Canonical ve
og:URL'leri sitenin origin'ini izler:Config.BaseURL'ü ya da host başına, elagoht/tenant gibi birOriginResolverplugin'inin verdiğini. İkisi de yoksa uygulama başlamaz. v0.3.0 plugin'in kendibaseURL'ünü kaldırdı. - Register etmek her page'e şunları verir:
og:site_name,og:type, canonical URL,og:locale, page'in path'i olan her locale için birhreflanglink'i, varsayılan görsel ve Twitter card'ı. Canonical URL ada göre oluşturulur, bu yüzden okuyucunun geldiği query string asla onun parçası olmaz. - Page neyle ilgili olduğunu data handler'ından
meta.Setile söyler. Her tag kendi key'i altında hoist edilir. Bu yüzden page'in tanımı varsayılanın yerini tag tag alır, daha derindeki bir fragment'inki de üst fragment'inkinin yerini alır. <title>bunlardan biri değildir: plugin yokken olduğu gibirc.HoistTitleya daWithTitle'dır. Layout'ta{{hoist "head"}}gerektirir.
elagoht/ogimage
github.com/Elagoht/collage-ogimage, her page'in paylaşım kartını — bir link'in gösterildiği 1200×630 görseli — bir HTML template'inden saf Go ile çizer ve içeriğinden üretilen bir URL'de sunar.
import "github.com/Elagoht/collage-ogimage"
Plugins: []collage.Plugin{
meta.New(meta.Options{SiteName: "The blog"}),
ogimage.New(ogimage.Options{
Templates: templatesFS,
Root: "templates",
Default: "og/default.html",
Dir: ".cache/ogimage",
}),
},
<!-- templates/og/post.html -->
<div style="display:flex; flex-direction:column; justify-content:space-between;
width:1200px; height:630px; padding:72px; background:#0f172a; color:#fff">
<span style="font-size:28px">{{.Site.Name}}</span>
<h1 data-fit style="font-size:72px">{{.Title}}</h1>
<span style="font-size:28px">{{.Label}}</span>
</div>
if err := ogimage.Set(rc, "og/post.html", ogimage.Card{Title: post.Title, Label: post.Category}); err != nil {
return view{}, nil, err
}
- Uygulamanın
Config.BaseURL'ünü gerektirir. Birden fazla host'a hizmet veren bir sitede kartın URL'si request'in origin'ini izler; bu yüzden birOriginResolverplugin'i register edilmişseConfig.BaseURLgerekmez. elagoht/meta'dan sonra register edin ve meta'nınDefaultImage'ını boş bırakın. - v0.3.0'da tek bir constructor vardır:
ogimage.New(ogimage.Options{…}).renderTimeoutbir süre string'idir ("5s"), negatif birmaxEntriesya damaxBytesartık sınırsız değil hatadır, build finding'i deogimage-draw'dır. - v0.4.0'da
ogimage.Draw'ın iki string'i tek bir değer olarak verilir:ogimage.Draw(ctx, opts, ogimage.Input{HTML: html, Locale: locale}). Böylece ikisinin yerini karıştırmak artık derlenmez; boş birLocaleyine"en"ile çizer. Statik build artıkmaxEntriesya damaxBytes'ın tuttuğundan fazla kart olsa bile her kartı çizer; önceden, çizilmeden önce çıkarılan kartlar içinogimage-draw"file does not exist" hatasıyla başarısız oluyordu. - Bir kart, HTML ve CSS'in bir alt kümesiyle yazılmış,
og/altındaki birhtml/templatedosyasıdır: kutu içeren bir elementdisplay:flexder, metin içeren bir element run'lardan oluşan bir paragraftır. Çizemeyeceği bir şey uygulamayı başlangıçta template, satır ve sütun bilgisiyle durdurur. - Kart tanımlamayan bir page
Default'u alır; kart, page'in başlığından ve açıklamasından çizilir. - URL, çizilenin hash'idir ve immutable sunulur; hiçbir şey invalidate edilmez, değişen bir page'in yeni bir kartı olur. Bir kart ilk istendiğinde ve yalnızca bir render onu kaydettiyse çizilir;
collage exportkartları yazar.Dirkartları restart'lar arasında saklar; disk page cache'i bunu gerektirir. - Development'ta
/_og-preview/kartları listeler;go run . ogimage og/post.html card.json > card.pngsiteye gerek olmadan bir kart çizer: varsayılan locale'de ya da-locale tr'nin adlandırdığında.
elagoht/sitemap
github.com/Elagoht/collage-sitemap, uygulamanın register ettiği page'lerden /sitemap.xml'i sunar.
import "github.com/Elagoht/collage-sitemap"
BaseURL: "https://example.com",
Plugins: []collage.Plugin{sitemap.New(sitemap.Options{})},
{
"elagoht/sitemap": {
"path": "/sitemap.xml",
"exclude": ["thanks"],
"maxURLs": 50000
}
}
- Bir sitemap mutlak URL'ler listelediği için bir origin'e ihtiyaç duyar:
Config.BaseURL, birden fazla host'a hizmet veren bir sitede ise birOriginResolverplugin'inin adlandırdığı, request'in kendi origin'i. İkisi de yoksa uygulama başlamaz. v0.3.0 plugin'in kendibaseURL'ünü kaldırdı. - Path'i olan her page'i, her locale'de,
App.URL'in yazdığı biçimde listeler. Page'in diğer locale'lerihreflangalternate'leri olarak eklenir. Bir{param}pattern'i,WithStaticParams'ının döndürdüğü her değer için bir kez listelenir; bunlar static build'in yazdığı URL'lerdir.WithStaticParams'ı olmayan bir pattern dışarıda kalır.Exclude, page'leri adlarıyla dışarıda bırakır. - Bir page'in
<lastmod>'unu bir Go fonksiyonu olanLastModverir. - Static bir document'tır: cache'lenir, export edilir ve
sitemap.Taginvalidate edildiğinde yeniden üretilir. Yayımladığınız bir yazının tag'leriyle birlikte onu da invalidate edin. - 50.000 URL'yi (
maxURLs; 0 50.000 demektir, negatif bir değer uygulamayı durdurur) aşınca numaralı dosyalardan oluşan bir sitemap index'ine dönüşür.
elagoht/robots
github.com/Elagoht/collage-robots, /robots.txt'yi sunar.
import "github.com/Elagoht/collage-robots"
Plugins: []collage.Plugin{robots.New(robots.Options{
Rules: []robots.Rule{{Disallow: []string{"/admin"}}},
Sitemaps: []string{"https://example.com/sitemap.xml"},
})},
{
"elagoht/robots": {
"rules": [{ "userAgents": ["*"], "disallow": ["/admin"] }],
"sitemaps": ["https://example.com/sitemap.xml"],
"disallowAll": false
}
}
- Hiç kural yoksa her crawler'a her şeye izin verir. User agent belirtmeyen bir kural
*içindir. Negatif bircrawlDelayuygulamayı durdurur. v0.3.0(*Plugin).Render'ı kaldırdı: onun yerine/robots.txt'yi uygulamadan isteyin. disallowAll, kurallar ne derse desin siteyi bütün crawler'lara kapatır ve her response'uX-Robots-Tag: noindex, nofollowile gönderir. Bunu bir staging deploy'unun config'inde açın. Böylece aynı binary production'da açık, başka yerlerde kapalı olur.- Bir sitemap path olarak verilebilir (
"/sitemap.xml"); o zaman request'in origin'ine göre request başına mutlak hâle getirilir:Config.BaseURL'e ya da birden fazla host'lu bir sitede birOriginResolverplugin'inin verdiğine. Scheme-relative//host/pathreddedilir; bir path'i karşısında çözeceği origin yoksa uygulama başlamaz. - Body uygulama başlarken sabitlenir ve static build onu
robots.txtolarak yazar.
elagoht/feed
github.com/Elagoht/collage-feed, uygulamanın listelediği öğelerden RSS 2.0 ve Atom 1.0 feed'leri sunar ve bunları her page'in head'inde duyurur.
import "github.com/Elagoht/collage-feed"
BaseURL: "https://example.com",
Plugins: []collage.Plugin{feed.New(feed.Feed{
Title: "The blog",
Link: "/blog",
Items: latestPosts, // func(ctx) ([]feed.Item, error), newest first
Tags: []string{"posts"},
})},
Itemsbir fonksiyon olduğu için yalnızca Go'da yapılandırılır;collage plugin addfeed.New()yazar, hiç feed verilmezse plugin bir uyarı log'lar ve hiçbir şey sunmaz.- Bir feed RSS olarak
/feed.xml'de, Atom olarak/atom.xml'de sunulur.RSSveAtombu path'leri değiştirir,"-"ise bir formatı dışarıda bırakır. Birden fazla feed'in her biri birNameve kendi path'lerini alır. Bir feed en fazlaLimitkadar öğe taşır; varsayılan 20'dir. - Her page, her feed için bir
<link rel="alternate">alır. Bu yüzden layout'ta{{hoist "head"}}bulunması gerekir.NoDiscovery, bir feed'i head'lerin dışında tutar. - Static bir document'tır: cache'lenir, export edilir ve
Tags'inden biri invalidate edildiğinde yeniden üretilir. - Link'ler yalnızca
httpya dahttpsolarak yazılır (v0.2.1'den beri). Başka bir scheme taşıyan bir öğe link'i, URL biçimindeki birIDya da channel link'i (javascript:,data:,file:, nasıl yazılırsa yazılsın) atılır ve link değil, yalnızca scheme'i ile bir kezWARNseviyesinde log'lanır. Bir feed'in kendiLink'i,RSS'i ya daAtom'u böyle bir scheme taşırsa uygulamaErrUnsafeLinkile başlamaz. Mutlak birhttpya dahttpslink'i verildiği gibi yazılır (v0.2.2; v0.2.1 ASCII olmayan bir path'i yeniden encode ediyordu). - Feed'in link'leri request'in origin'ini izler:
Config.BaseURL'ü ya da birOriginResolverplugin'inin verdiğini. Böylece tek bir feed her host'a kendi link'lerini sunar. v0.3.0Feed.BaseURL'ü kaldırdı; origin yoksa uygulama başlamaz.
elagoht/redirects
github.com/Elagoht/collage-redirects, kodda değil bir dosyada tutulan redirect'leri routing'den önce sunar. Bunlar bir site taşımasının geride bıraktıklarıdır. Plugin, redirect'leri host'un kendi config'i için static bir build'e de verir.
import "github.com/Elagoht/collage-redirects"
//go:embed redirects.txt
var siteFS embed.FS
Plugins: []collage.Plugin{redirects.New(redirects.Options{FS: siteFS})},
# the old blog
/blog/* /posts/:splat
/about-us /about 301
/summer-sale /sale 302
/moved https://new.example/moved 308
/old-product - 410
{
"elagoht/redirects": {
"file": "redirects.txt",
"rules": [{ "from": "/careers", "to": "https://jobs.example.com", "status": 302 }]
}
}
- Her satırda bir kural vardır: eski path, gittiği yer ve bir status. Status yazılmazsa
301'dir;302,307,308ya da artık olmayan bir page için-ile birlikte410olabilir. Bu durumda sitenin kendi not-found page'i410status'uyla sunulur./blog/*bir prefix'tir ve hedefteki:splat,*'ın eşleştiği kısımdır. Eşleşen ilk kural kazanır, okuyucunun query string'i de taşınır. - Hatalı bir dosya uygulamanın başlamasını engeller ve hatanın yerini söyler: bozuk bir satır, hiçbir request'in ulaşamayacağı bir kural, okuyucuyu bir döngüde dolaştıran kurallar. v0.2.0'dan beri bir kuralda control karakteri olması ya da bir hedefin, tarayıcının başka bir host olarak okuduğu
/\ile başlaması da uygulamanın başlamasını engeller. - v0.2.0'dan beri
_redirects'i ne sunar ne de yazar. Bu bir breaking change'dir:Options.NoRedirectsFileveRedirectsFile()kaldırıldı, config'tekinoRedirectsFilekey'i ise bilinmeyen bir key olarak uygulamayı durdurur. Plugin birRedirectSource'tur: static build kurallarını alır, elagoht/deploy da onları host'un biçiminde yazar. Bir deploy plugin'i yoksa hiçbir şey yazılmaz. - Collage'ın pattern sözdiziminin ifade edemediği bir kural yine sunulur, ama
redirects-not-exporteduyarısıyla build'in dışında bırakılır. Bir page'in ya da document'ın kendi redirect'ini kapsayan bir kural iseredirects-overlapuyarısıdır: sunucu kuralı, static bir host ise page'in redirect'ini izler. - Static bir build, yazdığı bir dosyanın üstüne düşen (
collage.ErrRedirectShadowsFile) ya da başka bir redirect ile aynı path'ten gelen (collage.ErrDuplicateRedirect) bir kuralda başarısız olur. Bu yüzden export'u v0.1.x ile çalışan bir site, kural ya da page kaldırılana kadar başarısız olabilir. Kurallar Go'da ya da config'te de verilebilir.
elagoht/indexnow
github.com/Elagoht/collage-indexnow, hangi URL'lerin değiştiğini IndexNow protokolüyle arama motorlarına bildirir. Bing, Yandex, Seznam, Naver ve birine söyleneni paylaşan diğerleri bu protokolü kullanır.
import "github.com/Elagoht/collage-indexnow"
BaseURL: "https://example.com",
Plugins: []collage.Plugin{indexnow.New(indexnow.Options{
Key: "4f1c2e9a7b3d4c8e",
})},
{
"elagoht/indexnow": {
"key": "4f1c2e9a7b3d4c8e",
"window": "10s",
"skip": ["/api", "/search"]
}
}
keyzorunludur. URL'lerConfig.BaseURL'ü izler; birden fazla host'a hizmet veren bir sitede origin başına bir submission gönderilir ve iki host'un paylaştığı bir origin bir kez gönderilir.- v0.3.0
baseURL'ü kaldırdı veexclude'un adınıskipyaptı: hiç gönderilmeyen request path prefix'leri;"/api"hem/api'yi hem altındakileri kapsar.windowvebackoffsüre string'leridir, negatif birretriesya dabatchSizeuygulamayı durdurur. - Gönderdiği, cache'in bıraktıklarıdır: yani bir invalidation'ın ulaştığı path'ler. Tag'i invalidate edildiğinde cache'te olmayan bir page gönderilmez.
- URL'ler
windowboyunca toplanır, arka planda gönderilir ve bir429ya da5xxgelirse yeniden denenir. Bekleyenler shutdown'da gönderilir. - Key'i
/<key>.txt'de sunar, static build da onu oraya yazar. Bir development sunucusu ve bir static build hiçbir şey göndermez.
İçerik
Metnin nereden geldiği ve nasıl sunulduğu: HTML'e çevrilen Markdown, renklendirilmiş kod, içindekiler tablosu, static bir sitede arama ve çeviriler.
elagoht/markdown
github.com/Elagoht/collage-markdown, Markdown string'lerini HTML'e çevirir: bir {{markdown}} template fonksiyonu, Go'dan Render ve bir dokümanın front matter'ını uygulamanın kendi tipine de okuyan Parse. Dosya okumaz, page kurmaz: Markdown'ın nereden geldiği, page'in kendisi, verisi ve SEO'su uygulamanındır.
import "github.com/Elagoht/collage-markdown"
md := markdown.New(markdown.Options{})
Plugins: []collage.Plugin{md},
<article>{{markdown .Body}}</article>
type Post struct {
Title string `md:"title"`
Date time.Time `md:"date"`
Tags []string `md:"tags"`
}
doc, err := markdown.Parse[Post](md, rc.Locale, src) // doc.Meta, doc.HTML, doc.Text, doc.Headings
{
"elagoht/markdown": {
"extensions": ["table", "strikethrough", "linkify", "taskList", "footnote", "mark", "headingIDs", "headingAttributes"],
"unsafe": false
}
}
Config.Pluginsiçinde olmalıdır: bir template fonksiyonu ekler.extensionsşunlardan seçer:table,strikethrough,linkify,taskList,footnote,mark(==metin==,<mark>metin</mark>olur),headingIDs,headingAttributes,definitionListvetypographer. Yazılmazsa son ikisi dışındakilerin hepsidir; bir liste bunun tamamının yerine geçer,[]hepsini kapatır, bilinmeyen bir ad uygulamayı durdurur.- Front matter'daki bir key,
md:"key"tag'li alana ya da o adı taşıyan tag'siz alana okunur; hiçbir alanın almadığı key yok sayılır, dönüşmeyen bir değer hatadır.markdown.FrontMatter[Post](src)onu render etmeden okur. - Heading id'leri her alfabenin harflerini korur ve page'in locale'ini izler (Türkçede
## IŞIK,ışıkolur). Code block'lar<pre><code class="language-go">biçimindedir; elagoht/highlight register edildiyse onları renklendirir. - Ham HTML ile bir başlığın
{style="…"}veon…attribute'ları,unsafeaçık değilse dışarıda bırakılır;idveclasskalır. - v0.4.0'da değişen: plugin artık bir dizin okumaz.
FS,Dir,LocaleDirs,Drafts,Name,Handler,IndexHandler,StaticParams,List,Get,TagveDirTagkalktı; uygulama kendi dosyalarını okur ve page'lerinimarkdown.Parseile kurar. Plugin'in README'si bu şekilde kurulmuş bir blog gösterir.
elagoht/highlight
github.com/Elagoht/collage-highlight, kodu chroma ile renklendirir: render edilen her page'deki code block'ları, bir {{highlight}} template fonksiyonu ve açık ile koyu bir stylesheet.
import "github.com/Elagoht/collage-highlight"
Plugins: []collage.Plugin{highlight.New(highlight.Options{})},
{{highlight .Snippet "go"}}
{
"elagoht/highlight": { "light": "github", "dark": "github-dark", "noBackground": true }
}
Config.Pluginsiçinde olmalıdır:{{highlight}}'ı ekler.noAutoaçılmadıkça bir page'in içerdiği her<pre><code class="language-go">bulunduğu yerde, render başına bir kez renklendirilir. elagoht/markdown ve çoğu Markdown renderer'ı bu biçimi yazar. Cache'lenen bir page renklendirildiği hâliyle sunulur.- Stylesheet yalnızca renklendirilmiş kod içeren page'lerden, içeriğe göre adlandırılmış bir adla link'lenir. Her tema kendi
prefers-color-schemesorgusu altındadır.noAuto: truebu block'lara dokunmaz, kodu yalnızca{{highlight}}renklendirir; v0.3.0'dan beri"auto": false'un yerini alır ve"auto"bilinmeyen bir key'dir. v0.2.0'dan beri otomatik geçiş stylesheet'iAfterRenderEvent.Hoistile hoist eder. Böylece stylesheet, layout'un{{hoist "head"}}koyduğu yere, o yoksa</head>'in önüne yerleşir.{{highlight}}ise layout'ta{{hoist "head"}}gerektirir.
elagoht/toc
github.com/Elagoht/collage-toc, bir page'in heading'lerine id verir ve template'lerin istediği yere bir içindekiler tablosu ve okuma süresi koyar.
import "github.com/Elagoht/collage-toc"
Plugins: []collage.Plugin{toc.New(toc.Options{})},
<aside>{{toc}}</aside>
<p>{{readingTime}}</p>
{
"elagoht/toc": {
"minLevel": 2,
"maxLevel": 4,
"wpm": 225,
"text": { "label": "Table of contents", "readingTime": "{n} min read" },
"locales": { "tr": { "label": "İçindekiler", "readingTime": "{n} dk okuma" } }
}
}
Config.Pluginsiçinde olmalıdır: template fonksiyonları ekler.- v0.2.0'dan beri varsayılan locale'in metinleri en üst seviyede değil,
textaltındadır (Options.Text, gömülü değil, adı olan bir alan); diğer locale'lerlocalesiçindedir."ids": falseartık"noIDs": true. En üst seviyede kalmış eski birlabelya daids, bilinmeyen key olarak uygulamayı durdurur. - Her fonksiyon bir placeholder yazar. Plugin, page render edildikten sonra onu doldurur:
<main>içindekih2–h4heading'lerini iç içe bir liste olarak ve kelime sayısınıwpm'e bölerek. id'si olmayan bir heading, metninden bir id alır. Her alfabenin harfleri korunur ve page'in dilinin küçülttüğü gibi küçük harfe çevrilir.noIDs, placeholder'ı olmayan bir page'e dokunmaz.- Kendi başına sunulan bir fragment page hook'larını çalıştırmaz. Bu yüzden
{{toc}}'u kendi başına yenilenen bir fragment'e değil, page'e koyun.
elagoht/search
github.com/Elagoht/collage-search, static bir siteye arama ekler: static build her page'in bir index'ini yazar, küçük bir script de bu index'te tarayıcıda arama yapar.
import "github.com/Elagoht/collage-search"
Plugins: []collage.Plugin{search.New(search.Options{})},
{{searchBox}}
{
"elagoht/search": {
"maxText": 5000,
"exclude": ["admin", "tags"],
"text": { "label": "Search" },
"locales": { "tr": { "label": "Ara", "noResults": "Sonuç yok" } }
}
}
Config.Pluginsiçinde olmalıdır:{{searchBox}}'ı ekler.- v0.2.0'dan beri
excludepath prefix'lerini değil, her locale'de dışarıda bırakılan page adlarını alır: eski bir"/admin/"ya da hiçbir page'in taşımadığı bir ad uygulamayı durdurur. Kutunun yazdıklarıtextaltındadır (label,placeholder,results,oneResult,noResults,unavailable);localesaynılarını locale başına tutar. - Index bir static build'e aittir.
collage export, her page'in title'ından, description'ından, heading'lerinden ve metnindensearch-index.json'ı yazar. Çalışan bir sunucuda index yoktur; arama kutusu bozulmak yerine bunu söyler. - Script page ile birlikte çekilir ve index'i kutuya ilk odaklanıldığında yükler. Her kelimeyi büyük/küçük harf ve aksan farkı gözetmeden eşleştirir, title'ları heading'lerin, heading'leri metnin üstünde sıralar ve page'in diliyle sınırlı kalır.
elagoht/i18n
github.com/Elagoht/collage-i18n, çeviri yapar: her locale için bir katalog, template'lerde page'in render edildiği locale'de {{t}}, çoğul biçimler ve finding olarak raporlanan eksik çeviriler.
import "github.com/Elagoht/collage-i18n"
//go:embed locales
var locales embed.FS
Plugins: []collage.Plugin{i18n.New(i18n.Options{FS: locales})},
<a href="{{pageURL "home"}}">{{t "nav.home"}}</a>
<p>{{tn "cart" .Count}}</p>
{ "elagoht/i18n": { "dir": "locales", "strict": true } }
Config.Pluginsiçinde olmalıdır: template fonksiyonları ekler. KataloglarOptions.FS'ten gelir, bu yüzden plugin Go'da kurulur.- Desteklenen her locale için iç içe key'lerden oluşan bir JSON dosyası olur:
locales/<locale>.json. Desteklenen bir locale'in dosyası yoksa uygulama başlamaz. tbir key'i çevirir ve{name}'i ad-değer çiftlerinden doldurur.tnbir sayı için çoğul biçimi seçer,thise katalogdan gelen markup'a izin verir. Bir data handleri18n.T(rc, key, pairs...)çağırır; v0.3.0'dan beri çiftler string'dir (i18n.T(rc, "visits", "n", strconv.Itoa(n))), template fonksiyonları ise hâlâ her değeri yazdırır.thher değeri düştüğü yere göre escape eder (v0.4.0'dan beri), tıpkı html/template'in orada{{.Value}}'yu escape ettiği gibi: katalogdaki markup güvenilirdir, onu dolduran değerler değildir. Metinde bir değer escape edilir; bir URL attribute'unda (href,src,action…)http:,https:,mailto:ya da göreli olmayan bir değer#ZgotmplZolur; tırnaksız bir attribute'ta boşlukları ve='i escape edilir, böylece yeni bir attribute ekleyemez. v0.3.0'a kadar bir değer nerede olursa olsun HTML-escape ediliyordu; bu yüzden<a href="{url}">içindeki birjavascript:değeri çalışan bir link oluşturuyordu. Bir tag'in ya da attribute'un içinde biten bir entry artık render'ı biri18n:hatasıyla başarısız kılar: tag'i katalogda kapatın. Güvenli bir URL ya da düz metin eskisi gibi render edilir; yalnızca bir URL'nin boşlukları ve ASCII olmayan harfleri artık percent-encode edilir.- Eksik bir key önce varsayılan locale'e, sonra key'in kendisine düşer. Development'ta page'in üzerinde, static build'de ise build raporunda
i18n-missingolarak raporlanır. Development'ta kataloglar her request'te yeniden okunur. - Render dışında (v0.2.0'dan beri), örneğin bir e-posta ya da arka plan işi için, plugin'in değerini saklayın:
tr.In(user.Locale)birTranslatordöndürür. Bu değerinT,TNveTHmetotları aynı katalogları, fallback'i ve çoğul biçimleri kullanır.Funcs()ise uygulamanın kendihtml/template'inet,tnvethverir. Uygulamanın desteklemediği bir locale varsayılan locale olur. Bulunamayan bir key, her key ve locale için bir kez loglanır. Kataloglarcollage.New'da değil, uygulama başlarken okunur. Ondan önce istenen bir çeviri key'in kendisini döndürür. - Bir katalogda olup diğerinde olmayan bir key başlangıçta loglanır ve build'de
i18n-untranslatedolarak listelenir. v0.2.0'dan beri bu iki yönde de yapılır (v0.3.0'dan önce kodlarmissing-translationveuntranslatedidi). Bir locale'in kuralının hiç seçmediği çoğul biçim sayılmaz,zerosayılır.strictaçıkken kataloglar farklıysa uygulama başlamaz. - Hem noktalı hem iç içe yazılmış bir key (
{"nav": {"home": …}}yanında{"nav.home": …}), v0.2.0'dan beri uygulamanın başlamasını engeller. Önceden hangi metnin gösterileceği map'in dolaşılma sırasına bağlıydı.
Form'lar ve state
Bir form'un bir action etrafında ihtiyaç duydukları: validation, spam koruması, redirect'ten sonra gösterilen bir mesaj, bir cookie'de tutulan session ve dosya upload'ları.
elagoht/validate
github.com/Elagoht/collage-validate, bir action'ın aldığı form'u doğrular: alan başına zincirlenebilen kontroller, status 422 ile yeniden render edilen reddedilmiş bir gönderim ve her alanın mesajını ve okuyucunun yazdığını form'a geri koyan template fonksiyonları.
import "github.com/Elagoht/collage-validate"
Plugins: []collage.Plugin{validate.New(validate.Options{})},
v := validate.Form(rc)
v.Field("email").Required().Email()
v.Field("password").Required().MinLen(8)
if !v.Valid() {
return validate.Refuse(rc, v, signupPage), nil
}
return collage.SeeOther("/welcome"), nil
Her alan, kontrol edilen değeri kendi tipinde geri verir (v0.3.0'dan beri):
servings := v.Field("servings").Required("Kaç porsiyon?").Int().Range(1, 50)
minutes := v.Field("minutes").Int() // isteğe bağlı
steps := v.Field("steps").Required().Lines() // her satırda bir tane olan bir <textarea>
tags := v.Field("tags").All().OneOf(tagNames...) // bir checkbox grubu
if !v.Valid() {
return validate.Refuse(rc, v, rc.Page), nil
}
create(servings.Value(), minutes.Ptr(), steps.Value(), tags.Value()) // int, *int, []string, []string
<input name="email" type="email" value="{{fieldValue "email"}}">
{{with fieldError "email"}}<p class="error">{{.}}</p>{{end}}
<!-- bir kayıttan başlayan form: kayıtlı ad ya da yazılan -->
<input name="fullname" value="{{fieldValue "fullname" .User.FullName}}">
{
"elagoht/validate": {
"messages": { "required": "Please fill this in." },
"localeMessages": { "tr": { "required": "Bu alan zorunludur." } },
"noRefill": ["pin", "card"]
}
}
Config.Pluginsiçinde olmalıdır:{{fieldError}},{{fieldValue}}ve{{hasErrors}}'ı ekler.{{fieldValue "name" fallback}}, reddedilen bir gönderimde gönderilen değeri, form ilk kez gösterildiğinde ise fallback'i gösterir. Bir profil ya da düzenleme form'u bu değerle başlar.- v0.1.2'den beri
validate.Form, bir kontrol ya dav.Valueform'a ihtiyaç duyana kadar hiçbir şey okumaz. Body'yi okumadan reddeden bir action (örneğinContent-Length'i sınırı aşan bir fotoğraf)v.Failvevalidate.Refuseiçin bir validator kurar ve body hiç okunmaz. v0.1.3'ten beri böyle bir ret, geri yazılacak bir şey olmadığı için her alanın fallback'ini gösterir. Action'ınWithMaxBodyBytesdeğeri kontrol ettiği boyutun üzerinde olmalıdır. Aksi halde önce collage'ın413'ü cevap verir. - collage'ın form kuralının ilk yarısıdır. Bkz. Form'lar ve action'lar. Kimsenin göndermediği bir page'de fonksiyonlar boştur. Bu yüzden tek bir template iki render'a da hizmet eder ve ilk render cache'lenebilir kalır.
- Kontroller
Required,MinLen,MaxLen,Email,URL,Int,Range,OneOf,Matches,EqualveCustom'dır.v.Fail, yalnızca uygulamanın bildiği bir durumu raporlar. Bir alan ilk mesajını korur.OneOfdışındaki her kontrol isteğe bağlı bir mesaj alır:Required("…"), arkasından gelen.Message("…")ile aynı işi görür (v0.3.0'dan beri). - Her kontrol kırpılmış değeri görür (v0.3.1'den beri):
Value()'nun döndürdüğü, kenarlarındaki boşluklar silinmiş değeri. ÖncedenMinLen,MaxLen,Email,OneOf,Matches,EqualveCustomdeğeri geldiği gibi görürdü; bu yüzdenValue()"x"döndürürkenMinLen(8)," x"'i geçirirdi. En az uzunluğa ulaşmak için boşlukla doldurulmuş bir değer artık reddedilir," m "OneOf("m")'den geçer,Equaliki alanı da kırpılmış karşılaştırır veCustomkırpılmış değeri alır. Yalnızca boşluktan oluşan bir değer,Required'da zaten olduğu gibi, her kontrol için boş sayılır;" "olarak gönderilen isteğe bağlı bir alan atlanır.v.Value(name)değeri hâlâ geldiği gibi döndürür. - Tipli değerler (v0.3.0'dan beri).
Field.Value(), kenarlarındaki boşluklar silinmiş string'dir.Int(),Float(),Bool()(checkbox),Date()(2026-10-25),All()(adın altında gelen tüm değerler) veLines()(bir textarea'nın satırları) alanı tipli bir alana çevirir. Bu alanınValue()'suint,float64,bool,time.Timeya da[]string'dir ve kontrolleri bu değer üzerinde çalışır:Min,Max,Range,MinItems,MaxItems,Custom(func(int) string). Boş bırakılan alandaPtr()nil'dir, yani isteğe bağlı bir alanın "verilmedi"si. Başarısız olan bir alan sıfır değerini verir.Int()artık*IntFielddöndürür: arkasından gelen bir string kontrolü artık derlenmez;.Int().Message(…)ve.Int().Range(…)çalışmaya devam eder. - Mesajlar varsayılan olarak İngilizcedir. Kontrol başına, locale başına ya da her locale için değiştirilebilir. Adında
passwordgeçen bir alan asla geri doldurulmaz.noRefillbu listeye kendi adlarınızı ekler (v0.2.0'dan beripassword'ün yerine geçmez). validate.Values(rc, values)(v0.2.0'dan beri), başka bir şeyin önceden okuduğu değerleri kontrol eder: örneğinuploads.Receive'in bir body'yi stream ettikten sonra geri verdiği alanlar.Refusebunları da aynı şekilde form'a geri yazar.- Alan adları render başına tek bir ad alanındadır: aynı page'de aynı alan adını paylaşan iki form, o alanın mesajını ve değerini ikisinde de gösterir. Her form'un alanlarına kendine ait adlar verin.
elagoht/honeypot
github.com/Elagoht/collage-honeypot, form spam'ini CAPTCHA olmadan durdurur. İnsanların hiç görmediği ama bot'ların doldurduğu bir tuzak alan kullanır. İmzalı bir zaman damgası da hiç servis edilmemiş, çok önce servis edilmiş ya da, form isterse, çok çabuk geri gönderilmiş bir form'u reddeder.
import "github.com/Elagoht/collage-honeypot"
Plugins: []collage.Plugin{honeypot.New(honeypot.Options{})},
<form method="post" action="/contact">
{{csrfToken}}
{{honeypot}}
<textarea name="message"></textarea>
<button>Send</button>
</form>
{
"elagoht/honeypot": {
"minDelay": "0s",
"maxAge": "24h",
"silent": false,
"protect": []
}
}
Config.Pluginsiçinde olmalıdır:{{honeypot}}'ı ekler.- v0.6.0'dan beri key, hiçbir şey ayarlanmadan
HONEYPOT_KEY'dan okunur:.env.development'a ve production'ın çalıştığı yereHONEYPOT_KEY=(openssl rand -hex 32) yazın.keyEnvbaşka bir değişkenin adını verir ve önceliklidir; ardındanOptions.Key, en sonHONEYPOT_KEYgelir. Adı verilen değişkenin ayarlı olması gerekir,HONEYPOT_KEYboş olabilir; ikisinden biri hex değilse uygulama başlamaz. - v0.5.0'da değişenler: hex
keykalktı. ArtıkkeyEnvkey'i tutan ortam değişkeninin adını verir, Go'dan iseOptions.Keybyte'ları doğrudan alır.maxAgeveminDelaysüre string'leridir ("24h","300ms").{{honeypot 0.3}}hâlâ saniye alır. Varsayılan"0s"bekleme olmadığı anlamına gelir (-1artık bir hatadır). Eski bir key ya da çıplak bir sayı, uygulamayı başlarken o key'in adını vererek durdurur. - Bir gönderimin ne kadar büyük olabileceğine karışmaz. Form'u
BeforeActionHook'ta, action'ın kendi body sınırıyla kontrol eder. Bu yüzden büyük dosya yükleyen bir form için yalnızca action'ınWithMaxBodyBytes'ı yeter. Yalnızca collage action'ları kontrol edilir,app.Handleile bağlanan handler'lar edilmez. - Hangi path'lerin korunduğunu form'lar söyler.
{{honeypot}}taşıyan bir form'un olduğu page servis edildikten sonra, o form'unaction'ına gönderilen form body'si action'a ulaşmadan önce kontrol edilir.{{honeypot}}taşımayan bir form hiç kontrol edilmez ve yapılandırmada form'ları tek tek yazmak gerekmez. JSON body'ler ve herGETkontrol edilmeden geçer. WithStreamingBody()ile kurulmuş bir action da kontrol edilmeden geçer: form'u hiç parse edilmez, dolayısıyla kontrol edilecek bir şey yoktur.- Process path'leri servis ettiği page'lerden öğrenir. Bir restart'tan ya da yeni bir sürümden sonra, form'un page'i yeniden servis edilene kadar, path'e doğrudan POST atan bir bot kontrol edilmez.
protect, ilk request'ten itibaren kontrol edilen prefix'leri listeler.["/"]sitenin kabul ettiği her form'u kontrol eder. v0.2.0'dan önce varsayılan buydu. - Bir process öğrendiği en fazla 4096 path'i tutar. v0.6.1'den beri yeni bir path için, form'u en uzun zamandır servis edilmemiş olan path unutulur ve en fazla dakikada bir uyarı log'lanır. Önceden öğrenme 4096'da dururdu: her path'e
{{honeypot}}'lu bir form'la cevap veren bir page, bir istemcinin kümeyi çöple doldurmasına ve henüz öğrenilmemiş her form'un restart'a kadar kontrolsüz kalmasına izin verirdi. Öğrenilmiş bir path üzerinden bir action'a ulaşan gönderim action'ın kendisini de işaretler; işaretli action artık her path'te kontrol edilir: kayıt 1'in yorum form'una gönderim yapıldıktan sonra kayıt 2'ninki de kontrol edilir. Bir action'ın böyle ilk gönderiminden önce path'i hâlâ dışarı itilebilir;protectbunu kapatır. Küme dolduğunda her form'u kontrol etmeye geçilmez, çünkü o zaman hiç{{honeypot}}taşımamış bir form (bir çıkış düğmesi, başka bir plugin'in form'u) reddedilirdi. - Varsayılan olarak bekleme süresi yoktur.
{{honeypot 0.3}}, form'un gönderilmeden önce en az o kadar saniye açık kalmasını ister. Süre zaman damgasına imzalanır, böylece bot onu kısaltamaz.minDelay, kendi süresini seçmeyen her form için bir süre ("300ms") belirler. - Zaman damgası, collage'ın forgery token'ı gibi page cache'ten sağ çıkar: cache'lenen page bir placeholder taşır, plugin de o anki zamanı imzalayıp
PersonaliseHookile, page cache'ten sonra ve sıkıştırmadan önce onun yerine koyar.Config.Pluginsiçindeki yeri fark etmez. (v0.4.0'dan önce elagoht/compress'ten önce listelenirse placeholder gzip'li body'de kalıyor ve her gerçek gönderim reddediliyordu.) Damgalanan bir pageCache-Control: private, no-store(collage ayarlar) ile ve her response'ta yeni birETagile gönderilir. En az 32 rastgele byte'lık, her instance'ta aynı olan bir key ayarlayın. Key,keyEnv'in adını verdiği değişkende hex olarak durur; aslaplugins-config.json'a girmez. - Yalnızca collage'ın render ettiği şey damgalanır: bir page, bir fragment, bir action'ın HTML cevabı, bir hata sayfası.
app.Handleile bağlanan elle yazılmış bir handler'ın kendi yazdığı placeholder olduğu gibi, damgasız gider. Onu taşıyan ve bir collage action'ına gönderilen form, action'ın path'i korunuyorsa (protect'te ya da başka bir form'dan öğrenilmiş) ya da action işaretliyse reddedilir, değilse hiç kontrol edilmez; böyle bir path'iprotect'e yazın. (v0.4.0'dan önce böyle bir response damgalanıyordu; türü ilk byte'lardan tahmin ediliyordu.) - Ret bir
400'dür.silentile ise kabul edilmiş bir form'un cevabı gibi, form'a geri dönen bir303'tür. Dikkatsiz bot'ları durdurur, kararlı birini durdurmaz; onu elagoht/ratelimit ile birlikte kullanın.
elagoht/flash
github.com/Elagoht/collage-flash, flash mesajları ekler: bir action'ın redirect etmeden önce ayarladığı ve redirect ettiği page'in bir kez gösterdiği mesaj.
import "github.com/Elagoht/collage-flash"
Plugins: []collage.Plugin{flash.New(flash.Options{})},
flash.Add(rc, flash.Success, "Your changes are saved.")
return collage.SeeOther("/settings"), nil
{{range flashes}}
<p class="flash flash--{{.Kind}}" role="status">{{.Text}}</p>
{{end}}
{
"elagoht/flash": {
"cookie": "collage_flash",
"maxAge": "5m"
}
}
Config.Pluginsiçinde olmalıdır:{{flashes}}'ı ekler.- v0.3.0'dan beri key, hiçbir şey ayarlanmadan
FLASH_KEY'dan okunur:.env.development'a ve production'ın çalıştığı yereFLASH_KEY=(openssl rand -hex 32) yazın.keyEnvbaşka bir değişkenin adını verir ve önceliklidir; ardındanOptions.Key, en sonFLASH_KEYgelir. Adı verilen değişkenin ayarlı olması gerekir,FLASH_KEYboş olabilir; ikisinden biri hex değilse uygulama başlamaz. - v0.2.0'da değişenler: hex
key, key'i tutan ortam değişkeninin adını verenkeyEnvoldu (Go'dakiOptions.Keydeğişmedi).maxAgesaniye yerine bir süre string'idir, varsayılanı"5m". Eski birkey, uygulamayıunknown key "key"ile durdurur. - Mesajlar imzalı,
HttpOnlybir cookie içinde taşınır.collage.IsHTTPSrequest'in HTTPS ile geldiğini söylediğinde cookieSecureolur. En az 32 rastgele byte'lık, her instance'ta aynı olan bir key ayarlayın. Key yoksa her process için bir key üretilir ve bir uyarı log'lanır. - En fazla 300 karakterlik sekiz mesaj tutulur ve v0.3.1'den beri cookie yazılırken ölçülür: tarayıcı dört kilobaytı aşan bir cookie'yi bütünüyle atar, bu yüzden
Set-Cookiesatırı asla 4096 byte'ı aşmaz. Encode edilince büyüyen metin (ASCII olmayan harfler ya da her biri altı byte olan<,>ve&) bu sınırı daha az mesajla aşabilir; o zaman geri kalanlar sığana kadar en eski mesajlar atılır, tek başına fazla büyük bir mesaj kısaltılır ve bir uyarı log'lanır. Önceden böyle bir cookie 6–7 KB'a ulaşır ve her mesaj sessizce kaybolurdu. - Mesaj taşıyan bir request yeniden render edilir. Page cache'ten okunmaz, ona yazılmaz da ve
private, no-storeolarak işaretlenir. Diğer her request, plugin yokmuş gibi sunulur.
elagoht/session
github.com/Elagoht/collage-session, session'ı bir cookie'de tutar: sitenin imzaladığı ve şifreleyebildiği küçük bir string map'i. Arkasında bir veritabanı yoktur.
import "github.com/Elagoht/collage-session"
Plugins: []collage.Plugin{session.New(session.Options{})},
s := session.Get(rc)
s.Regenerate()
if err := s.Set(session.UserKey, user.ID); err != nil {
return nil, err
}
return collage.SeeOther("/account"), nil
session.RequireUserPage taşıyan bir layout, giriş yapmamış okuyucuları sardığı her page'den uzak tutar. Bu, onları login adlı page'e gönderen bir guard'dır:
private := collage.NewFragment("private", "layouts/private.html").
WithGuard(session.RequireUserPage("login")).
Build()
{
"elagoht/session": {
"encrypt": true,
"maxAge": "168h",
"idleTimeout": "0s",
"sameSite": "lax"
}
}
- v0.5.0'dan beri key
SESSION_KEY'den, önceki key'ler deSESSION_PREVIOUS_KEYS'ten hiçbir şey ayarlanmadan okunur:.env.development'a ve production'ın çalıştığı yereSESSION_KEY=(openssl rand -hex 32) yazın.keyEnvvepreviousKeysEnvbaşka değişkenlerin adını verir ve önceliklidir; ardından Go'dan verilen option'lar, en son bu ikisi gelir. Adı verilen değişkenin ayarlı olması gerekir, bu ikisi boş olabilir; hex olmayan bir key uygulamanın başlamasını engeller. - Template fonksiyonu eklemediği için
RegisterPluginde onu kabul eder. - v0.3.0'da değişenler: key'ler artık
plugins-config.json'a girmez.keyEnvhex key'i tutan ortam değişkeninin,previousKeysEnvise önceki key'leri virgülle ayrılmış olarak tutan değişkenin adını verir. Go'danOptions.KeyveOptions.PreviousKeysbyte'ları doğrudan alır.maxAgeveidleTimeoutsaniye yerine süre string'leridir ("168h","30m"). Eski birkeyya dapreviousKeys, uygulamayıunknown keyile durdurur. RequireUser(loginPath)(v0.2.0'dan beri), session'ındasession.UserKey("user") altında bir değer bulunan okuyucuyu içeri alır. Diğer herkesi303ileloginPath'e gönderir; gitmek istedikleri yernextiçinde taşınır:/login?next=%2Fdashboard. Kendi query'si olan bir login path'i o query'yi korur.Require(key, loginPath)aynı işi herhangi bir key için yapar:Require("admin", "/login"). Plugin uygulamada yoksa guard, request'iErrNoSessionile başarısız kılar. Her okuyucuyu, onu asla içeri alamayacak bir login'e göndermez. Login action'ınext'e redirect etmeden öncenext'icollage.SafeRedirect'ten geçirin:collage.SafeRedirect(rc.Request.URL.Query().Get("next"), "/").RequireUserPage(loginPage)login page'inin path'ini yazmak yerine adını alanRequireUser'dır. Path her request içincollage.URLile, request'in locale'inde kurulur: Türkçe bir page'den/tr/giris?next=…. Böylece adı değişen ya da çevrilen bir path, guard'ı eski adreste bırakmaz.RequirePage(key, loginPage)aynısını herhangi bir key için yapar. Uygulamanın kaydetmediği bir ad, kimseyi içeri almak yerine request'i başarısız kılar.RequireGuest(homePath)veRequireGuestPage(homePage)(v0.6.0'dan beri) yalnızca giriş yapmamış okuyucunun işine yarayan page'leri korur: giriş, kayıt, unutulan şifre. Giriş yapmamış okuyucu geçer; giriş yapmış olan, request'tekinextcollage.SafeRedirect'e göre bu sitede bir path ise oraya, değilse home path'e ya da adı verilen page'e (request'in locale'inde)303ile gönderilir. Auth page'lerinin layout'unda:WithGuard(session.RequireGuestPage("account")).- Metotları
Get,Set,Delete,Clear,RegenerateveID'dir. Kendi handler'ınız session'ısession.FromContext(r.Context())ile okur. - Geçerli bir session taşıyan request yeniden render edilir. Page cache'ten okunmaz, ona yazılmaz da ve
private, no-storeolarak işaretlenir. Session'ı olmayan bir okuyucu eskisi gibi cache'ten sunulur. Session'ı cache'lenen bir page'den değil, bir action'dan ayarlayın. - Cookie
HttpOnlyveSameSite=Lax'tir, yalnızca session değiştiğinde yazılır vecollage.IsHTTPSrequest'in HTTPS ile geldiğini söylediğindeSecureolur. Key'ler önceki key'ler üzerinden döndürülür: bunlardan biriyle imzalı bir cookie kabul edilir ve güncel key ile yeniden yazılır. Bir session iptal edilemez, çünkü okuyucunun cookie'sinde yaşar. - Bir session, verildiği host'a bağlıdır (v0.7.0'dan beri): küçük harfe çevrilmiş ve port'u atılmış host imzalı payload'un içindedir; başka bir host'ta sunulan bir cookie orada session değildir (yok sayılır, silinmez). Birkaç siteyi tek key'le tek process'ten sunan bir uygulamada, yani elagoht/tenant'ın tenant'larında,
acme.test'tenglobex.test'e kopyalanan bir cookie orada anonimdir. Tek siteli bir uygulamadadomainayarlanırsa session host yerine domain'e bağlanır, böylece alt domain'leri onu paylaşır; tenant'larla (host'ları origin'lere çözen herhangi bir plugin'le) her host kendi sitesi olarak kalır, bu yüzden oradadomainayarlamayın. Host, request'inHost'udur: onu yeniden yazan bir proxy'nin arkasında orijinalHost'u iletin, yoksa her session proxy'ninkine bağlanır. - v0.7.0'dan önceki cookie'ler host taşımaz. Tek siteli bir uygulama böyle bir cookie'yi kabul eder ve geldiği host'a bağlı olarak yeniden yazar; böylece yükseltme kimsenin oturumunu kapatmaz. Çok siteli bir uygulama onu hangi tenant'ın verdiğini bilemez, bu yüzden reddeder ve siler: her okuyucu bir kez yeniden giriş yapar. Config'te hiçbir şey değişmez.
elagoht/uploads
github.com/Elagoht/collage-uploads dosya upload'larını alır. Her dosyayı içeriğine göre kontrol eder, rastgele bir key altında saklar ve sitenizin yerine geçmesine izin vermeden geri sunar. Önceden parse edilmiş bir form'u okuyabilir ya da body'yi part'lar hâlinde stream edebilir; sonuç ikisinde de aynıdır.
import "github.com/Elagoht/collage-uploads"
u := uploads.New(uploads.Options{Dir: "var/uploads"})
Plugins: []collage.Plugin{u},
got, err := u.Receive(rc,
uploads.Field("avatar", uploads.Rules{
MaxSize: 5 << 20,
MaxFiles: 1,
Types: []string{"image/png", "image/jpeg"},
}),
)
var rule *uploads.Error
if errors.As(err, &rule) {
// Show rule.Field's error beside the form; got.Values holds what was typed.
return showFormAgain(rc, got.Values, rule)
}
if err != nil {
return nil, err
}
avatar := got.Files["avatar"][0] // Key, Name, Type, SHA256, Size
app.Handle("/uploads/", u.Handler())
{
"elagoht/uploads": {
"dir": "var/uploads"
}
}
- Template fonksiyonu eklemediği için
RegisterPluginde onu kabul eder. Plugin'i bir değişkende tutun: actionu.Receive'i çağırır, uygulama dau.Handler()'ı bağlar. Bu mount hiçbir middleware olmadan çalışır. Dosyaları bir basicauth'un, bir session kontrolünün ya da elagoht/compress'in kapsaması gerekiyorsaapp.Handleçağrısınacollage.WithMiddleware()ekleyin. - v0.2.0'da değişenler: tek bir constructor var,
uploads.New(uploads.Options{…}):New(store)artıkNew(uploads.Options{Store: store}),NewWith(uploads.Config{Dir: d})iseNew(uploads.Options{Dir: d})'dir.Handlerargüman almaz;Cache-Controldeğeri yapılandırmadacacheControl, Go'daOptions.CacheControl'dür. Yapılandırma Go'dan bir store verildiğinde de okunur, bu yüzden bilinmeyen bir key orada da uygulamayı durdurur. - İki yol. Sıradan bir action'da,
{{csrfToken}}içeren düz bir<form enctype="multipart/form-data">JavaScript olmadan çalışır veReceiveparse edilmiş form'u okur. Bu, onlarca MB'a kadar dosyalar için uygundur.WithStreamingBody()ile kurulmuş bir action'da ise body'yiMultipartReaderile dolaşır ve her dosyayı doğrudan store'a stream eder. Böyle bir action token'ı yalnızcaX-CSRF-Tokenheader'ından alır, bu yüzden onafetch()ile post edin. Form'u önce parse eden her şey (validate.Formdahil) stream'i elden verir. Diğer field'larıgot.Values'tan okuyun. Streaming body'ler bölümüne bakın. - Tip içerikten belirlenir. Bir dosyanın tipi ilk 512 byte'ından sniff edilir. Adına, uzantısına ve
Content-Type'ına hiç bakılmaz. Çiğnenen bir kural, field'ı veErrTooLarge,ErrType,ErrTooManyya daErrUnexpectedField'dan birini taşıyan bir*uploads.Error'dır. - Ya hep ya hiç. Bir şey başarısız olursa (çiğnenen bir kural, giden bir client, limitini aşan bir body, store'un kendisi) o çağrının sakladığı her dosya
Receivedönmeden önce silinir. Başarılı olduktan sonra dosyalar sizindir. Action bundan sonra başarısız olursa onlarıu.Store().Deleteile silin. Dir, her dosyanın key'ini 128 rastgele bit ve sniff edilen tipe göre bir uzantıdan üretir. Böylece client'ın gönderdiği hiçbir şey bir path'e girmez.Name, client'ın temizlenmiş dosya adıdır ve yalnızca gösterim içindir. 0700'lük bir dizine 0600'lük dosyalar yazar, asla üzerine yazmaz ve yalnızca normal dosyaları okur. Metadata'yı (ad, sahip, upload zamanı) key'in yanında kendi veritabanınızda tutmak size kalır.Handler, bir dosyayı key'iyleX-Content-Type-Options: nosniff,Content-Security-Policy: sandboxve yeniden sniff edilmiş tipiyle sunar. Dosya bir PNG, JPEG, GIF ya da WebP resmi değilseContent-Disposition: attachmentekler. Erişim kontrolü yapmaz: key'i olan herkes dosyayı çekebilir. Bu yüzden özel dosyaları kendi action'ınızdan sunun. Dizini asla doğrudan sunmayın.- Kötüye kullanım ve disk. Upload action'ını koruyun (token bir kimlik doğrulama değildir),
MaxBodyBytes'ı veMaxSize'ı dar tutun, path'e rate limit koyun, store'u kendine ait bir volume'da tutun ve action'aWithBodyTimeoutverin. Proxy'ler için Deployment sayfasına bakın.Receiveile veritabanı yazmanız arasındaki bir çökme, hiçbir satırın göstermediği dosyalar bırakır. Dizini zaman zaman tarayıp veritabanınızın bilmediği eski key'leri silin. Bir saatten yeni.upload-*geçici dosyalarını atlayın, çünkü bunlar devam eden upload'lar olabilir.
Güvenlik
Bir sitenin göndermesi gereken header'lar, tek bir istemcinin siteye ne kadar hızlı istek atabileceğine bir sınır, henüz herkese açık olmayan bir sitenin önünde bir parola, bir kimlik sağlayıcısıyla giriş ve ziyaretçinin cookie onayı.
elagoht/secure
github.com/Elagoht/collage-secure, bir sitenin göndermesi gereken güvenlik header'larını ve nonce'ları page cache'ten sağ çıkan bir Content-Security-Policy'yi gönderir.
import "github.com/Elagoht/collage-secure"
Plugins: []collage.Plugin{secure.New(secure.Options{
CSP: "default-src 'self'; script-src 'self' 'nonce-{nonce}'",
})},
{
"elagoht/secure": {
"csp": "default-src 'self'; script-src 'self' 'nonce-{nonce}'",
"cspReportOnly": false,
"hsts": 63072000,
"hstsSubdomains": true,
"frameOptions": "DENY",
"permissionsPolicy": "camera=(), microphone=(), geolocation=()"
}
}
Config.Pluginsiçinde olmalıdır:{{cspNonce}}'ı ekler. Listedeki yeri fark etmez: nonce,PersonaliseHookile cache'ten sonra ve sıkıştırmadan önce yerleştirilir; bu yüzden elagoht/compress'ten önce de sonra da listelenebilir. (v0.2.0'dan önce compress'ten önce listelenirse marker gzip'li body'de kalıyor ve CSP her inline script'i engelliyordu.)- Varsayılan olarak
X-Content-Type-Options,X-Frame-Options,Referrer-PolicyveCross-Origin-Opener-Policygönderir.Strict-Transport-Security'yi ise TLS üzerinden ya daX-Forwarded-Proto: httpsgönderen bir proxy'nin arkasında gönderir. v0.3.0'dan beri bu header'a,Server.TrustedProxiesdoluysa yalnızca oradaki bir proxy'den geldiğinde inanılır (collage.IsHTTPS).Permissions-Policyve CSP, ayarlandıklarında gönderilir."-"bir header'ı dışarıda bırakır;X-Content-Type-Optionsda buna dahildir ("contentTypeOptions": "-"; v0.3.0'da"noSniff": false'un yerini aldı). - Policy'deki
{nonce}ile inline bir script'teki{{cspNonce}}aynı nonce'tur ve her response'ta yenidir. Cache'lenen page bir placeholder taşır, plugin'in hook'u da onun yerine taze bir nonce koyar. Nonce taşıyan bir pageCache-Control: private, no-store(collage ayarlar) ile ve her response'ta yeni birETagile gönderilir. Diğer her response conditional request'lere her zamanki gibi cevap verir: bir feed, bir document ya da mount edilmiş bir dosya304'ünü yine alır (v0.1.5'ten beri; öncesinde bir policy tanımlıysa plugin'in arkasındaki hiçbir şey alamıyordu). - Bir key ayarlayın: en az 32 rastgele byte, her instance'ta ve restart'larda aynı, hex olarak (
openssl rand -hex 32)SECURE_KEY'de; hiçbir şey ayarlanmadan okunur (v0.4.0'dan beri). Secret aslaplugins-config.json'a girmez:keyEnvbaşka bir değişkenin adını verir ve önceliklidir, ya daOptions.Keybyte'ları Go'dan alır veSECURE_KEY'e göre önceliklidir (v0.3.0;keyveOptions.KeyHexkaldırıldı). Key ile{{cspNonce}}placeholder'ı her process'te aynıdır; bu yüzden bir deploy'dan sağ çıkan disk cache'ten ya da birkaç instance'ın paylaştığı bir cache'ten gelen page de nonce'unu alır. Key yoksa placeholder process başına değişir ve böyle bir page başka bir process'in placeholder'ını taşır; kayıt süresi dolana kadar hiçbir header ile eşleşmez. Disk cache ya da birden fazla instance kullanıyorsanız key ayarlayın. Kısa bir key, adı verilmiş boş ya da hex olmayan bir değişken veya hex olmayan birSECURE_KEYuygulamanın başlamasını engeller; key'i gizli tutun. - Policy yoksa ya da policy
{nonce}içermiyorsa adlandırılacak bir nonce da yoktur:nonceattribute'u static build'deki gibi kaldırılır, page sabit birETagile cache'lenebilir kalır. - Static export'un yazdığı page'leri bu middleware hiç sunmaz ve bir dosya her response'ta değişen bir nonce taşıyamaz. Bu yüzden static build'de
nonceattribute'u kaldırılır, script yerinde kalır ve bir kez uyarı verilir. Bu inline script'lere host'un kendi policy'sinde izin verin (v0.1.2'den beri; öncesinde placeholder export edilen HTML'de kalıyordu). - Development'ta policy report-only olarak gönderilir. Böylece collage'ın live-reload script'i çalışmaya devam eder.
elagoht/ratelimit
github.com/Elagoht/collage-ratelimit, tek bir istemcinin siteye ne kadar hızlı istek atabileceğini sınırlar: istemci ve kural başına bir token bucket, bucket boşalınca da Retry-After ile bir 429 Too Many Requests.
import "github.com/Elagoht/collage-ratelimit"
Plugins: []collage.Plugin{ratelimit.New(ratelimit.Options{
Rules: []ratelimit.Rule{
{PathPrefix: "/login", Rate: 0.1, Burst: 5},
{Rate: 0.5, Burst: 10},
},
})},
{
"elagoht/ratelimit": {
"rules": [{ "pathPrefix": "/login", "rate": 0.1, "burst": 5 }],
"skip": ["/_collage/", "/healthz", "/readyz", "/api/webhooks"],
"ipv6Prefix": 48
}
}
- Hiç seçenek verilmezse her form ve action, yani
GET,HEADveOPTIONSdışındaki her metot, önce ondan oluşan bir burst'le, ardından iki saniyede bir request'le sınırlanır. - Bir request'i, eşleştiği ilk kural sayar. Bu yüzden dar kuralları başa koyun; her kuralın kendi bucket'ları vardır.
skip(varsayılanı/_collage/,/healthzve/readyz) ve bir kuralınpathPrefix'i tam segment eşleşir, sondaki/olsa da olmasa da:/login,/login-help'i kapsamaz. Response'larRateLimit-Limit,RateLimit-RemainingveRateLimit-Resettaşır. - Bir istemci IP adresidir, IPv6'da ise
/64'üdür. Bir reverse proxy'nin arkasında proxy'leri collage'ınServer.TrustedProxies'ine yazın; istemci o zamancollage.ClientIP'dir. Plugin'in kenditrustProxyvetrustedProxiesayarları v0.2.0'da kaldırıldı; bunları içeren eski bir yapılandırma başlangıçta durur. Go'dakiKeyFuncbaşka bir şeye göre key üretir. ipv6Prefix(v0.3.0'dan beri), bir IPv6 adresinin baştaki kaç bitinin istemciyi adlandırdığını belirler: 32 ile 128 arası, varsayılanı 64; IPv4 istemcileri her zaman tek bir adrestir. Bir/64saldırganın tamamı değildir: bir tunnel broker ücretsiz bir/48verir, birçok hosting sağlayıcısı da her sunucuya bir/48ya da/56verir; bu, her biri kendi bucket'ına sahip 65536 ya da 256/64demektir.48, bütün bir/48'i tek istemci ve tek bucket yapar; o/48'deki herkes onu paylaşır.128tek bir adrestir. Aralık dışındaki bir değer uygulamanın başlamasını engeller.- Bucket'lar memory'de tutulur, bu yüzden sınırlar process başınadır.
- v0.1.7'den beri static bir build'in header yakalaması sınırlanmaz ve
RateLimitheader'larını almaz.
elagoht/basicauth
github.com/Elagoht/collage-basicauth, bir sitenin önüne HTTP Basic authentication koyar: bir staging deploy'u, bir preview ya da henüz yayına girmemiş bir site için.
import "github.com/Elagoht/collage-basicauth"
Plugins: []collage.Plugin{basicauth.New(basicauth.Options{
Users: map[string]string{"team": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"},
})},
{
"elagoht/basicauth": {
"realm": "Staging",
"protect": ["/"],
"skip": ["/healthz", "/readyz", "/_collage/"],
"disabled": false
}
}
- Hiç kullanıcı yoksa,
disabledayarlanmadıkça uygulama başlamaz.skip'in varsayılanı/healthz,/readyzve/_collage/'dır. - collage'ın middleware'inden geçeni kapsar: her page, document, action, mount edilmiş dizin ve plugin handler'ı. Uygulamanın kendisinin
app.Handleile mount ettiği bir handler çıplaktır: onun için hiçbir middleware, bu plugin'inki de dahil, çalışmaz. Bu yüzden "korunan" bir staging host'ta böyle mount edilmiş bir API, webhook ya da upload handler'ı herkese cevap verir. Parolanın arkasına koymak içinapp.Handle("/api/", api, collage.WithMiddleware())ile mount edin;protectveskipona da her path'e olduğu gibi uygulanır. - Başarısız bir bcrypt kontrolünün bedeli her seferinde ödenir ve herkes
Authorization: Basic x:ygönderebilir. Dışarıya açık bir sitede elagoht/ratelimit'i basicauth'tan önce, her metodu sayan bir kuralla listeleyin (varsayılan kuralı, bir parola tahmincisinin gönderdiğiGET'i saymaz); böylece reddedilen bir tahmin, kontrolün bedeli ödenmeden önce sayılır:ratelimit.Rule{Methods: []string{"*"}, Rate: 5, Burst: 50}. - Parola düz metin olarak,
sha256:ve hex'i olarak ya da bir bcrypt hash'i olarak yazılır.COLLAGE_BASICAUTH_USERS, kullanıcıları environment'tan ekler ve secret'ları dosyaların dışında tutar. disabledya daCOLLAGE_BASICAUTH_DISABLED=true, aynı binary'nin bir deploy'unu, production'dakini, açık bırakır.- Kimliği doğrulanmış her response'ta
public,privateile değiştirilir ve responseVary: Authorizationtaşır. Böylece öndeki bir CDN, bir page'i sormadan sonraki okuyucuya vermez. Siteyi HTTPS üzerinden sunun. - Static build'in header yakalaması geçirilir; böylece deploy edilen bir page bir
401'in header'larını taşımaz. Korunan bir path'in altına dosya yazan bir buildbasicauth-exporteduyarısı verir: static bir host bu dosyaları parolasız sunar. Onları host'ta koruyun ya da build'in dışında bırakın.
elagoht/oauth
github.com/Elagoht/collage-oauth, okuyucuyu bir OpenID Connect sağlayıcısıyla (Google, Microsoft, GitLab ya da discovery document'ı olan herhangi biri) giriş yaptırır. İsterseniz sağlayıcının API token'larını da saklar, böylece uygulama okuyucu adına sağlayıcıyı çağırabilir. Kullanıcıları uygulama kendisi tutar: siz kendi kullanıcı ID'nizle cevap verirsiniz, plugin de okuyucuyu elagoht/session üzerinden giriş yaptırır. Bu yüzden session.RequireUser guard'ları değişmeden çalışır.
import "github.com/Elagoht/collage-oauth"
Plugins: []collage.Plugin{
session.New(session.Options{}),
oauth.New(oauth.Options{
Providers: []oauth.Provider{{
Name: "google",
Preset: "google",
ClientID: "1234-abcd.apps.googleusercontent.com",
ClientSecretEnv: "GOOGLE_CLIENT_SECRET",
}},
OnLogin: func(ctx context.Context, id oauth.Identity) (string, error) {
return users.FindOrCreate(ctx, id.Provider, id.Subject, id.Name)
},
}),
},
<a href="{{oauthLogin "google"}}">Google ile giriş yap</a>
{
"elagoht/oauth": {
"providers": [
{ "name": "google", "preset": "google", "clientID": "1234-abcd.apps.googleusercontent.com",
"clientSecretEnv": "GOOGLE_CLIENT_SECRET", "offline": true }
],
"afterLogin": "/account",
"errorPath": "/sign-in-failed"
}
}
- elagoht/session v0.3.0 ya da sonrasını gerektirir. Session de register edilmelidir: yoksa login route'ları
500döner.collage plugin add elagoht/oauthönce elagoht/session'ı ekler.OnLoginveStorekod olduğu için onları Go'da verin. Secret ve key ortam değişkeninde durur: dosya yalnızca değişkenlerin adınıclientSecretEnv,keyEnvvepreviousKeysEnvile verir (v0.2.0'dan beri;key,previousKeysveOptions.KeyHexkaldırıldı, eski bir yapılandırma başlangıçta durur). - v0.3.0'dan beri ne
keyEnv/previousKeysEnvne de Go option'ları key vermezse keyOAUTH_KEY'den, önceki key'lerOAUTH_PREVIOUS_KEYS'ten okunur:Storetoken saklıyorsa.env.development'a ve production'ın çalıştığı yereOAUTH_KEY=(openssl rand -hex 32) yazın. Bu ikisi boş olabilir; içlerinde hex olmayan bir key uygulamanın başlamasını engeller. - Route'lar
{prefix}/{name}/loginve{prefix}/{name}/callback'tir (prefix/auth), yalnızcaGET. Sağlayıcıya{origin}/auth/google/callbackadresini kaydedin. OriginConfig.BaseURL'dür ya da elagoht/tenant gibi bir origin resolver'ın isteğin host'u için söylediğidir. Bu yüzden çok kiracılı bir sitede her host'un adresi ayrı kaydedilir. - Bir
issuerhttpsolmalıdır (düzhttpyalnızcalocalhost'a ya da bir loopback IP'ye), yoksa site başlamaz. Böyle olmayan bir endpoint adlandıran discovery document girişiunavailableile bitirir. Token ve revocation çağrıları hiçbir redirect'i izlemez. elagoht/session'ınsameSiteayarını varsayılanı olan"lax"'ta bırakın:"strict"ile session cookie'si sağlayıcıdan dönüşte gönderilmez ve okuyucunun session'ı giriş yapmış hale gelmek yerine yenisiyle değiştirilir. - Bekleyen giriş kendi cookie'sinde tutulur (v0.3.1'den beri), session'da değil:
collage_oauth,Path=/auth/<provider>/(prefix'in altında; böylece yalnızca o sağlayıcının iki route'una gider, hiçbir page'e gitmez), on dakika,HttpOnly,SameSite=Lax, HTTPS üzerindenSecure, ve sonucu ne olursa olsun callback tarafından silinir. Bir girişi herkes başlatabilir; session ise imzalıdır,maxAgeboyunca yaşar ve taşıyanı için page cache'i kapatır: önceden login route'una tek bir anonimGET, herkese böyle bir cookie verirdi. Artık session'ı yalnızca başarılı bir callback başlatır; başarısız bir giriş hiç session başlatmaz. Cookie'yi 4096 byte'ın üzerine çıkaracak birnextafterLogin'de biter. Yapılandırmada değiştirilecek bir şey yoktur; yükseltme sırasında süren bir girişstateile başarısız olur. Önceki bir sürümün bu yolla ürettiği session'lar, session key'i değiştirilmezsemaxAgesonuna kadar geçerli kalır. microsoftpreset'i tek başına her Entra ID tenant'ını ve her kişisel Microsoft hesabını kabul eder. Yalnızca bir tenant'ı kabul etmek içinissuer'ı onunkine ayarlayın (https://login.microsoftonline.com/<tenant-id>/v2.0): ayarlanmış bir issuer birebir eşleşmelidir. Microsoftemail_verifiedgöndermez, bu yüzden onun içinEmailVerifiedfalse'tur.offline, preset'i olmayan bir sağlayıcıdanoffline_accessscope'unu ister.- Bir giriş
state,nonceve PKCE kullanır, id_token'ın claim'lerini kontrol eder, session'a yeni bir ID verir (ya da bir session başlatır) ve okuyucuyucollage.SafeRedirectile kontrol edilmişnext'e, kontrol edildiği haliyle gönderir. Başarısız bir giriş kimseyi giriş yapmış bırakmaz:errorPath?error=<kod>ile açılır (state,expired,denied,rejected,exchange,token,unavailable), yoksa sitenin status page'i gösterilir. - Hesapları
Provider+Subjectile eşleyin. E-postaya da yalnızcaEmailVerifiedtrue ise güvenin: doğrulanmamış bir adresle hesap eşlemek, bir okuyucunun başkasının hesabını ele geçirmesine yol açar. - Bir
Storeve bir key (en az 32 byte: Go'danOptions.Keyya dakeyEnv'in adını verdiği değişkende hex) verilirse token'lar AES-256-GCM ile mühürlenerek saklanır.plug.Client(ctx, userID, "google"), kullanıcının token'ını gönderen ve yenileyen bir*http.Clientdöndürür.errors.Is(err, oauth.ErrNotLinked)okuyucuyu yeniden girişe göndermek demektir;Revokebağlantıyı koparır. Key'i değiştirmek için eskisiniPreviousKeys'e (ya dapreviousKeysEnv'in adını verdiği değişkene, virgülle ayrılmış hex olarak) taşıyın. Token yalnızca ilk gittiği host'a ya da onun subdomain'lerine gider. - Sınırlar: GitHub yok (OpenID Connect değil), hesap bağlama yok ve id_token'ın imzası kontrol edilmez (token endpoint'inden TLS üzerinden gelir, OpenID Connect Core buna izin verir). Refresh birleştirme süreç başınadır. Bir guard'ın ya da action'ın redirect'i kontrolsüz kalır: yalnızca
nextkontrol edilir.
elagoht/fail2ban
github.com/Elagoht/collage-fail2ban, bir siteyi yoklayan ya da brute-force eden istemcileri banlar. İstemci başına strike'ları adlandırılmış jail'lerde sayar; bir jail'in sınırına ulaşan istemci ban süresi boyunca düz bir 403 alır.
import "github.com/Elagoht/collage-fail2ban"
bans := make(chan fail2ban.Ban, 100) // uyarıları toplayan kendi goroutine'iniz okur
f2b := fail2ban.New(fail2ban.Options{
OnBan: func(b fail2ban.Ban) {
select {
case bans <- b:
default: // dolu: request'i bekletmek yerine bırak
}
},
})
Plugins: []collage.Plugin{f2b /* , diğerleri */},
{
"elagoht/fail2ban": {
"jails": {
"probe": { "banTime": "6h" },
"notfound": { "disabled": true }
},
"allow": ["203.0.113.7", "10.0.0.0/8"],
"ipv6Prefix": 48
}
}
collage.Duration'ı,Server.TrustedProxies'i,collage.ClientIP'yi ve collage'ın routing'den önce reddettiği request'leri de gören birRequestHook'u kullanır.Config.Plugins'te ilk sıraya koyun, elagoht/health kullanılıyorsa onun arkasına; böylece ban kontrolü diğer plugin'lerin middleware'inden önce çalışır ve health'in probe'ları bir ban yüzünden reddedilmez.elagoht/accesslogondan önce gelebilir: yalnızca satırı yazar ve ilk sırada bir ban'ın403'ünü byte sayısıyla loglar (sonra listelenirse de accesslog v0.3.0'dan beri reddi loglar, byte sayısı olmadan).- İstemci, forwarded zincirinden anlaşılamadığında (adres olmayan bir girdi) ve bağlantının kendi adresi,
RemoteAddr, kullanıldığında plugin bunu bir kez Warn seviyesinde loglar (v0.2.1'den beri). Sınırlama değişmez. - Bir reverse proxy ya da CDN'in arkasında
Server.TrustedProxies'i ayarlayın. Ayarlanmazsa istemci proxy'nin kendisi olur: tek bir tarayıcı bot proxy'nizin banlanmasına, onunla birlikte her ziyaretçinin banlanmasına yol açar. Bir CDN'in yayımladığı aralıklar dahil her hop'u yazın. Unutursanız, loopback ya da private bir adresten gelen,X-Forwarded-Fortaşıyan amaClientIP'si yine o adres olan bir request sayılmaz ve tek bir WarnTrustedProxies'in muhtemelen eksik olduğunu söyler. Bir istemci bir IPv4 adresidir, IPv6'da ise bir/64. ipv6Prefix(v0.3.0'dan beri), bir IPv6 adresinin baştaki kaç bitinin istemciyi adlandırdığını belirler: 32 ile 128 arası, varsayılanı 64; IPv4 istemcileri her zaman tek bir adrestir. Bir/48sahibinin (ücretsiz bir tunnel broker tahsisi ya da bir sunucununki) her biri kendi strike'ları ve ban'ı olan 65536/64'ü vardır.48, bütün/48'i tek istemci yapar: strike'ları toplanır ve ban'ı hepsini kapsar, bedeli o bloktaki herkesin de banlanmasıdır.128tek bir adrestir. Aralık dışındaki bir değer uygulamanın başlamasını engeller.allow'daki bir adres, banlı bir bloğun içinde olsa da asla reddedilmez; birBan'ınPrefix'i bloğunkidir.probejail'i (10miçinde 3 strike,1hban) bir probe path'i isteyen (/.env,/.git/,/wp-login.phpgibi, ayrıca herhangi bir yerde.envile başlayan ya da.gitolan bir segment; kendinizinkiniprobePathsile ekleyin) ya da collage'ın encoded slash ya da./..segment'i yüzünden erkenden reddettiği request'e strike verir. Sitenizin gerçekten page, document ya da action olarak sunduğu bir probe path'i,404ya da başka bir hatayla yanıtlanmadıkça sayılmaz.notfoundjail'i (1miçinde 50,10mban) diğer her404'e strike verir, bir mount'unki hariç. Tarayıcının bir alt kaynak request'i (imageya dascriptgibi birSec-Fetch-Dest) asla strike vermez;Sec-Fetch-Site: cross-siteolarak işaretlenmiş bir request de (no-cors bir fetch, gizli bir iframe, başka bir siteden bir link) vermez. Bu, bu header'ları gönderen tarayıcılarda başka bir sitedeki sayfanın okurlarınızı banlatmasını engeller; sizin bir subdomain'inizdeki bir sayfa ya da kendi origin'inizdeki kullanıcı içeriği iframe ya da fetch ile yine strike verdirir. Bu header'ları taklit eden bir tarayıcı bot fark edilmez. Kendi jail'iniz yalnızcaReport'ta strike verir; herhangi birini adıyla override edebilir ya da"disabled": trueile kapatabilirsiniz (v0.2.0'a kadar"off"). Süreler string olarak yazılır ("10m","1h30m");"banTime": 3600gibi çıplak bir sayı, key'i adlandırarak uygulamayı durdurur.- Tekrarlanan ban iki katına çıkar,
maxBanTime'a (24h) kadar. Banlı istemci düz bir403 Forbiddenalır, sitenin error page'ini asla. Encoded slash'li ya da kirli path'li bir request için collage'ın kendi404'ü ya da redirect'i yine de ona ulaşır. - Ban bir middleware'dir. Düz
app.Handleile mount edilmiş bir handler hiçbir middleware çalıştırmaz. Bu yüzden ban'lı bir istemci,/api/'ye yönelik login brute force'u dahil, ona tam erişimini korur; oradaki yoklamaları ise yine sayılır. Onu da kapsamak için handler'ıcollage.WithMiddleware()ile mount edin. Bkz. İstemedikçe middleware yok. - Başarısız bir login'de
Report(r, "login")çağırın.Forgive(r, "login")strike'ları siler, ama yalnızca başarı, şifresi tahmin edilen hesabın kendisi içinse güvenlidir: her başarıyı affetmek, kendi hesabı olan bir saldırganın sınırsız tahmin yapmasına izin verir. Başarısız denemeler zatenfindTimesonunda düşer.allow, hiç sayılmayan ve banlanmayan adresleri ve aralıkları listeler.Ban,UnbanveBanselle kullanılan API'dir (Banbir ban'ı asla kısaltmaz);OnBan(yalnızca Go) her ban'dan sonra çağrılır, dağıtık bir taramada belki binlerce kez, bu yüzden her ban için senkron bildirim göndermeyin. - Ban'lar process başınadır ve memory'de tutulur: instance'lar paylaşmaz, restart hepsini siler. Dev modunda
inDevelopmentayarlanmadıkça hiçbir şey olmaz. Strike'lardan sonra tepki verir;elagoht/ratelimit'in yerine geçmez. maxTracked(10000) strike sayaçlarını sınırlar, en uzun zaman önce strike almış istemciyi düşürür;maxBans(10000) ban kayıtlarını sınırlar. v0.3.0'dan beri süren bir ban asla çıkarılmaz: sınırda yalnızca bitmiş bir ban (tekrarlanan ban iki katına çıksın diye tutulan kayıt) yer açar. Tablo süren ban'larla doluyken yeni bir suçlu banlanmaz; strike'ları tutulur ve bir ban biter bitmez banlanır. En fazla dakikada bir birWarn,fail2ban: the ban table is fullder; Go'danBanda aynı şekilde reddedilir. Önceden bir saldırgan,maxBanskadar başka adresi banlatarak kendi ban'ını kaldırabilirdi.maxBans'i yükseltin ya da suçlular tek bir/48'in/64'leriyseipv6Prefix'i48yapın.
elagoht/consent
github.com/Elagoht/collage-consent, bir cookie onay banner'ı ekler, script'leri ve iframe'leri kategorileri onaylanana kadar bekletir ve page'e ziyaretçinin seçimini okuması için küçük bir JS API verir. Listelediğiniz path'lerde sunucu da seçimi okuyabilir.
import "github.com/Elagoht/collage-consent"
Plugins: []collage.Plugin{consent.New(consent.Options{})}, // plugins-config.json'dan yapılandırılır
{
"elagoht/consent": {
"version": 1,
"categories": [
{ "name": "necessary", "required": true },
{ "name": "analytics" },
{ "name": "media" }
],
"text": {
"title": "Çerezler", "body": "Ziyaretleri ölçmek ve gömülü medyayı göstermek için çerez kullanıyoruz.",
"accept": "Tümünü kabul et", "reject": "Tümünü reddet", "save": "Seçimleri kaydet", "settings": "Seç",
"placeholder": "Bu içerik {host} adresinden yüklenir.", "allow": "{category} kategorisine izin ver",
"categories": { "necessary": "Gerekli", "analytics": "Analitik", "media": "Gömülü medya" }
},
"locales": {
"en": { "title": "Cookies", "accept": "Accept all", "reject": "Reject all" }
},
"policyURL": "/gizlilik",
"maxAgeDays": 180,
"serverPaths": []
}
}
Layout'ta
{{hoist "head"}}ister. Bu işaret yoksa hiçbir şey görünmez ve bekletilen hiçbir şey çalışmaz.Onay tarayıcıda verilir. Her ziyaretçi aynı HTML'i alır, bu yüzden page cache eskisi gibi çalışır.
version'ı artırmak herkese yeniden sorar.requiredbir kategori her zaman onaylıdır ve cookie'ye yazılmaz.textvarsayılan locale'in metnidir ve her kategoriyi etiketlemelidir; diğer locale'lerlocales'te durur ve eksik key'leritext'ten alır (v0.2.0'dan beri; eskitext: {"tr": {…}}biçimi locale key'ini adlandırarak uygulamayı durdurur).Onay gerektiren şeyi, yazıldığı haliyle çalışmayacak biçimde işaretleyin. Kategori onaylanınca bekletilen script gerçek bir script olur ve document sırasıyla çalışır, bekletilen iframe
src'sini alır. O ana kadar iframe'in yerinde bir placeholder butonu durur; fragment swap'ı ya da bir router'ın sonradan eklediği markup da aynı şekilde bekletilir:<script type="text/plain" data-consent="analytics" src="https://example.com/a.js"></script> <iframe data-consent="media" data-src="https://www.youtube-nocookie.com/embed/…" title="…"></iframe>Bekletilen script module olamaz. İçeriği çalışmış bir kategori geri alınırsa page yeniden yüklenir.
JS API:
collageConsent.get()(onaylı kategoriler, sıralı),collageConsent.set({ analytics: true }),collageConsent.open()ve her kayıttan sonradocumentüzerindecollage:consentevent'i.data-consent-opentaşıyan bir element banner'ı yeniden açar. Banner bir<dialog>'dur ve--consent-*custom property'leriyle özelleştirilir.Sunucu tarafında path'leri
serverPaths'e yazın (tam segment eşleşir:/shop,/shop/cart'ı kapsar,/shopping'i kapsamaz), sonra oradaki bir data handler'daconsent.Granted(rc, "analytics")çağırın. Page cache cookie başına değil, seçim başına bir kayıt tutar.serverPathsdışında, static export'ta ve build'in capture request'indeGrantedfalse döner (requiredkategori için true). Bu path'lerdeki her responseVary: Cookietaşır; çoğu CDN bunu cache'lemez, bu yüzden yalnızca HTML'i seçime göre değişmesi gereken page'leri listeleyin. Stream path'lerini asla listelemeyin: collage-live'ın/_live/ve/_collage/path'leri hiçbir zaman varied edilmez.Seçim,
collage_consentadlı first-party cookie'de tutulur ve script onu okur. Bu yüzden onu sunucudan ya daHttpOnlyolarak asla ayarlamayın.GPC (
navigator.globalPrivacyControl) isteğe bağlı kutuları işaretsiz bırakır; "Tümünü kabul et" yine her şeyi onaylar. Do Not Track okunmaz.Content-Security-Policy: script tag'inde nonce yoktur, bu yüzden
script-src'self'içermelidir; yalnızca nonce'a dayanan ya da'strict-dynamic'kullanan bir policy onu engeller. Banner'ın stylesheet'ini script üretir, bu yüzdenstyle-srconun hash'ine izin vermelidir; güncel hash plugin'in README'sindedir ('unsafe-inline'de işe yarar). Bekletilen inline script'in kendinonce'u ya da metninin'sha256-…'hash'iscript-src'de bulunmalıdır.collage-live ile itilen bir fragment kendi path'i için middleware'den geçer:
serverPaths'in kapsadığı bir path'te okuyucunun kendi seçimini okur ve paylaşılmadan o okuyucu için render edilir. Static export script'i page'lerin yanına yazar ve karar tarayıcıda verilir; bu yüzden export edilmiş page'ler sunucuda her zaman "onaylanmadı" olarak render edilir.Granted, render ettiği App'in yapılandırmasını okur (v0.2.0'dan beri; öncesinde en son initialize edilen App'inkini) ve render context yoksa,requiredbir kategori için bile false döner. Analytics için elagoht/analytics'teconsentCategoryayarlayın.
Canlı güncellemeler
Bir page'in parçalarını, istemcide bir framework olmadan tarayıcıda güncel tutmak.
elagoht/live
github.com/Elagoht/collage-live, bir page'in parçalarını tarayıcıda güncel tutar. Bir page'in WithFragmentPath ile açtığı fragment'leri yenileyen küçük bir client script'i sunar. Yenileme belli aralıklarla ya da sunucu bir event stream üzerinden bir değişiklik gönderdiğinde yapılır.
import (
client "github.com/Elagoht/collage-client"
live "github.com/Elagoht/collage-live"
)
Plugins: []collage.Plugin{client.New(), live.New(live.Options{})},
{
"elagoht/live": { "prefix": "/_live/", "noStream": false, "keepAlive": "25s", "maxFragments": 32, "maxStreamAge": "0s" }
}
<head>
{{liveClient}}
</head>
<section data-collage-fragment="{{fragmentURL "home" "cpu"}}" data-collage-interval="2s">
{{slot "cpu"}}
</section>
<section data-collage-fragment="{{fragmentURL "home" "disks"}}" data-collage-push>
{{slot "disks"}}
</section>
Config.Pluginsiçinde olmalıdır, çünkü layout'un client'ı eklemek için çağırdığı{{liveClient}}'ı ekler. elagoht/client v0.2.0'ı gerektirir: her cevap page'e collage-client'ıncollage.put'u ile girer.collage plugin add elagoht/liveclient'ı da ekler; client yoksacollage.Newbaşarısız olur.{{liveClient}}, client'ın script'ini kendi script'inden önce yazar. Bu yüzden layout değişmez,{{clientjs}}'i de çağıran bir layout ise script'i bir kez yükler.- Başka bir plugin'in transport'u, örneğin elagoht/websocket,
UseTransport'uInit'inin yanı sıraConfigure'ından da çağırabilir; son çağrı geçerlidir (v0.5.2). keepAlivevemaxStreamAgesüre string'leridir (live.Optionsiçindecollage.Duration): bir sayı, negatif bir süre ya da negatif birmaxFragmentsuygulamayı durdurur,nullise varsayılanı bırakır. v0.5.0'dan berilive.New()velive.NewWith(live.Config{…})tek birlive.New(live.Options{…})oldu.- Container'ın sahibi page'dir, içindekinin sahibi fragment'tir.
data-collage-intervalbelli aralıklarla fetch eder,data-collage-pushfragment'i stream'den alır,data-collage-swap="morph"DOM'u collage-client'ın morph'uyla yerinde patch eder. Bir form üzerindekidata-collage-targetise form'ufetchile gönderir ve cevabı bir element'in içine koyar. Bunu başarı durumunda ya da bir422geldiğinde yapar. Bir action, bir gönderimin validation'dan geçmediğini böyle söyler: form'un fragment'ini hatalarla birlikte ve 422 status'uyla yeniden döndürür (bkz. Form'lar ve action'lar). Başka her hata hedefi olduğu gibi bırakır ve onu stale olarak işaretler. v0.2.1'den beri action'ı redirect eden bir form, collage'ınCollage-Fetchheader'ı sayesinde tek request'te yönlendirilir. - v0.6.0'dan beri morph, idiomorph'unkidir ve element'leri id'lerine göre eşleştirir. Eskisi onları sıralarına göre eşleştiriyordu. Bu yüzden bir listenin başına eklenen bir öğe, ondan sonraki her öğeyi yeniden kuruyor, yazı yazılan bir alan da metnini ve focus'unu kaybediyordu. Focus'taki bir alan değerini yine korur, ama focus'taki bir
<select>'in option'ları artık sunucununkileri alır.collage:swapcollage-client'tan gelir vedetail: { url: null, mode, inner: true }taşır. - Client elindeki
ETag'i gönderir ve304gelirse DOM'a dokunmaz. Fragment'in hoist ettiklerini key'lerine göre head'e bir kez ekler. Gizli bir sekmede durur. Bir request başarısız olduğunda element'idata-collage-staleile işaretler ve beklemeyi artırır. Gönderilen bir kopya, polling'in alacağı ETag'in aynısını taşır. Bu yüzden client'ın zaten elinde olan bir kopya yeniden gönderilmez. - Bir element'i sabit tutmak (v0.3.0'dan beri). Okuyucu bir işin ortasındayken (bir sürükleme, açık tutulan bir menü)
collageLive.pause(el)element'i sabit tutar. Poll'lar, push'lar ve form cevapları gelmeye devam eder, ama yalnızca en sonuncusu saklanır vecollageLive.resume(el)onu yerine koyar. Bir fragment'in içindeki element o fragment'i gösterir, yani sürüklemenin başladığı liste etrafındaki board'u sabit tutar. Pause'lar iç içe geçebilir ve sabit tutulan elementdata-collage-pausedtaşır.collageLive.put(el, html), sayfanın kendi aldığı bir cevabı (bir action'ın fragment'ini) bir form cevabı gibi yerine koyar. DOM'u doğrudan patch etmek, client'ın element'te hâlâ en son koyduğu içeriğin durduğunu sanmasına yol açardı. Sürükle-bırak örneği README'de. - Swap'e animasyon eklemek (v0.4.0'dan beri). Bir view transition DOM değişmeden önce başlamalıdır,
collage:swapise değişiklikten sonra tetiklenir.data-collage-transitionher cevabıdocument.startViewTransitioniçinde yerine koyar: push'lar, poll'lar, form cevapları veputda dahil. Böylece bir cevaptan diğerineview-transition-name'ini koruyan kartlar yeni yerlerine kayar. API yoksa ya daprefers-reduced-motion: reduceaçıksa cevap hemen yerine konur. Daha fazla kontrol içincollage:before-swap, element değişmeden hemen önce element üzerinde tetiklenir.preventDefaultçağıran bir listenere.detail.swap()'i kendisi, kendi transition'ı içinde çalıştırır ve hareket edecek element'lere swap'ten önce ve sonra isim verir. Daha yeni bir cevaptan sonra geç çağrılanswap()hiçbir şey yapmaz. Element sabit tutulurken çağrılan birswap()ise element resume edilene kadar bekler. Örnek README'de. - Tarayıcı başına tek bağlantı. Bir tarayıcı HTTP/1.1 üzerinden bir origin'e, tüm sekmeleri toplamında en fazla altı bağlantı açar. Bu yüzden v0.2.0'dan beri client stream'i, sitenin tüm sekmelerinin paylaştığı bir shared worker'dan açar. Shared worker olmayan yerlerde her sekme kendi stream'ini açar ve gizliyken kapatır. v0.2.1'den beri back-forward cache'ten dönen bir sekme yeniden push alır. Önceden worker, sekme ayrıldığında onu unutuyordu.
- Stream kapalıyken gönderilen element'ler stale olarak işaretlenir. Üç başarısız bağlantıdan sonra beş saniyede bir polling ile yenilenir ve stream dakikada bir yeniden denenir.
- Gönderme tag'lere dayanır. Uygulama bir tag'i invalidate ettiğinde plugin, o tag'e bağlı her açık fragment'i yeniden render eder ve stream'den gönderir. API'nin tamamı invalidate etmektir.
- Örneklenen veri (CPU yükü, bir kuyruğun uzunluğu gibi), fragment başına bir tag ile bir timer'la invalidate edilerek gönderilir. Böyle bir fragment'i
Static()ile değil,Shared()ile işaretleyin. Böylece page dynamic kalırken collage fragment'i sekme başına değil, her değişiklikte bir kez render eder. Aynı ölçümü okuyan birkaç fragment onu tag'siz bircollage.Cachedile çeker. Böylece bir fragment'in tick'i diğerlerini yeniden render ettirmez.Sharedolmayan bir fragment her bağlantı için render edilir; data cache açıkkenCached, çektiğini bir kez çekilmiş tutar. Bir sistem monitörü örneği README'de adım adım anlatılır. - Her push tek bir bağlantı için yapılır, o bağlantının kendi request'iyle, ve yalnızca ona gönderilir: fragment'in URL'sine giden, uygulamanın ve her plugin'in middleware'inin, ardından guard'ların cevapladığı bir request'tir. Bunlardan birinin reddettiği bir okuyucuya (sunucuda iptal edilmiş bir session, değişmiş kimlik bilgileri, bir ban) fragment yerine bir stale mesajı gönderilir, hiçbir guard'ın kapsamadığı bir fragment değil. Render'ın kendisi yine her değişiklikte bir kez yapılır ve collage onu kabul ettiği okuyucular arasında paylaşır; bir rate limit her push'u bir request olarak sayar.
- Gönderilen bir fragment'teki form kabul edilir. Bir bağlantının ilkinden sonraki her render, forgery cookie'sinin doğruladığı bir token taşır.
- Bir bağlantı, açıldığı andaki cookie'lerle render eder. İmzalı, stateless cookie'ler kullanıyorsanız
maxStreamAgebağlantıyı bu süre sonunda kapatır ve client onu o anda elinde olan cookie'lerle hemen yeniden açar. - Stream
<prefix>stream/adresinde sunulur. Kendi compression middleware'iniztext/event-stream'e dokunmamalıdır. Aksi hâlde stream ancak bittiğinde ulaşır.noStreamaçıkken client yalnızca polling yapar ve başka bir transport üzerinden de hiçbir şey gönderilmez.
elagoht/websocket
github.com/Elagoht/collage-websocket, collage-live'ın gönderdiği fragment'leri bir event stream yerine bir WebSocket üzerinden taşır.
import (
client "github.com/Elagoht/collage-client"
live "github.com/Elagoht/collage-live"
"github.com/Elagoht/collage-websocket"
)
Plugins: []collage.Plugin{client.New(), websocket.New(websocket.Options{}), live.New(live.Options{})},
collage plugin add elagoht/websocketcollage-live'ı ve collage-client'ı da ekler ve websocket'i live'dan önceye koyar. Plugin, uygulamanın live plugin'ini listede nerede olursa olsun kendisi bulur; live yoksacollage.Newbaşarısız olur. collage-live v0.6.0 ve collage-client v0.2.0 ya da sonrasını gerektirir.- Başka hiçbir şey değişmez. Layout yine
{{liveClient}}'ı içerir, bu artık client'a buraya bağlanmasını söyler. Element'ler de yinedata-collage-pushtaşır. collage-live kendi event stream'ini sunmayı bırakır. WebSocket da aynı shared worker'dan açılır. Bu yüzden tüm sekmeler yine tek bir bağlantıyı paylaşır. - Push ayarları live'ındır. WebSocket, live'ın
prefix'i artıws/adresinde sunulur (varsayılan/_live/ws/), live'ınkeepAlivearalığında ping'lenir ve live'ınmaxStreamAgesüresi dolunca kapatılır. Live'danoStreamaçıksa bir bağlantıya sitenin kendi not-found page'i (404) döner; v0.4.1'den önce düz metin bir 404'tü.PathvePingkalktı; config'tepathya dapingbilinmeyen bir key'dir. - Genellikle buna ihtiyacınız olmaz. Fragment göndermek tek yönlüdür ve event stream tam da bunun içindir: bağımlılık gerektirmez ve kendiliğinden yeniden bağlanır. Bu plugin, stream'lerin bozulduğu deploy'lar içindir. Örneğin stream'leri buffer'layan bir proxy ya da onları sınırlayan bir platform. Live ailesinin bağımlılığı olan tek parçasıdır:
github.com/coder/websocket. - Bir bağlantı okuyucunun cookie'lerini taşır. Bu yüzden varsayılan olarak yalnızca sitenin kendi page'leri bağlantı açabilir.
originPatterns, page'leri ayrıca bağlanabilecek host'ları adlandırır:
{
"elagoht/live": { "prefix": "/push/", "keepAlive": "20s", "maxStreamAge": "1h" },
"elagoht/websocket": { "originPatterns": ["admin.example.com"] }
}
elagoht/client
github.com/Elagoht/collage-client, bir page'in kendi yaptığı swap'ler için küçük bir client script'i sunar: element getter'ları ve yerine konan bir fragment. Fragment kendi URL'sinden çekilir ya da hazır markup olarak verilir; element'in yerine geçerek ya da element'e morph edilerek yerleşir. Geri kalan her şey düz JavaScript'e bırakılır. elagoht/live de cevaplarını bununla yerleştirir.
import client "github.com/Elagoht/collage-client"
Plugins: []collage.Plugin{client.New()},
<head>
{{clientjs}}
</head>
<!-- the fragment's own template: its root is what is swapped -->
<ul id="items" data-src="{{fragmentURL "list" "items"}}">
{{range .}}<li>{{.Name}}</li>{{end}}
</ul>
const names = collage.$$("li", collage.$("#items")).map((li) => li.textContent);
collage.replace("#items").catch(() => {}); // fetch data-src, put it in as outerHTML would
collage.morph("#items").catch(() => {}); // the same fetch, the DOM patched in place
collage.put("#items", html, { morph: true }); // markup in hand, no fetch
document.addEventListener("collage:swap", (event) => {
console.log(event.target.id, event.detail.mode, event.detail.url);
});
Config.Pluginsiçinde olmalıdır: master layout'un<head>'inde bir kez çağırdığı{{clientjs}}'i ekler. Yapılandırılacak bir şey yoktur.- Script yalnızca
window.collage'ı tanımlar.collage.$querySelector'dır,collage.$$ise Array olarak dönenquerySelectorAll'dur. İkinci argüman olarak bir root verilmedikçe ikisi dedocumentüzerinde çalışır. collage.replace(target, url?)bir fragment'i çeker ve onu,outerHTML'in yapacağı gibi,target'ın yerine koyar.targetbir selector ya da bir Element'tir.url'in varsayılanı element'indata-src'sidir;WithFragmentPathile açılmış bir page{{fragmentURL}}'i oraya koyar. Cevap element'in tamamının yerine geçer. Bu yüzden element, fragment'in kendi root'u, yani template'inin en dıştaki tag'idir. Promise yeni element ile resolve olur.collage.morph(target, url?)aynı fetch'tir, ama DOM idiomorph ile yerinde patch'lenir. Eşleşen element'ler korunur. Böylece yazı yazılan alan focus'unu, caret'ini ve içine yazılanları, korunan bir element de scroll pozisyonunu korur. Morph edilen element'teki başka bir alan sunucunun değerini alır. Bu yüzden page'in yarım doldurulmuş bir form taşımayan bir kısmını morph edin ya da onureplaceedin.collage.put(target, content, { morph?, inner? })(v0.2.0'dan beri) aynı swap'in fetch'siz hâlidir: elde olan markup, bir Element ya da bir DocumentFragment, örneğin bir form'unfetch'inin cevabı. Dönmeden önce page'i değiştirir, page'de artık bulunan element'i döndürür ve diğerlerinin reject edeceği yerde hata fırlatır.innerolmadan içerik tek bir element olmalıdır.innerile element yerinde kalır ve çocukları içerikle değiştirilir ya da morph edilir.innerHTMLgibi o da hiçbir origin kontrolü yapmaz, bu yüzden ziyaretçinin yazdığı bir şeyi asla ona vermeyin. Element üzerinde süren birreplaceya damorph'u iptal eder.- Herhangi biri bittikten sonra page'deki element'ten bir
collage:swapevent'i bubble eder.detail'i{ url, mode, inner }'dir:mode"replace"ya da"morph"'tur,urliseputiçinnull'dır. - Request, fragment path'lerin ve action'ların beklediği gibi
Collage-Fetch: 1(collage.FetchHeader) header'ını ve page'in cookie'lerini taşıyan birGET'tir. Cevap güvenilir markup olarak eklenir. Bu yüzdenurlpage'in kendi origin'inde olmalıdır: başka bir origin fetch'ten önce reddedilir, bir redirect'in başka bir origin'den getirdiği cevap da öyle.url'i ya dadata-src'yi asla ziyaretçi girdisinden oluşturmayın. - Bir element üzerindeki en yeni çağrı kazanır. Üzerinde süren bir çağrı olan bir element'te başlatılan
replaceya damorph, eski çağrıyı iptal eder. Eski çağrı superseded olarak reject olur. Böylece yavaş bir cevap hiçbir zaman daha yeni bir cevabın üstüne düşmez. - Başarısız bir çağrı page'i olduğu gibi bırakır. Page'de olmayan bir target, ne
urlne dedata-srcolması, başka bir origin, bir ağ hatası, 2xx olmayan ya da tek bir element olmayan bir cevap (düz metin bir hata body'si, bütün bir document, yan yana iki element), fetch sürerken page'den çıkarılan bir element ya da daha yeni bir çağrı: bunların hiçbiri event fire etmez ve hepsi hangisi olduğunu söyleyen birErrorile reject olur, örneğincollage: morph /list/items: answered 500. Sessizce başarısız olabilecek bir polling tick'i.catch(() => {})ile biter. Çekilen bir fragment'in içindeki script'ler,outerHTML'de olduğu gibi çalışmaz. - elagoht/secure'dan gelen bir Content-Security-Policy nonce'u varsa onu verin:
{{clientjs cspNonce}}.'self''e izin veren bir policy script'i nonce olmadan da yükler. Yalnızca nonce'a izin veren ya da'strict-dynamic'kullanan bir policy'de, nonce'u unutan bir layoutcollage devaltında yine çalışır, çünkü orada policy yalnızca raporlar; production'da ise script'i yüklemeyi bırakır. - Script
/_client/client.<hash>.jsadresinde sunulur,immutableolarak bir yıl cache'lenir vedeferile yüklenir.{{clientjs}}ile{{liveClient}}'ın birlikte yaptığı gibi script'i iki kez içeren bir page onu bir kez çalıştırır. idiomorph 0.8.0 (0BSD) dahil gzip'lenmiş hâliyle yaklaşık 7 KB'tır ve hiçbir şeye bağımlı değildir. - Ne polling yapar, ne form post eder, ne de push alır: bunlar için elagoht/live kullanın. Bir form'un post'u, Page'in bir kısmını güncellemek sayfasında gösterildiği gibi sizin kendi
fetch'iniz olarak kalır, cevabı daputile yerleşir.
Asset'ler ve teslimat
Tarayıcının aldığı byte'ların neye benzediği ve oraya nasıl ulaştığı: minify edilmiş, yeniden boyutlandırılmış, bundle edilmiş, sıkıştırılmış, bir CDN'den purge edilmiş, çevrimdışı okuma için saklanmış ve header'ları ve redirect'leriyle birlikte static bir host'a deploy edilmiş.
elagoht/minimizer
github.com/Elagoht/collage-minimizer, render edilen page'lerden, JSON endpoint'leri gibi document'lardan ve mount'larınızın sunduğu dosyalardan whitespace'leri ve yorumları temizler.
import minimizer "github.com/Elagoht/collage-minimizer"
Plugins: []collage.Plugin{minimizer.New(minimizer.Options{})},
{
"elagoht/minimizer": { "noCSS": false, "js": true }
}
Config.Pluginsiçinde olmalıdır. Mount edilen dosya sistemlerini sarmalar ve bu işlem uygulama kurulurken yapılır.- Sıfır değerli
OptionsHTML, JSON ve CSS'i minify eder;noHTML,noJSONvenoCSSbunlardan birini kapatır. JavaScript varsayılan olarak kapalıdır,{"js": true}ile açabilirsiniz.minimizer.New(minimizer.Options{...})bir başlangıç noktası belirler, JSON bölümü onun üzerine decode edilir. - v0.2.0'da değişenler:
New()veNewWith(Config{…})artıkNew(Options{…})'dur."html": false,"json": falseve"css": falseyerine"noHTML": true,"noJSON": trueve"noCSS": trueyazılır;"html": truegibi key'ler ise silinir. Eski bir key uygulamayı başlangıçta durdurur. - Her dil, geçtiği her yerde kapsanır (v0.1.5'ten beri). JavaScript mount edilen bir script'i ve JavaScript ya da module olan inline bir
<script>'i, CSS bir stylesheet'i ve bir<style>'ı, JSON bir JSON document'ı ve JSON taşıyan bir<script>'i (application/ld+json,importmap) kapsar. Tanımadığı türde bir script, örneğintext/template, olduğu gibi kalır. - Bir parser değil, bir scanner'dır. Yalnızca anlam taşıyamayacak içeriği kaldırır.
<pre>ve<textarea>olduğu gibi korunur, CSS string'lerine dokunulmaz, JavaScript'te noktalı virgülün yerini tutabileceği her satır sonu korunur ve geçersiz JSON olduğu gibi döndürülür. Bir JavaScript satırı yalnızca hiçbir statement'ın sonunda yer alamayacak bir token'dan sonra birleştirilir:{ ( [ , ;ya da=,&&,=>gibi bir operatör. Bir isim, kapanan bir parantez, bir string ya da++sonrasında ise satır sonu korunur (v0.1.6'dan beri; öncesinde her satır sonu korunuyordu). - Mount edilen dosyalar, response değil dosya sistemi sarmalanarak minify edilir. Bu sayede bir mount'a yapılan
Rangerequest'leri doğru byte'ları döndürmeye devam eder.
elagoht/opti-image
github.com/Elagoht/collage-opti-image, piksel cinsinden width ve height belirten her <img>'yi yeniden yazar. Yeni <img>, plugin'in kendi mount'undan sunduğu yeniden boyutlandırılmış bir kopyayı gösterir.
import optiimage "github.com/Elagoht/collage-opti-image"
Plugins: []collage.Plugin{optiimage.New(optiimage.Options{})},
{
"elagoht/opti-image": {
"allowedOrigins": ["https://images.example.com"],
"webp": "auto",
"maxRecipes": 10000,
"maxDiskBytes": 1073741824
}
}
Config.Pluginsiçinde olmalıdır.- v0.5.0'da değişen: çıktı boyutu sınırlıdır. Boyut
<img>'nin boyutudur ve yazarının yazmadığı HTML gösteren bir page (widthveheight'ı koruyan, temizlenmiş yorumlar) bir ziyaretçinin boyut belirtmesine izin verir: 2×2 bir görseldewidth="50000" height="50000", 10 GB'lık bir bitmap'ti.maxPixels'ten fazla piksel ya da 16384'ten uzun bir kenar belirten<img>artık olduğu gibi bırakılır, render başına bir uyarı verilir ve onun için ad üretilmez; önceki bir sürümden diskte kalan ve böyle bir boyut isteyen tarif, kaynağı okunmadan reddedilir. maxRecipes(10000) vemaxDiskBytes(1 GiB), v0.5.0'dan beri, tutulanı sınırlar.maxRecipes, plugin'in nasıl yapacağını bildiği görselleri, bellekte vecacheDiriçinde<name>.jsonolarak sınırlar; aşılınca en uzun zamandır kullanılmayan, görseliyle birlikte unutulur ve adı, bir page onu yeniden anana kadar 404'tür.maxDiskBytes, diskteki üretilmiş görselleri sınırlar; önce en uzun zamandır kullanılmayan silinir ve yeniden istendiğinde tekrar üretilir. İkisi de önceki bir process'in dizinde bıraktıklarını sayar. Önceden, bir request'in değerini bir<img>'ye koyan page her request için bir ad üretir ve sonsuza kadar tutardı. Static build tarifleri her page render edildikten sonra listeler; bu yüzdenmaxRecipes'ten fazla farklı görseli olan bir site için onu yükseltin; uyarı build'in çıktısındadır.- Bir allowed origin kendi scheme'inin varsayılan portunu yazıyorsa,
https://cms.example.com:443, aynı host'un görselleriyle eşleşir; görselin URL'si portu yazsa da yazmasa da. Önceden başlangıçta kabul edilir ama hiçbir görselle eşleşmezdi (v0.4.1). - v0.4.0'da değişenler:
New()veNewWith(Config{…})artıkNew(Options{…})'dur.allowedOrigins,{scheme, host}nesneleri değil origin string'lerinden ("https://cms.example.com") oluşan bir listedir ve her biricollage.ParseOriginile denetlenir.fetchTimeoutveoriginMaxAge,"10s"gibi string'lerdir; çıplak bir sayı uygulamayı durdurur. Negatif bir boyut, piksel sayısı ya da kalite hatadır. allowedOriginsboşsa veFilesda yoksa plugin devre dışı kalır. Listelemediğiniz bir host'tan hiçbir zaman görsel çekmez. Scheme de origin'in bir parçasıdır.- Sitenin kendi görselleri kendi dosyalarından okunur (v0.3.0'dan beri):
optiimage.New(optiimage.Options{Files: map[string]fs.FS{"/static/": staticFS}})ile<img src="/static/avatar.png" width="256" height="256">, hiçbir istek atılmadanstaticFS'ten okunan, yeniden boyutlandırılmış bir kopya olur. Böylece site kendi public adresinden görsel çekmez, bir test ya da export da ağa ihtiyaç duymaz. Dosyanın içeriği görselin adının bir parçasıdır, yani değişen bir dosya yeni bir ad alır.Files'ın JSON karşılığı yoktur. - Bir origin'den gelen görsel
immutabledeğildir (v0.3.5'ten beri). Adı içeriğinden değil, tarifinden (URL, boyut, format) üretilir. Bu yüzden origin dosyayı aynı ad altında değiştirebilir. Görselpublic, max-age=<originMaxAge>ile sunulur.originMaxAgebir süredir, varsayılanı"24h"'tır ve en az bir saniye olmalıdır. Adı içeriğinin digest'ini taşıyan, sitenin kendiFiles'ından bir görselpublic, max-age=31536000, immutabledeğerini korur. - Yalnızca hem
widthhem deheightdeğeri piksel sayısı olarak verilmiş görseller yeniden yazılır. Hedef boyut olarak güvenilebilecek tek değer, bu belirtilen boyuttur. - Render sırasında hiçbir şey çekilmez. Page,
/_image/8f2a91c0b4e7d3a6.webpgibi içeriğe göre adlandırılmış bir dosyaya link verir. Görsel, bir tarayıcı onu ilk kez istediğinde çekilir ve yeniden boyutlandırılır. - Static export, görselleri de çıktısına yazar. Çünkü görseller bir mount'tan sunulur ve tüm mount'lar, page'ler render edildikten sonra kopyalanır.
webpdeğerifalse(varsayılan),trueya da"auto"olabilir."auto", WebP'yi yalnızca görselin aksi hâlde lossless olacağı durumlarda kullanır. Üretilen görseller varsayılan olarak bellekte ve.cache/opti-imageiçinde tutulur (cacheDir).p.Purge()vep.PurgeSource(url)bunları temizler.
optiimage.New(optiimage.Options{...}) Go tarafında bir başlangıç config'i belirler. JSON bölümü daha sonra bu config'in üzerine key key decode edilir.
elagoht/bundle
github.com/Elagoht/collage-bundle, uygulamanın JavaScript, TypeScript ve CSS'ini uygulama başlarken esbuild ile bundle eder, çıktıyı içeriğe göre hash'lenmiş adlarla sunar ve development'ta bir düzenlemede yeniden build eder.
import "github.com/Elagoht/collage-bundle"
Plugins: []collage.Plugin{bundle.New(bundle.Options{
Dir: "assets",
Entries: []string{"app.ts", "app.css"},
})},
<link rel="stylesheet" href="{{bundle "app.css"}}">
<script src="{{bundle "app.js"}}" defer></script>
{
"elagoht/bundle": {
"dir": "assets",
"entries": ["app.ts", "app.css"],
"prefix": "/_bundle/",
"target": "es2020"
}
}
Config.Pluginsiçinde olmalıdır:{{bundle}}'ı ekler.minifyvesourcemapdeğeri""(yazılmazsa;minifyyalnızca development dışında açıktır),"always"ya da"never"olur. v0.2.0'da değişenler: önceden boolean'dılar ve artıktrueya dafalseuygulamayı başlangıçta durdurur.prefix'in sonundaki/artık zorunlu değildir.- Çıktı
/_bundle/'daki bir mount'tan sunulur. Her dosya, esbuild'in içeriğinden ürettiği hash'i taşıyan bir adla sunulur ve bir yıl cache'lenir. Build'in üretmediği bir ad,{{asset}}'in eksik bir dosyada yaptığı gibi render'ı başarısız kılar. - Bundle'ı build edilemeyen bir production sunucusu başlamaz. Development'ta hata page'de gösterilir ve sunucu çalışmaya devam eder.
- Kaynaklar uygulama başlarken bir
fs.FS'ten değil, diskten okunur. Static build mount'u kopyalar, bu yüzden build edilen site bundle'ı içerir.
elagoht/favicon
github.com/Elagoht/collage-favicon, bir sitenin ikonlarını tek bir kaynak görselden üretir: favicon.ico, Apple touch icon, web app ikonları ve onları listeleyen manifest. İkonları kökte sunar ve her page'in head'inden link'ler.
collage plugin add elagoht/favicon
v0.3.0'dan beri gereken yalnızca budur. İkonlar sitenin kendi static/icon.png dosyasından (varsa static/icon.svg'den de) üretilir. Böyle bir dosya olana kadar ikonlar collage'ınkilerdir. Ayarlar manifest ve renkler içindir:
{
"elagoht/favicon": {
"name": "The blog",
"themeColor": "#0f172a",
"backgroundColor": "#ffffff"
}
}
- Kaynak kare bir PNG, JPEG ya da GIF'tir; ideal olarak 512 piksel ya da daha büyüktür.
- Kaynak varsayılan olarak
/static/icon.png'dir (v0.3.0'dan beri), SVG ise varsa/static/icon.svg'dir. Bunlar sitenin kendi URL'leridir ve onları sunan mount üzerindenHost.OpenMountedile okunur: development'ta diskten, build edildikten sonra binary'nin embed ettiği kopyadan.sourcevesvgbaşka bir dosyayı gösterir./ile başlayan bir değer bir URL'dir ve aynı şekilde okunur. Diğer her path diskten ya daFS'ten okunur.SourceBytesveSVGBytesbyte'ları Go'da verir. Başlangıç page'inin key'istartURL'dir. - Eksik bir kaynak uygulamayı asla durdurmaz (v0.3.0'dan beri). Varsayılan URL'de dosya yoksa collage'ın ikonlarını sunar ve dosyanın nereye konacağını log'a yazar. Adı verilmiş ama bulunmayan, decode edilemeyen ya da kare olmayan bir kaynak, aynı fallback ile bir uyarıdır. Uygulamayı yalnızca geçerli olmayan bir renk durdurur.
- İkonlar başlangıçta bir kez üretilir ve static document olarak sunulur. Bu yüzden static build onları yazar. SVG olduğu gibi geçirilir, asla rasterize edilmez.
- Link'ler
?v=ve kaynağın bir özetini taşır. Böylece değişen bir ikon, değişen bir URL demektir. Layout'ta{{hoist "head"}}gerektirir.
elagoht/compress
github.com/Elagoht/collage-compress, response'ları Brotli ve gzip ile sıkıştırır ve bir static build'in yanına .br ve .gz dosyaları yazar.
import "github.com/Elagoht/collage-compress"
Plugins: []collage.Plugin{
compress.New(compress.Options{}),
secure.New(secure.Options{CSP: "..."}),
},
{
"elagoht/compress": { "minSize": 512, "gzipLevel": 6, "brotliLevel": 4, "types": ["application/x-yaml"] }
}
- Onu response body'lerini yeniden yazan her plugin'den önce register edin. İlk register edilen plugin en dıştaki middleware'dir. elagoht/secure ve elagoht/honeypot buna ihtiyaç duymaz:
PersonaliseHookile, her middleware'in içinde yeniden yazarlar. elagoht/health, compress'ten önce de sonra da listelenebilir. - En az
minSizebyte'lık metin türleri, request'in kabul ettiği en iyi encoding ile sıkıştırılır.text/event-stream, bir WebSocket ve birRangerequest'ine dokunulmaz. - Sıkıştırılmış bir body ETag başına saklanır. Böylece collage'ın cache'ten sunduğu bir page, okuyucu başına değil, encoding başına bir kez sıkıştırılır. ETag encoding'i de içerir ve conditional bir request yine
304'ünü alır.Cache-Control'üprivateya dano-storetaşıyan bir response (örneğin elagoht/secure'ün nonce'unu taşıyan bir page) yine sıkıştırılır ama hiç saklanmaz (v0.1.3): her seferinde değiştiği için saklanan kopya hiç yeniden kullanılmazdı. skipPrivate(v0.1.8'den beri, varsayılanfalse),Cache-Control'üprivateya dano-storetaşıyan bir response'u BREACH'e karşı sıkıştırmadan gönderir. Bir response, page'in yansıttığı bir girdinin yanında bir forgery token gibi bir sır taşıyorsa, sıkıştırılmış boyutu sırrı karakter karakter sızdırabilir. Açılmadıkça hiçbir şey değişmez. Diğer önlemler README'deki BREACH bölümündedir.- Static build, önceden sıkıştırılmış dosyaları sunan bir host için sıkıştırılabilen her dosyanın yanına bir
.brve bir.gzyazar;noPrecompressbunu kapatır. noCache(v0.2.0'dan beri) sıkıştırılmış body saklamaz. Negatif bircacheBytes'ın yerini alır; negatifcacheBytesartık uygulamayı durdurur.
elagoht/cdnpurge
github.com/Elagoht/collage-cdnpurge, collage'ın invalidate ettiği page'lerin CDN'deki kopyalarını purge eder: zone'a göre Cloudflare'de ya da bir webhook üzerinden URL listesi alan herhangi bir serviste.
import "github.com/Elagoht/collage-cdnpurge"
Plugins: []collage.Plugin{cdnpurge.New(cdnpurge.Options{
Cloudflare: &cdnpurge.Cloudflare{
ZoneID: os.Getenv("CF_ZONE_ID"),
APITokenEnv: "CF_API_TOKEN",
},
})},
{
"elagoht/cdnpurge": {
"webhook": { "url": "https://purge.example.com/", "tokenEnv": "PURGE_TOKEN" },
"window": "2s",
"retries": 4
}
}
cloudflareilewebhook'tan en az biri ve bir origin zorunludur:Config.BaseURLya da bir origin resolver.- v0.3.0'da değişenler:
baseURLkaldırıldı (Config.BaseURL'i ayarlayın);forceartıkinDevelopment'tır.cloudflare.apiTokenvewebhook.tokenyerine, token'ı tutan ortam değişkeninin adını verenapiTokenEnvvetokenEnvgelir (Go'danAPITokenveTokendeğeri doğrudan alır). Süreler string'dir; negatif birretrieshatadır. Eski bir key uygulamayı başlangıçta durdurur. - Tam olarak bir invalidation'ın ulaştığı path'leri
Config.BaseURLaltında purge eder ve her entry'yi, birOriginResolverplugin'inin adlandırdığı kendi host'unun origin'i altında purge eder. Bir origin'i paylaşan iki host için URL bir kez purge edilir. Origin'in cache'lemediği bir page adlandırılmaz. Bu yüzden CDN'in cache'lediği her şeyi collage'ın da cache'lediğinden emin olun. - Purge'ler
windowboyunca toplanır, invalidate eden goroutine'in dışında gönderilir, bir429ya da5xxgelirse yeniden denenir ve shutdown'da gönderilir. Bir development sunucusu,inDevelopmentayarlanmadıkça hiçbir şeyi purge etmez. - Token asla
plugins-config.json'a girmez; oraya yalnızca değişkenin adı yazılır.
elagoht/offline
github.com/Elagoht/collage-offline, bir service worker sunar. Böylece bir ziyaretçinin okuduğu page'ler ağ olmadan da yeniden açılır.
import "github.com/Elagoht/collage-offline"
Plugins: []collage.Plugin{offline.New(offline.Options{
Precache: []string{"/"},
Fallback: "/offline",
})},
<head>
{{offlineScript}}
</head>
{
"elagoht/offline": {
"precache": ["/", "/about"],
"fallback": "/offline",
"assets": ["/static/", "/_bundle/"],
"maxPages": 100
}
}
Config.Pluginsiçinde olmalıdır:/sw.js'de sunulan worker'ı kuran{{offlineScript}}'i ekler.- v0.2.0'da değişenler:
versionartıkbuildID,inDevartıkinDevelopment'tır. Negatif birmaxPagesya damaxAssets(her şeyi sakla) hatadır; onun yerine büyük bir sayı yazın. Birassetsprefix'i, sonunda/olsun olmasın, path segmentlerini bütün olarak kapsar. - Page'ler önce ağdan çekilir ve saklanır.
assetsaltındaki static dosyalar stale-while-revalidate ile sunulur. Ne ulaşılabilen ne de saklanan bir page içinfallbackpage'i gösterilir.no-storeya daprivateolarak işaretlenmiş bir response asla saklanmaz, precache de edilmez. - Private page'ler offline saklanmaz (v0.2.1'den beri). Guard'lı bir page (
WithGuard)private, no-cacheile gider; basicauth da page'leriniprivateolarak işaretler. Bir tarayıcı böyle bir page'i saklayabilir, çünkü göstermeden önce sunucuya yeniden sorar; worker ise offline'da kimseye sormadan cevap verir. v0.2.0'a kadar bu page'leri saklıyor ve hiçbir guard'a sormadan cihazı kim kullanıyorsa ona offline gösteriyordu. Cache sürümü plugin'inkiyle değişir, bu yüzden yükseltmeden sonraki ilk ziyaret eski worker'ın sakladıklarını atar. Tek bir okuyucunun verisini taşıyan kendi page'iniz bunuCache-Control: privateya dano-storeile söyler. - Worker'ın cache'leri her deploy'la değişen bir sürümle adlandırılır. Böylece yeni bir build, eskisinin sakladıklarının yerini alır. Build, ayarlanmışsa
buildID'dir; değilse collage'ınHost.BuildID'sidir, yaniConfig.Cache.Versionya da çalıştırılabilir dosyanın parmak izi. - Development'ta
/sw.js,inDevelopmentayarlanmadıkça kendi kaydını siler. Static buildsw.js'i yazar; bir CDN'in onu uzun süre tutmasını engelleyin.
elagoht/deploy
github.com/Elagoht/collage-deploy, static bir build'in yakaladığı header'lardan ve redirect'lerden static bir host'un okuduğu config dosyalarını yazar. Böylece bir sitenin redirect'leri, cache ve güvenlik header'ları export'tan sonra da korunur.
import "github.com/Elagoht/collage-deploy"
Plugins: []collage.Plugin{deploy.New(deploy.Options{Target: "netlify"})},
{
"elagoht/deploy": {
"target": "netlify"
}
}
- Constructor'ı
deploy.New(deploy.Options{…})'dur.targetşunlardan biridir:netlify,cloudflare,vercelya dagithub-pages. Başka bir değer uygulamanın başlamasını engeller. Boş bırakılırsa hiçbir şey yazmaz, son export'un yazdıklarını siler ve uyarı verir. netlifyvecloudflareiçin_headersve_redirects,verceliçin birvercel.jsonyazılır.github-pagesiçin her sabit redirect'e bir meta-refresh page'i ve bir.nojekyllyazılır, ama header yazılmaz.- Bir host'un taşıyamadığı şey bir uyarıdır. Plugin, uygulamadan farklı redirect eden bir kuralı asla yazmaz. Her host'ta 410, Netlify'da 302 ve 301 olarak yazılan 307 ile 308, Cloudflare'in kural sınırları, GitHub Pages'te ise pattern'li redirect'ler ve tüm header'lar uyarıya konu olur. Vercel,
vercel.json'ı yalnızca output dizini proje olarak deploy edildiğinde (vercel deploy dist) okur. - Header'lar mümkün olan en az kurala sıkıştırılır: her dosyanın paylaştığı
/*altına, bir dizinin paylaştığı/dir/*altına, geri kalanı her dosyanın kendi path'ine yazılır.Content-Typeasla bir wildcard kurala girmez. Dosyanın uzantısından anlaşılan birContent-Typeise host'a bırakılır. - Yazdıklarını
.collage-deploy.json'a kaydeder ve aynı dizine alınan bir sonraki export'ta bu dosyaları yeniler. Kendi yazmadığı bir_headers,_redirectsya davercel.jsondosyasının üzerine asla yazmaz: bu bir hatadır ve hiçbir şey yazılmaz. Bir redirect'te ya da header'da control karakteri olması da öyledir. - Redirect'lerini page'lerden, document'lardan ve elagoht/redirects gibi her
RedirectSourceplugin'inden alır. Header'larını ise header yakalamasından alır. Bu yüzden build'i production modunda ve gerçekBaseURLile alın.
Operasyon ve development
Bir sitenin render ettiğini denetlemek, development'ta bir render'ı görmek ve çalışan bir siteyi izlemek: access log'ları, metric'ler, trace'ler, analytics, hata raporları, health probe'ları ve sitenin çalıştırdığı zamanlanmış job'larla arka plan queue'ları.
elagoht/htmlcheck
github.com/Elagoht/collage-htmlcheck, bir sitenin render ettiği HTML'i denetler: yapıyı, erişilebilirliği, bir arama motorunun okuduklarını, bir page'i yavaşlatanları ve page'ler arasındaki link'leri. Bulduklarını finding olarak raporlar.
import "github.com/Elagoht/collage-htmlcheck"
Plugins: []collage.Plugin{htmlcheck.New(htmlcheck.Options{})},
{
"elagoht/htmlcheck": {
"rules": { "img-dimensions": "off", "heading-order": "error" },
"titleMax": 60,
"descriptionMax": 160,
"pageBudget": 200000,
"ignoreLinks": ["/api/"]
}
}
- Artık
inProductionanahtarı yok: production sunucusundaki bulgular hiçbir yere ulaşmıyordu; onları development'ta ya da static build'de okuyun. - Development'ta her page render edilirken denetlenir ve bulunanlar page'in üzerinde gösterilir. Static build'de önce her page, sonra build'in bütünü denetlenir: iki page'in paylaştığı title'lar, build'in yazmadığı page'lere giden link'ler. Bir error build'i başarısız kılar (bkz. Static export). Production sunucusunda hiçbir şey denetlenmez.
- 22 kuralı vardır:
html-lang,title,img-alt,input-label,duplicate-id,heading-order,broken-linkve diğerleri. Her biri varsayılan olarakerrorya dawarnseviyesindedir.rulesbir kuralın seviyesini değiştirir ya da onuoffile kapatır. Plugin'in tanımadığı bir kural adı uygulamanın başlamasını engeller.htmlcheck.Rules()hepsini listeler. ignoreLinksprefix'leri sondaki/olsun olmasın segment'lerin tamamını kapsar ve/ile başlamalıdır. Negatif birtitleMax,descriptionMaxya dapageBudgetuygulamayı durdurur; 0 varsayılandır (60, 160, bütçe yok).
elagoht/devtoolbar
github.com/Elagoht/collage-devtoolbar, development'ta her page'de küçük bir panel gösterir: hangi page'in, hangi locale'de, hangi status'la render edildiği, render'ın ve her fragment'inin ne kadar sürdüğü, hangi fragment'lerin başarısız olduğu, render'ın bağlı olduğu dependency tag'ler, Cache-Control'ü ve ETag'i, boyutu ve denetleyen plugin'lerin kaç finding raporladığı.
import "github.com/Elagoht/collage-devtoolbar"
Plugins: []collage.Plugin{
htmlcheck.New(htmlcheck.Options{}),
devtoolbar.New(devtoolbar.Options{}), // last
},
- Yalnızca yerel client'lar. Panel, yalnızca geliştiricinin makinesindeki ya da özel bir ağdaki client için çizilir (loopback, RFC 1918, IPv6 unique-local, link-local). Client'ı
collage.ClientIPbelirler; yaniServer.TrustedProxiesiçinde listelenen bir proxy'nin arkasında, proxy'nin ilettiği client esas alınır. Başka her client response'u olduğu gibi alır ve ilki bir uyarı log'lar. v0.4.2'den beri yerel olmayan bir client'ı ileten yerel bir peer, yaniServer.TrustedProxies'te olmayan bir proxy de panel almaz. İlki o ayarı adıyla anan bir uyarı log'lar. - Bir tailnet ya da carrier-grade NAT adresi (
100.64.0.0/10) özel ağ sayılmaz; bu yüzden makineye Tailscale üzerinden bağlanan bir telefon paneli görmez. Uzak client'lara da göstermek için kontrolüdevtoolbar.New(devtoolbar.Options{AllowRemote: true})ile ya da plugin yapılandırmasında kapatın:
{ "elagoht/devtoolbar": { "allowRemote": true } }
- Konum. Panel sol alt köşede durur. v0.5.0'dan beri
positiononu başka bir köşeye ya da üst veya alt kenarın ortasına koyar:top-left,top,top-right,bottom-right,bottomya dabottom-left. Go'dadevtoolbar.Options{Position: devtoolbar.PositionTopRight}olarak yazılır. Bunların dışındaki bir değer uygulamayı açılışta durdurur.
{ "elagoht/devtoolbar": { "position": "top-right" } }
- Onu en son register edin: saydığı finding'ler, ondan önce çalışan plugin'lerinkidir.
DevModeolmadan başlatılan bir sunucuda ve bir static build'de hiçbir şey yapmaz. Panel page cache'ten sonra eklenir, bu yüzden collage'ın cache'lediği içerik onu asla taşımaz.- v0.2.3'ten beri
Content-Typeolmadan yazılan bir page de paneli alır. Tür, net/http'nin yaptığı gibi ilk byte'lardan tahmin edilir.
elagoht/accesslog
github.com/Elagoht/collage-accesslog, her request için slog üzerinden yapılandırılmış bir log satırı yazar ve her request'e handler'larının log'larken kullanabileceği bir id verir.
import "github.com/Elagoht/collage-accesslog"
Plugins: []collage.Plugin{accesslog.New(accesslog.Options{})},
{
"elagoht/accesslog": {
"skip": ["/_collage/", "/healthz", "/readyz", "/static/"],
"sample": 0.25,
"requestIDHeader": "X-Request-ID"
}
}
/_collage/ile elagoht/health'in path'leri olan/healthzve/readyzvarsayılan olarak atlanır. Birskipprefix'i, sondaki/olsun olmasın segment'lerin tamamını kapsar:/healthz,/healthz-report'u kapsamaz. Routing'den önce cevaplanan bir request için temizlenmiş path'le eşleştirilir; bu yüzden/_collage/../adminatlanmaz.- v0.3.0'dan beri her request, nerede cevaplanırsa cevaplansın log'lanır. Plugin bir middleware olduğu kadar bir
collage.RequestHook'tur da; hook, middleware'in hiç ulaşmadığı request'leri log'lar: kendinden önce listelenen birelagoht/fail2ban'ın reddettiği bir ban, kendinden önce listelenen birelagoht/health'in geri çevirdiği bir request, çıplak birapp.Handlemount'unun response'u, ve collage'ın kirli bir path için kendi redirect'i (sorulduğu haliyle path altında) ya da encoded slash için404'ü. Bu satırlardabytesyoktur, response'larında daX-Request-IDyoktur. Eskisinden fazla satır bekleyin, banlı bir istemcinin403'leri de aralarında.accesslog.RequestIDçıplak birapp.Handlehandler'ında da çalışır. - Satırın tamamı için onu
Config.Plugins'te ilk sıraya koyun,elagoht/healthveelagoht/fail2ban'dan önce (yalnızca gözlemler), ve bir handler'ıcollage.WithMiddleware()ile mount edin. Handler'ı panic eden bir request yalnızca middleware ona ulaştıysa log'lanır; development reload stream'i ve dev sunucusunun bilinmeyen birHost'u reddi hiç log'lanmaz. - Satırda metot, query'siz path, status, byte sayısı, süre, istemci adresi, user agent, referer ve request id bulunur. Satır uygulamanın logger'ıyla ya da
Options.Loggerile yazılır; bir5xx,ERRORseviyesinde log'lanır. - Bir id'ye benzeyen
X-Request-IDkorunur, değilse yenisi üretilir. Id response'ta geri gönderilir veaccesslog.RequestID(ctx)ile okunur. sample,2xxresponse'ların bir kısmını log'lar, diğerlerinin hiçbirini atlamaz. İstemcinin adresicollage.ClientIP'dir; bir proxy'nin arkasındaysanız onuServer.TrustedProxies'e yazın.trustProxyvetrustedProxiesanahtarları kaldırıldı,X-Real-IPhiç okunmaz.- Referer query'siz log'lanır (v0.1.11'den beri): yalnızca scheme, host ve path. Bir reset token'ının ya da session id'sinin taşınabildiği query, fragment ve user info yazılmaz. Parse edilemeyen bir referer
""olarak log'lanır.fullReferer: trueheader'ı eskisi gibi, olduğu haliyle log'lar.
elagoht/prometheus
github.com/Elagoht/collage-prometheus, framework'ün metric'lerini Prometheus'a aktarır ve /metrics'te sunar: render ve fragment süreleri, cache olayları, route'a göre HTTP response'ları ve invalidation'lar.
import "github.com/Elagoht/collage-prometheus"
m := prometheus.New(prometheus.Options{Namespace: "collage"})
app, err := collage.New(&collage.Config{
Observability: collage.ObservabilityConfig{Metrics: m},
Plugins: []collage.Plugin{m},
})
{
"elagoht/prometheus": { "path": "/metrics", "tokenEnv": "METRICS_TOKEN" }
}
- Constructor'ı
New'dur. Tek değeri hem uygulamanınMetrics'i hem de bir plugin olarak verin. Birincisi olmadan hiçbir şey ölçülmez, ikincisi olmadan hiçbir şey sunulmaz. - Hiçbir label bir request'ten alınmaz. v0.2.0'dan beri
route,collage.RouteInfo'nun request'in neye resolve edildiğini söylediği tür ve addır:/blog/ave/blog/bikisi depage:post,/robots.txtdocument:robots, bir mountmount:/static/, bir 404 iseotherolur. Böylece path uyduran bir crawler yeni time series üretemez.routesseçeneği kaldırıldı: mount'lar ve handler'lar o olmadan da prefix'leriyle etiketlenir. - Bir token varsa scrape onu bir bearer token olarak göndermelidir. Token bir sırdır, bu yüzden
plugins-config.json'a hiç girmez:tokenEnvonu tutan ortam değişkeninin adını verir ya daOptions.Tokenonu Go'dan ayarlar; birtokenanahtarı uygulamayı durdurur.path: "-"metric'leri hiçbir yerde sunmaz. Path birebir eşleşir: başka bir route'un zaten yanıtladığı ya da/ile biten bir path uygulamanın başlamasını engeller.
elagoht/otel
github.com/Elagoht/collage-otel, collage'ın kendi span'lerini OpenTelemetry span'lerine dönüştürür ve bir request'in çağıranın başlattığı trace'i sürdürür.
import otel "github.com/Elagoht/collage-otel"
t := otel.New(otel.Options{Tracer: provider.Tracer("example.com/site")})
app, err := collage.New(&collage.Config{
Observability: collage.ObservabilityConfig{Tracer: t},
Plugins: []collage.Plugin{t},
})
{ "elagoht/otel": { "skip": ["/healthz"], "trustIncoming": "" } }
- Constructor'ı
New(otel.Options{Tracer: tracer})'dır. Tracer olarakcollage.http,collage.rendervecollage.fragment'i span'lere dönüştürür. Plugin olarak da çağıranın trace context'ini header'lardan okur; bunu collage'ın kendi span'inden önce çalışan birRequestHookiçinde yapar. İkisi de tek başına çalışır. - İkisi birlikteyken bir request tek bir trace'tir. Güvenilir bir çağıranınkinin child'ı olan bir server span vardır;
collage.httponun, render ve her fragment decollage.http'nin altında yer alır. Server span,collage.RouteInfo'nun bildirdiği route'a göre adlandırılır: page, document ya da action için register edildiği pattern (GET /blog/{slug},GET /feed.xml), mount ya da handler için prefix'i. collage'ın routing'den önce reddettiği bir request (kirli bir path'in redirect'i, encoded slash'in404'ü) bir route adlandırmaz: span'i adı olarak metodu korur ve yalnızcacollage.route.kind=rejectedtaşır; böylece bir tarayıcı bot'un path'leri asla span adı olmaz. - v0.4.0'da değişen: bir istemcinin trace context'i yalnızca güvenilirse sürdürülür.
traceparentherkesin gönderebileceği bir iddiadır: herkesten sürdürülürse internetteki bir istemcinin, birParentBasedsampler'ın neyi export edeceğine karar vermesine ve sitenin trace id'lerini seçmesine izin verir;baggage'ı da uygulamaya ulaşır. Varsayılan olarak trace yalnızca bağlantısıConfig.Server.TrustedProxies'ten gelen bir request'te sürdürülür; diğer her request'in server span'i, çağıranın span'ine link veren yeni bir trace'in köküdür ve baggage'ı atılır.trustIncoming""(bu varsayılan),"always"(yalnızca başka servislerin ulaştığı bir servis; eski davranış) ya da"never"olur; başka bir değer uygulamayı durdurur. Öndeki bir CDN genellikle istemcinintraceparent'ını olduğu gibi iletir; proxy trace'i başlatmıyorsatraceparent,tracestatevebaggage'ı proxy'de silin ya da"never"ayarlayın. - v0.4.0'dan beri metot da sınırlıdır: RFC 9110'unkiler ve
PATCHdışındaki bir metothttp.request.method'da_OTHER'dır, gönderildiği halihttp.request.method_original'dadır ve span'in adındaHTTPyazar (HTTP /blog/{slug}); böylece metot uyduran bir istemci span adı uyduramaz. - SDK uygulamaya aittir: provider, exporter, sampler ve propagator. Bir propagator ayarlayın; yoksa her request kendi trace'ini başlatır.
skipprefix'leri, sondaki/olsun olmasın segment sınırında eşleşir.url.schemecollage.IsHTTPS'i izler; bu yüzden bunu söyleyen güvenilir bir proxy'nin arkasındahttpsolur.
elagoht/analytics
github.com/Elagoht/collage-analytics, her page'in head'ine bir analytics snippet'i ekler: Plausible, Umami, GoatCounter ya da Google Analytics 4. Bunu production'da ve static build'lerde yapar, development'ta asla yapmaz.
import "github.com/Elagoht/collage-analytics"
Plugins: []collage.Plugin{analytics.New(analytics.Options{
Plausible: &analytics.Plausible{Domain: "example.com"},
})},
{
"elagoht/analytics": {
"plausible": { "domain": "example.com" },
"exclude": ["admin"],
"respectDNT": true,
"requireConsent": true
}
}
- Layout'ta
{{hoist "head"}}ister. Anahtarları kısaltmaları Go'daki gibi yazar:respectDNT,goatCounter, Umami'ninwebsiteID'si, Google Analytics'inmeasurementID'si. - Plausible, Umami ve GoatCounter ziyaretleri cookie olmadan sayar. Google Analytics 4 cookie ayarlar; onu
requireConsentile kullanın. respectDNTya darequireConsentile siteden sunulan küçük bir loader, herhangi bir sağlayıcının script'i çekilmeden önce tarayıcıda karar verir. Do Not Track ya da Global Privacy Control altında hiçbir şey yüklenmez.requireConsentile de pagewindow.collageAnalyticsConsent()çağırana kadar hiçbir şey yüklenmez.exclude, snippet almayan page'leri adlandırır.- Sitede elagoht/consent varsa
requireConsentyerineconsentCategoryayarlayın (örneğin"analytics"). Plugin'in yazdığı her tag, ziyaretçi o kategoriyi kabul edince consent plugin'inin çalıştırdığı birtype="text/plain" data-consent="analytics"tag'ine dönüşür. Kategori consent plugin'inde tanımlı olmalıdır, yoksa tag'ler hiç çalışmaz. Google Analytics iki bekletilen tag olur: script'i ve onu yapılandıran inline çağrı; loader yoktur. consentCategory,requireConsentile birlikte kullanılamaz: ikisi birden verilirse ya da ad küçük harf, rakam ve tire dışında bir şey içerirse uygulama başlamaz.respectDNTyine geçerlidir ve Global Privacy Control'e de uyar; yani GPC gönderen bir tarayıcıda "Tümünü kabul et"ten sonra bile hiçbir şey yüklenmez. Sıkı bir Content-Security-Policy altında Google Analytics'in inline tag'i,script-src'de bir'sha256-…'ister (yukarıdaki consent plugin'inin CSP notlarına bakın).
elagoht/tenant
github.com/Elagoht/collage-tenant, tek bir site'ı birçok müşteriye, her birine kendi host'unda sunar: acme.app.com, globex.app.com ya da müşterinin kendi domain'i. Cache'lenen page tenant başına tutulur ve site'ın yazdığı her mutlak URL host'u izler.
import "github.com/Elagoht/collage-tenant"
Plugins: []collage.Plugin{tenant.New(tenant.Options{
Tenants: []tenant.Static{
{ID: "acme", Origin: "https://acme.app.com", Hosts: []string{"acme.app.com", "acme.localhost"}},
},
Resolve: lookupCustomDomain, // ya da çalışma anında eklenen host'lar için bir veritabanı
})},
{
"elagoht/tenant": {
"tenants": [
{ "id": "acme", "origin": "https://acme.app.com", "hosts": ["acme.app.com"] }
],
"bypass": ["app.com"],
"ttl": "1m",
"unknownTTL": "1m",
"maxUnknownPerMinute": 600
}
}
tenantsya da birResolvefonksiyonu (yalnızca Go) gerekir.- Hiçbir tenant'a ait olmayan host, site'ın kendi 404 page'iyle 404 alır. Başarısız olan ya da panic eden bir resolver
Retry-Afterile 503 alır ve bu cache'lenmez. Bir tenantttlboyunca, v0.3.0'dan beri "tenant yok" cevabı daunknownTTLboyunca cache'lenir (ikisi de"1m"; süre string'leri, sayı hatadır, negatif değer de);maxHosts(10000) kaç host'un hatırlanacağını sınırlar, negatif bir değer uygulamayı durdurur. v0.2.1'den beri tenant'lar ve "tenant yok" cevapları ayrı ayrı bu kadar tutulur, böylece uydurma host'larla yapılan bir sel gerçek bir tenant'ı dışarı itemez. Aynı host için eşzamanlı cache miss'ler tek bir resolver çağrısını paylaşır.bypasshost'ları tenant'sız sunulur. maxUnknownPerMinute(600, v0.3.0'dan beri), dakikada "tenant yok" cevabı verebilecek ya da başarısız olabilecek lookup sayısını sınırlar: her request'te yeni, rastgele birHostgönderen bir istemci önceden her biri için birResolveçağrısı yaptırırdı. Bütçe bitince, cevabı tutulmayan bir host, bütçe dolana kadarResolveçağrılmadanRetry-Afterile 503 alır ve dakikada bir uyarı log'lanır. Tenant'ı tutulan bir host,ttl'i geçmiş olsa da bütçeden bağımsız çözülür; tenant bulan bir lookup da bütçeden düşmez. Böylece bir sel, bilinen bir tenant'ın sitesini düşüremez. Daha önce hiç görülmemiş bir tenant host'u sel sırasında bu 503'ü alabilir: onutenantsaltında listeleyin ya da bütçeyi yükseltin.- Bir handler tenant'ı
tenant.ID(rc)ile okur; yalnızca context'i olan kod, örneğin bir page'inStaticParams'ı,tenant.IDFromContext(ctx)ile. İkisi de cache'lenen bir page'de güvenlidir.collage.BaseURL(rc)tenant'ın origin'idir. elagoht/sitemap,feed,meta,ogimage,indexnow,cdnpurgeverobotshost'u izler: yazdıkları URL'ler tenant'ın origin'idir.acme.localhostcollage devile çalışır. Static build'in host'u yoktur; tenant'sız render eder vetenant-no-hostuyarısı verir. Static export,Config.BaseURL'ün host'unun site'ıdır ve tenant'sız render edilir; tenant başına export desteklenmez. Header yakalaması o host olarak cevaplanır; bu yüzden o host bir tenant'ın olmalı ya dabypass'ta listelenmeli.
elagoht/errortrack
github.com/Elagoht/collage-errortrack, sunucu hatalarını ve panic'leri Sentry'ye ya da protokolünü konuşan herhangi bir servise (GlitchTip, kendi barındırdığınız Sentry) yalnızca standart kütüphaneyle raporlar. Her 5xx'i ve recover edilen her panic'i ErrorHook üzerinden duyar ve arka plandaki bir goroutine'den gönderir; bu yüzden yavaş ya da kapalı bir Sentry hiçbir request'i yavaşlatmaz.
import "github.com/Elagoht/collage-errortrack"
Plugins: []collage.Plugin{errortrack.New(errortrack.Options{
User: func(r *http.Request) errortrack.User {
return errortrack.User{ID: userID(r)}
},
})},
{
"elagoht/errortrack": {
"dsnEnv": "SENTRY_DSN",
"environment": "production",
"sampleRate": 1
}
}
- Status'ü ve request'i
ErrorEvent'ten okur. Ayrıca birDSNya daDSNEnvgerekir: yoksa başlangıç başarısız olur. Bunun tek istisnasıinDevelopmentverilmemiş dev moddur; orada hiçbir şey gönderilmez ve DSN gerekmez. DSN bir kimlik bilgisidir;plugins-config.json'a değil, ortam değişkenine koyun.timeout("5s") bir süre string'idir; sayı uygulamayı durdurur. - Sunucudan çıkan şey sınırlıdır: error zinciri, bir panic'in stack'i, ham path yerine route pattern'i (bir middleware'in panic'i gibi hiçbir route çözülmediğinde yalnızca
scheme://host; ham path yalnızcasendPathile), değerleri[filtered]olan query anahtarları ve altı request header'ı;sendPathverilmedikçeRefereryalnızca origin'ine indirilir; URL'nin scheme'icollage.IsHTTPS'i izler. Cookie'ler,Authorization, body ve client adresi hiçbir zaman gönderilmez (adres yalnızcasendIPile,collage.ClientIP'nin verdiği hâliyle). Bir kullanıcı, ancakUsercallback'inizin döndürdüğü kadarıyla gönderilir. - Mesaj, hatalı kodun yazdığı gibi gönderilir ve bir sır taşıyabilir.
BeforeSendile temizleyin; o event'i düzenleyebilir ya dafalsedönerek düşürebilir. minStatus(500) neyin raporlanacağını belirler; panic'ler her zaman raporlanır.sampleRate,perMinute(60) vequeueSize(100) hacmi sınırlar: aşan event'ler düşürülür ve sayılır, yeniden denenmez; bir429gönderimi duraklatır.- Kaydettiğiniz plugin üzerindeki
Capture(ctx, err), bir arka plan işi gibi request dışında oluşan bir hatayı raporlar.inDevelopmentverilmedikçe dev modda hiçbir şey gönderilmez.
elagoht/health
github.com/Elagoht/collage-health, bir platformun liveness ve readiness probe'larına cevap verir. collage bir shutdown için drain etmeye başladığı anda readiness'i false'a çevirir. Böylece load balancer, port kapanmadan önce request göndermeyi bırakır. Endpoint'lere page'ler ya da document'lar değil, plugin'in middleware'i cevap verir. Bu yüzden bir static export bunları hiçbir zaman içermez.
import "github.com/Elagoht/collage-health"
h := health.New(health.Options{})
h.Check("db", func(ctx context.Context) error { return db.PingContext(ctx) })
app, err := collage.New(&collage.Config{
Server: collage.ServerConfig{DrainDelay: 5 * time.Second, ShutdownTimeout: 10 * time.Second},
Plugins: []collage.Plugin{
h, // before anything that can refuse or answer a request
basicauth.New(basicauth.Options{}),
ratelimit.New(ratelimit.Options{}),
},
})
{
"elagoht/health": {
"livePath": "/healthz",
"readyPath": "/readyz",
"checkTimeout": "2s",
"cacheFor": "1s",
"details": false,
"maxInFlight": 0
}
}
- Süreler string'dir:
"checkTimeout": 2anahtarı adlandırarak uygulamayı durdurur;"2s"yazın. /healthz(livePath), process bir request'e cevap verdiği sürece200 okdöner ve hiçbir check çalıştırmaz./readyz(readyPath)200 okdöner; bir check başarısız olduğu sürece503 unavailable, bir drain başladıktan sonra ise503 drainingdöner. İkisi deGETveHEAD'eCache-Control: no-storeile cevap verir. Bu path'lerden birinde register edilen bir page, uygulamanın başlamasını engeller. Orada duran bir document ise gölgede kalır: demo scaffold'undaki/healthzdocument'ına hiç ulaşılmaz. Onu silin ya dalivePath'i değiştirin.h.Check(name, fn), uygulama başlamadan önce bir readiness check'i ekler. Bir probe bütün check'leri aynı anda çalıştırır. Her biricheckTimeout(2s) sonra biten bir context altında çalışır. Hata dönen, panic eden ya da o süre içinde dönmeyen check başarısız olur. Bir sonuçcacheFor(1s) boyunca yeniden kullanılır ve bir çalışma sürerken gelen probe'lar onun sonucunu paylaşır. Bir hata loglanır, hiçbir zaman gönderilmez.detailsile readiness, her check'iokya dafailingolarak adlandıran bir JSON ile cevap verir. İsimler fazla şey söylüyorsa bunu kapalı bırakın.- Bir drain başladığında readiness
503 drainingolur ve check'ler çalıştırılmaz.DrainDelay'i, readiness probe'unun periyodu ile failure threshold'unun çarpımından biraz uzun tutun. maxInFlight(0, sınır yok) load shedding yapar: sınırı aşan request'e hemenRetry-After: 1ile503 overloadedcevabı verilir, hiçbir zaman kuyruğa alınmaz. Sınır client başına değil, globaldir; client başına sınır ratelimit'in işidir. Probe'lar hiçbir zaman sayılmaz ya da reddedilmez.- Bir request'i reddedebilen ya da ona cevap verebilen her plugin'den önce listeleyin, böylece bir probe ona her zaman ulaşır: tenant, bir probe'un pod IP'li host'una
404ile cevap verir, basicauth ondan parola ister, ratelimit ve fail2ban onu reddeder. compress ve accesslog ondan önce durabilir. accesslog v0.3.0'dan beri shed edilen bir request, accesslog nerede listelenirse listelensin loglanır: health'ten sonra listelendiğindebytesolmadan, önce listelendiğinde eksiksiz. Probe'lar accesslog'un varsayılanskip'i sayesinde log'un dışında kalır.
elagoht/jobs
github.com/Elagoht/collage-jobs, bir aralıkla ya da bir cron ifadesiyle zamanlanmış job'ları ve tipli arka plan queue'larını yalnızca uygulama hizmet verirken çalıştırır. Job'lar ve queue worker'ları, ListenAndServe port'unu bağladığında ServeHook üzerinden başlar. Job'lar drain başladığında tetiklenmeyi bırakır. collage build'de, bir plugin komutunda ya da yalnızca app.Handler() veya app.Start() çağıran bir test'te hiçbir şey çalışmaz.
import "github.com/Elagoht/collage-jobs"
j := jobs.New(jobs.Options{})
j.Every("refresh-feed", 15*time.Minute, refreshFeed).RunOnStart()
j.Cron("cleanup", "0 3 * * *", cleanup).Timeout(10 * time.Minute)
type Email struct{ To, Subject string }
mail := jobs.NewQueue(j, "email", func(ctx context.Context, m Email) error {
return send(ctx, m)
}, jobs.QueueOptions[Email]{Workers: 2, MaxAttempts: 3})
app, err := collage.New(&collage.Config{
Plugins: []collage.Plugin{j},
})
// In an action:
if err := mail.Enqueue(r.Context(), Email{To: to}); err != nil {
// jobs.ErrQueueFull, or jobs.ErrDraining once Shutdown has begun:
// tell the user to try again
}
{
"elagoht/jobs": {
"timezone": "Europe/Istanbul",
"disabled": ["cleanup"]
}
}
- Plugin'i yukarıdaki
jgibi bir değişkende tutun:collage plugin addjobs.New(jobs.Options{})'u doğrudan listeye yazar, orada kimse onun üzerindeEveryçağıramaz. - Her instance kendi zamanlanmış job'larını çalıştırır. Bir load balancer'ın arkasındaki N replica ile bir job her tetiklemede N kez çalışır; leader election yoktur. Böyle bir job'ı eşzamanlı çalışmaya karşı güvenli hâle getirin ya da yalnızca tek bir instance'ta çalıştırın. Bunu, her replica'nın paylaştığı bir config'teki
disabledile değil, ortama bakarakjobs.New(jobs.Options{Disabled: …})ile belirleyin. - Bir job, uygulama başlamadan önce tanımlanan bir
func(ctx context.Context) error'dır.Every(name, d, fn)onu herdsürede bir çalıştırır. Bu süre geçen zamanla ölçülür, bu yüzden ne DST ne de geri alınan bir duvar saati onu değiştirir.Cron(name, expr, fn)beş alanlı bir ifade alır: dakika, saat, ayın günü, ay, haftanın günü. Alanlarda*, değerler, aralıklar, adımlar ve virgülle ayrılmış listeler kullanılabilir; isimler, macro'lar ve saniyeler kullanılamaz. Ayın günü ve haftanın günü ikisi birden kısıtlandığında, Vixie cron'daki gibi ikisinden biri eşleşen gün eşleşmiş sayılır:0 0 1 * 1ayın 1'inde ve her pazartesi çalışır. Hatalı yazılmış ya da hiçbir zaman eşleşemeyecek bir ifadeCron'da panic eder. RunOnStart()job'ı plugin başlar başlamaz da çalıştırır.Timeout(d)her çalışmanın ctx'ini sınırlar ve job bu ctx'i dinlemelidir. Devam eden bir çalışma varken gelen tetikleme atlanır, böylece çalışmalar hiçbir zaman üst üste binmez. Başarısız olan ya da panic eden bir çalışma Error seviyesinde loglanır ve tekrar denenmez.- Cron ifadeleri
timezone'da (UTC) okunur. Bir DST değişiminde atlanan saatteki bir zaman, boşluktan sonraki ilk anda bir kez çalışır. Saati sabit olan bir schedule'da tekrarlanan saatteki bir zaman, ilk geçişinde bir kez çalışır. Saat alanı*ile başlayan bir schedule ise Vixie cron'daki gibi tekrarlanan saatin iki kopyasında da tetiklenir.disabled, çalışmayacak job'ların adlarını verir. Bilinmeyen bir ad, geçersiz bir zone gibi startup'ı başarısız kılar. - Zone, sistemin zoneinfo'sundan okunur.
FROM scratchbir image'da bu yoktur.mainiçindeimport _ "time/tzdata"ile, yaklaşık 450 KB'lık zone verisini binary'ye gömün. Scaffold'un distroless image'ı zoneinfo'yu zaten içerir. NewQueue[T],Ttipindeki item'ları type assertion olmadan bir fonksiyona verir.Workers(1) aynı anda işlenen item sayısıdır,Capacity(1000) kaç item'ın bekleyebileceğini sınırlar.MaxAttempts(1, yani tekrar yok) bir item'ın kaç kez deneneceğidir. Her tekrardan önce 1s, 2s, 4s… şeklinde, en fazla bir dakika beklenir.OnFailureson hatayla bir kez çağrılır.Enqueuehiçbir zaman bloklamaz: dolu bir queue'daErrQueueFull, yalnızca plugin'inShutdown'ı başladıktan sonra iseErrDrainingdöner. Drain hiçbir şeyi reddetmez, çünkü sunucu o sırada hâlâ hizmet verir. Item'lar bellekte durur ve process biterse kaybolur.- Shutdown, queue'daki işi bitirir. Devam eden çalışmaları bekler ve her queue boşalana kadar item almaya devam eder. ctx'i daha önce biterse çalışmaları iptal eder ve onlar için bir saniye daha bekler. Kalan item'lar Warn seviyesinde
dropped, vazgeçildikten sonra hâlâ süren çalışmalar iseabandonedolarak loglanır. Onunla bir durdurmaDrainDelay + ShutdownTimeout + 1skadar sürebilir. Platformunuzun grace period'u bunu karşılamalıdır; bkz. Deployment. - Onu, işinin kullandığı plugin'lerden sonra register edin. Böylece o plugin'ler hâlâ çalışırken önce o shutdown edilir. Onun shutdown deadline'ını paylaşırlar, bu yüzden
ShutdownTimeout'u queue'daki iş artı onların ihtiyacına göre ayarlayın. - Data handler'lardan enqueue etmeyin: bir build ya da header yakalaması onları çalıştırır ama hiç hizmet vermez, item da hiçbir zaman işlenmez. Scaffold edilmiş bir proje en azından onu dropped olarak loglar, çünkü
main.go'su build'den sonra uygulamayı shutdown eder. Kendihttp.Server'ını çalıştıran bir uygulama plugin'ij.Start(ctx)ile başlatır; bkz. Deployment.
elagoht/gesso
github.com/Elagoht/collage-gesso, bir gesso uygulamasını collage aynı process'te sunduğunda onun lifecycle'ını çalıştırır. gesso, collage'ın kendisinin yapmadığı backend işi için bir JSON API framework'üdür. API'nin modülleri (bir queue worker'ı, ısıtılmış bir cache) ListenAndServe port'unu bağladığında ServeHook üzerinden başlar. collage'ın server'ı durduktan sonra ters sırayla durur, ardından API'nin OnShutdown hook'ları çalışır. collage build'de, bir plugin komutunda ya da yalnızca app.Handler() veya app.Start() çağıran bir test'te hiçbir şey başlamaz.
Plugin API'yi mount etmez. Onu, middleware'i dışarıda tutan uygulamanın kendi Handle'ı ile mount edin ve plugin'e aynı app'i verin. App'i newApp içinde, collage.New'den önce kurun:
// main.go
api, err := gesso.New(gesso.Config{BasePath: "/api"}, notes.New(notes.Deps{DB: db}))
if err != nil {
return nil, err
}
api.OnShutdown(func(context.Context) error { return db.Close() })
app, err := collage.New(&collage.Config{
// …
Plugins: plugins(api),
})
if err != nil {
return nil, err
}
if err := app.Handle("/api/", api); err != nil {
return nil, err
}
// plugins.go: collage plugin add imports the plugin as gesso, so the
// framework takes another name here.
import (
"github.com/Elagoht/collage/pkg/collage"
gessoapp "github.com/Elagoht/gesso"
gesso "github.com/Elagoht/collage-gesso"
)
func plugins(api *gessoapp.App) []collage.Plugin {
return []collage.Plugin{
gesso.New(gesso.Options{App: api}),
}
}
- gesso v0.5.0 ya da sonrasını ister.
plugins-config.json'dan hiçbir şey almaz;Options.Appolmadan startup başarısız olur.pluginsargüman alabilir:collage plugin addvedellistesini yine düzenler. - Bir sayfa API'yi aynı process'te çağırır, iki tarafın da tanımladığı bir endpoint üzerinden:
notes.GetNote.Call(ctx, gesso.NewLocal(api), in, gesso.Bearer(token)). Çağrı API'nin bütün pipeline'ından geçer (authentication, guard'lar, validation) ve network üzerindeki gibi JSON ya da bir problem olarak döner; yalnızca bellekten hiç çıkmaz. API kendi process'ine taşındığında onun yerinegesso.NewRemote(url, nil)ile çağrılır, lifecycle'ını kendiRun'ı yönetir ve plugin kaldırılır; çağıran kod değişmez. - API'nin modülleri başlayamazsa hata Error seviyesinde loglanır ve API her request'e
503döner, problem koduunavailable: handler'ları çalışmayan modüllerle karşılaşırdı. - Devam eden bir request, hiçbir modül durmadan önce cevaplanır, çünkü collage plugin'leri shutdown etmeden önce server'ını durdurur.
OnShutdownhook'ları API hiç başlamadığında da (bir build'den sonra) çalışır; böylece kapattıkları bir veritabanı kapanmış olur. collagetestile kurulan bir test'te hiçbir şey hizmet vermez, bu yüzden modüller başlamaz: handler'lar cevap verir, bir worker'ın job'ları ise yalnızca test onları çalıştırdığında çalışır.
Plugin olmayan library'ler
Yukarıdaki plugin'lerin hepsi Config.Plugins içinde register edilir. Library ise kendi kodunuzun bir page'den ya da uygulamanın config'inden kullandığı bir modüldür. Bu yüzden register edilecek bir şey, collage plugin add ya da plugins-config.json'da bir bölüm yoktur ve kırk altı plugin'in arasında sayılmaz.
elagoht/paginate
Bir pager'ın aritmetiği, numaralı bir window (1 … 4 5 [6] 7 8 … 20) ve sayfalanmış bir listing için link'ler. Static export'un yazdığı path ile sayfalanmış link'ler (/blog, /blog/page/2) ve yalnızca bir sunucunun cevapladığı query ile sayfalanmış link'ler (/search?page=3) vardır. Bir data handler'dan ve bir template'ten kullanılır. Bkz. Pagination.
go get github.com/Elagoht/collage-paginate
FromPath(rc, last),PathNamedileStaticParams'ın yazdığınpath parametresini okur; v0.1'de parametrenin adını alırdı.paginate.Versionkaldırıldı.
elagoht/redis
Redis tabanlı bir collage.SharedCache. Bir uygulamanın her instance'ı tek bir page cache ve tek bir collage.Cached data store'u ile çalışır. Böylece herhangi bir instance'taki invalidation'ı hepsi görür. Cache.Store'a verilir:
go get github.com/Elagoht/collage-redis
import "github.com/Elagoht/collage-redis" // package redis
store, err := redis.New(redis.Config{URL: os.Getenv("REDIS_URL")})
if err != nil {
log.Fatal(err)
}
defer store.Close()
app, err := collage.New(&collage.Config{
Cache: collage.CacheConfig{Enabled: true, Store: store},
})
- Redis 6 ya da sonrasını gerektirir. Tek bir node ve Sentinel (
Config.Clientüzerinden) desteklenir, Redis Cluster desteklenmez. NewRedis'e hiç bağlanmaz. Bu yüzden Redis kapalıyken de uygulama açılır ve cache'siz sunar. Bir Redis hatası bir miss'tir, asla başarısız bir request değildir.- Varsayılan olarak yeni bir binary'nin her deploy'u boş bir namespace ile başlar.
MaxAge(yedi gün), stale fallback dahil her key'i sınırlar. Config ve bunun için Redis'in nasıl çalıştırılacağı Caching sayfasında ve library'nin README'sinde anlatılır.
Head'e yazan plugin'ler
Document'ın head'ine structured data, meta tag ya da preload ipucu gibi içerik ekleyen bir plugin, bunu hoist ederek yapar. Fragment'ler de title'larını ve stylesheet'lerini aynı mekanizmayla ekler. Hoist edilen içerik, yalnızca layout'un {{hoist "head"}} çağırdığı yere yerleşir:
<head>
<meta charset="utf-8">
{{hoist "head"}}
</head>
Bu marker olmadan hiçbir şey görünmez. Plugin register edilir, çalışır ve bloğunu tanımlar, ama bloğun yerleşeceği bir yer yoktur. Bu bilinçli bir tercihtir. HTML içinde </head>'i arayıp kendini araya ekleyen bir plugin, layout'unuzu ilgilendiren bir kararı sizin yerinize vermiş olurdu.
collage new ile oluşturulan layout'larda marker zaten vardır. Elle yazdığınız bir layout'ta olmayabilir. Hoist mekanizmasının genel anlatımı için Head ve SEO sayfasına bakın. Yayımlanmış plugin'lerden jsonld, meta, ogimage, feed, favicon ve analytics head'e bu yolla yazar.
Plugin'ler nerede çalışır
Plugin'ler, bir sunucunun render ettiği page'lerden fazlasını görür:
- Cache'lenen page'ler yalnızca bir kez işlenir. Plugin'in HTML'de yaptığı değişiklikler, page cache'e yazılmadan önce yapılır. Bu yüzden cache hit olduğunda işlenmiş byte'lar, plugin yeniden çalıştırılmadan sunulur. Her request'te çalışması gereken bir plugin, örneğin ziyaretçiye özel bir değer ekleyen bir plugin, cache'lenen bir page ile birlikte kullanılamaz.
- Error page'leri de aynı render hook'larından geçer. Böylece 404 page'iniz de diğer page'ler gibi minify edilir ve zenginleştirilir.
- Bir action'ın response olarak döndüğü page de
OnAfterRender'dan geçer Bu page, bir form'un validation sonrası yeniden render'ıdır. BöyleceGETile gelen page gibi minify edilir. Bkz. Form'lar ve action'lar. - Document'lar (sitemap'ler, feed'ler, JSON) kendi hook'larından geçer. Böylece bir minifier onları da kapsar. Bkz. Document'lar.
- Static export da sunucudaki render ile aynı render hook'larını çalıştırır. Her plugin önce başlatılır ve yapılandırılır. Böylece export edilen site, sunucunun sunduğu siteyle aynı olur. Bkz. Static export.
- Static bir build'in header yakalaması bir
BuildFinishedHookplugin'i register edilmişse yazılan her dosyayı handler'a sorar. Bu yüzden middleware ve request hook'ları bir build'in path'lerini görür. Trafiği sayan ya da sınırlayan bir plugin bunlarıcollage.IsCapture(r.Context())ile atlar. Bkz. Static export. - Düz bir
app.Handlemount'unun etrafında değil. v0.67.0'dan beri uygulamanınapp.Handleile mount ettiği bir handler için,collage.WithMiddleware()ile mount edilmedikçe hiçbir plugin'in middleware'i çalışmaz: session, basicauth, rate limit, ban, access log, redirect ya da tenant yoktur. Request hook'ları onun için yine de çalışır, bir plugin'in kendiHost.Handleendpoint'leri ise her zaman middleware'in içinde çalışır. Bkz. İstemedikçe middleware yok. - Yalnızca hizmet verirken çalışan iş (bir scheduler, bir queue worker'ı)
OnServe'de başlar. Onu yalnızcaListenAndServeçağırır: bir static export, bir plugin komutu veapp.Handler()onu hiçbir zaman başlatmaz. Bkz. Plugin yazmak.
Daha ileri
Plugin yazmak sayfası plugin sözleşmesini, her hook'u ve her hook'un neyi değiştirebileceğini anlatır. Ayrıca testleriyle birlikte eksiksiz bir plugin örneği içerir.