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.Plugins iç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. RegisterPlugin ile 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üz app.Handle ile 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 new ile oluşturulan bir projede bunlar go 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:

Request önce plugin middleware'inden, sonra app.Use'dan, sonra router'dan geçer. Cache'te bulunan bir page doğrudan OnPersonalise'a gider. Bulunmazsa OnBeforeRender çalışır, page render edilir, OnAfterRender HTML'i değiştirebilir, sonuç tag'leriyle cache'e yazılır ve OnPersonalise onu her okuyucu için yeniden yazar. Request dışında InvalidateTags OnCacheInvalidate'i, tamamlanan bir static build de OnBuildFinished'ı tetikler.requestplugin middleware'iapp.Userouterpage cache'te mi?hitmissOnBeforeRenderrender: fragment'ler veri çekerOnAfterRender · ev.HTMLcache'e yazım · tag'lerOnPersonalise · her okuyucuresponsekendi başınaInvalidate/PurgeTags→ OnCacheInvalidatestatic build yazıldı→ OnBuildFinished
Config.Plugins'teki plugin'lerin middleware'i, request'i uygulamanın kendi middleware'inin dışından sarar. Cache'te bulunan bir page render hook'larını atlayıp doğrudan OnPersonalise'a gider; yani cache'e yazılan, OnAfterRender'ın değiştirdiği hâlidir. Yeni bir render önce OnBeforeRender'ı, sonra OnAfterRender'ı çalıştırır; OnAfterRender HTML'i, tag'leriyle cache'e yazılmadan önce değiştirebilir. Hiç cache'lenmeyen bir page'de cache'e bakılmaz ve yazılmaz: request router'dan doğrudan OnBeforeRender'a gider. Page'iyle cevap veren bir action da OnBeforeRender'ı ve OnAfterRender'ı çalıştırır, ama cache'lemez. Tag'leri invalidate ya da purge etmek, nereden çağrılırsa çağrılsın, ve bir static build'i bitirmek kendi hook'larını tetikler.

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:

HataNe zaman
ErrAppStartedUygulama 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.
ErrDuplicatePluginAynı 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.ErrUnknownPluginConfig dö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. Kontrol New iç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.

GrupPlugin'ler
SEO ve keşfedilebilirlikjsonld, meta, ogimage, sitemap, robots, feed, redirects, indexnow
İçerikmarkdown, highlight, toc, search, i18n
Form'lar ve statevalidate, honeypot, flash, session, uploads
Güvenliksecure, ratelimit, basicauth, oauth, fail2ban, consent
Canlı güncellemelerlive, websocket, client
Asset'ler ve teslimatminimizer, opti-image, bundle, favicon, compress, cdnpurge, offline, deploy
Operasyon ve developmenthtmlcheck, 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 kuruyorsunuzBaşlangıçSize ne sağlarlar
Bir blogmarkdown, highlight, toc, feed, sitemap, robots, meta, jsonld, ogimage, searchMarkdown 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ğujsonld, meta, sitemap, opti-image, i18n, cdnpurge, compress, minimizerProduct 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, liveBir 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
}
  • Configure aşaması yoktur, bu yüzden RegisterPlugin de bu plugin'i kabul eder. v0.3.0 siteURL'i kaldırdı: onun yerine uygulamanın BaseURL'ünü ayarlayın.
  • Emit mevcut node'lara ekleme yapar ve plugin register edilmiş olsun ya da olmasın çalışır. Node'lar schema.org tipine ve Key alanına göre key'lenir. Bu yüzden iç içe bir fragment'in Article'ı, daha dıştaki bir fragment'te tanımlanan Article'ı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 Key verin (v0.4.0). Key page'e yazılmaz: döngü içinde jsonld.Emit(rc, jsonld.Person{Key: p.Slug, Name: p.Name}) her kişiyi korur. Key verilmezse sonraki Person öncekinin yerini alır. ID ayrı 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ürleriyle WebPage, ProfilePage, BreadcrumbList, ItemList), yazı (Article, NewsArticle, BlogPosting, Blog, DiscussionForumPosting, QAPage, FAQPage), kişi ve kurumlar (Person, Organization, LocalBusiness, EmployerAggregateRating), Event, ticaret (kargo ve iadeyle Product, 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çin jsonld.Raw kullanılır. jsonld.Raw geçersiz JSON'u reddeder.
  • Bir Event'in konumu bir Place, bir OnlineURL ya da karma bir etkinlik için ikisi birden olur. Saatleri kendi ofsetiyle yazılır: duvar saati biçimindeki bir zamanı time.Parse ile değil (UTC demektir), etkinliğin saat diliminde time.ParseInLocation ile 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 bir OriginResolver plugin'inin verdiğini. İkisi de yoksa uygulama başlamaz. v0.3.0 plugin'in kendi baseURL'ü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 bir hreflang link'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.Set ile 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 gibi rc.HoistTitle ya da WithTitle'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 bir OriginResolver plugin'i register edilmişse Config.BaseURL gerekmez. elagoht/meta'dan sonra register edin ve meta'nın DefaultImage'ını boş bırakın.
  • v0.3.0'da tek bir constructor vardır: ogimage.New(ogimage.Options{…}). renderTimeout bir süre string'idir ("5s"), negatif bir maxEntries ya da maxBytes artık sınırsız değil hatadır, build finding'i de ogimage-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ş bir Locale yine "en" ile çizer. Statik build artık maxEntries ya da maxBytes'ın tuttuğundan fazla kart olsa bile her kartı çizer; önceden, çizilmeden önce çıkarılan kartlar için ogimage-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 bir html/template dosyasıdır: kutu içeren bir element display:flex der, 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 export kartları yazar. Dir kartları 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.png siteye 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 bir OriginResolver plugin'inin adlandırdığı, request'in kendi origin'i. İkisi de yoksa uygulama başlamaz. v0.3.0 plugin'in kendi baseURL'ünü kaldırdı.
  • Path'i olan her page'i, her locale'de, App.URL'in yazdığı biçimde listeler. Page'in diğer locale'leri hreflang alternate'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 olan LastMod verir.
  • Static bir document'tır: cache'lenir, export edilir ve sitemap.Tag invalidate 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 bir crawlDelay uygulamayı 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'u X-Robots-Tag: noindex, nofollow ile 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 bir OriginResolver plugin'inin verdiğine. Scheme-relative //host/path reddedilir; bir path'i karşısında çözeceği origin yoksa uygulama başlamaz.
  • Body uygulama başlarken sabitlenir ve static build onu robots.txt olarak 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"},
})},
  • Items bir 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. RSS ve Atom bu path'leri değiştirir, "-" ise bir formatı dışarıda bırakır. Birden fazla feed'in her biri bir Name ve kendi path'lerini alır. Bir feed en fazla Limit kadar öğ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 http ya da https olarak yazılır (v0.2.1'den beri). Başka bir scheme taşıyan bir öğe link'i, URL biçimindeki bir ID ya 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 kez WARN seviyesinde log'lanır. Bir feed'in kendi Link'i, RSS'i ya da Atom'u böyle bir scheme taşırsa uygulama ErrUnsafeLink ile başlamaz. Mutlak bir http ya da https link'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 bir OriginResolver plugin'inin verdiğini. Böylece tek bir feed her host'a kendi link'lerini sunar. v0.3.0 Feed.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, 308 ya da artık olmayan bir page için - ile birlikte 410 olabilir. Bu durumda sitenin kendi not-found page'i 410 status'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.NoRedirectsFile ve RedirectsFile() kaldırıldı, config'teki noRedirectsFile key'i ise bilinmeyen bir key olarak uygulamayı durdurur. Plugin bir RedirectSource'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-exported uyarısıyla build'in dışında bırakılır. Bir page'in ya da document'ın kendi redirect'ini kapsayan bir kural ise redirects-overlap uyarı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"]
  }
}
  • key zorunludur. URL'ler Config.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ı ve exclude'un adını skip yaptı: hiç gönderilmeyen request path prefix'leri; "/api" hem /api'yi hem altındakileri kapsar. window ve backoff süre string'leridir, negatif bir retries ya da batchSize uygulamayı 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 window boyunca toplanır, arka planda gönderilir ve bir 429 ya da 5xx gelirse 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.Plugins iç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, definitionList ve typographer. 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, ışık olur). Code block'lar <pre><code class="language-go"> biçimindedir; elagoht/highlight register edildiyse onları renklendirir.
  • Ham HTML ile bir başlığın {style="…"} ve on… attribute'ları, unsafe açık değilse dışarıda bırakılır; id ve class kalır.
  • v0.4.0'da değişen: plugin artık bir dizin okumaz. FS, Dir, LocaleDirs, Drafts, Name, Handler, IndexHandler, StaticParams, List, Get, Tag ve DirTag kalktı; uygulama kendi dosyalarını okur ve page'lerini markdown.Parse ile 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.Plugins içinde olmalıdır: {{highlight}}'ı ekler.
  • noAuto açı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-scheme sorgusu altındadır. noAuto: true bu 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'i AfterRenderEvent.Hoist ile 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.Plugins içinde olmalıdır: template fonksiyonları ekler.
  • v0.2.0'dan beri varsayılan locale'in metinleri en üst seviyede değil, text altındadır (Options.Text, gömülü değil, adı olan bir alan); diğer locale'ler locales içindedir. "ids": false artık "noIDs": true. En üst seviyede kalmış eski bir label ya da ids, bilinmeyen key olarak uygulamayı durdurur.
  • Her fonksiyon bir placeholder yazar. Plugin, page render edildikten sonra onu doldurur: <main> içindeki h2–h4 heading'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.Plugins içinde olmalıdır: {{searchBox}}'ı ekler.
  • v0.2.0'dan beri exclude path 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ı text altındadır (label, placeholder, results, oneResult, noResults, unavailable); locales aynılarını locale başına tutar.
  • Index bir static build'e aittir.collage export, her page'in title'ından, description'ından, heading'lerinden ve metninden search-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.Plugins içinde olmalıdır: template fonksiyonları ekler. Kataloglar Options.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.
  • t bir key'i çevirir ve {name}'i ad-değer çiftlerinden doldurur. tn bir sayı için çoğul biçimi seçer, th ise katalogdan gelen markup'a izin verir. Bir data handler i18n.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.
  • th her 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 #ZgotmplZ olur; 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 bir javascript: değeri çalışan bir link oluşturuyordu. Bir tag'in ya da attribute'un içinde biten bir entry artık render'ı bir i18n: 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-missing olarak 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) bir Translator döndürür. Bu değerin T, TN ve TH metotları aynı katalogları, fallback'i ve çoğul biçimleri kullanır. Funcs() ise uygulamanın kendi html/template'ine t, tn ve th verir. Uygulamanın desteklemediği bir locale varsayılan locale olur. Bulunamayan bir key, her key ve locale için bir kez loglanır. Kataloglar collage.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-untranslated olarak listelenir. v0.2.0'dan beri bu iki yönde de yapılır (v0.3.0'dan önce kodlar missing-translation ve untranslated idi). Bir locale'in kuralının hiç seçmediği çoğul biçim sayılmaz, zero sayılır. strict açı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.Plugins iç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 da v.Value form'a ihtiyaç duyana kadar hiçbir şey okumaz. Body'yi okumadan reddeden bir action (örneğin Content-Length'i sınırı aşan bir fotoğraf) v.Fail ve validate.Refuse iç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'ın WithMaxBodyBytes değeri kontrol ettiği boyutun üzerinde olmalıdır. Aksi halde önce collage'ın 413'ü 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, Equal ve Custom'dır. v.Fail, yalnızca uygulamanın bildiği bir durumu raporlar. Bir alan ilk mesajını korur. OneOf dışı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. Önceden MinLen, MaxLen, Email, OneOf, Matches, Equal ve Custom değeri geldiği gibi görürdü; bu yüzden Value()"x" döndürürken MinLen(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, Equal iki alanı da kırpılmış karşılaştırır ve Custom kı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) ve Lines() (bir textarea'nın satırları) alanı tipli bir alana çevirir. Bu alanın Value()'su int, float64, bool, time.Time ya da []string'dir ve kontrolleri bu değer üzerinde çalışır: Min, Max, Range, MinItems, MaxItems, Custom(func(int) string). Boş bırakılan alanda Ptr() 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 *IntField dö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 password geçen bir alan asla geri doldurulmaz. noRefill bu listeye kendi adlarınızı ekler (v0.2.0'dan beri password'ü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ğin uploads.Receive'in bir body'yi stream ettikten sonra geri verdiği alanlar. Refuse bunları 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.Plugins iç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ığı yere HONEYPOT_KEY= (openssl rand -hex 32) yazın. keyEnv başka bir değişkenin adını verir ve önceliklidir; ardından Options.Key, en son HONEYPOT_KEY gelir. Adı verilen değişkenin ayarlı olması gerekir, HONEYPOT_KEY boş olabilir; ikisinden biri hex değilse uygulama başlamaz.
  • v0.5.0'da değişenler: hex key kalktı. Artık keyEnv key'i tutan ortam değişkeninin adını verir, Go'dan ise Options.Key byte'ları doğrudan alır. maxAge ve minDelay süre string'leridir ("24h", "300ms"). {{honeypot 0.3}} hâlâ saniye alır. Varsayılan "0s" bekleme olmadığı anlamına gelir (-1 artı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'ın WithMaxBodyBytes'ı yeter. Yalnızca collage action'ları kontrol edilir, app.Handle ile 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'un action'ı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 her GET kontrol 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; protect bunu 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 PersonaliseHook ile, page cache'ten sonra ve sıkıştırmadan önce onun yerine koyar. Config.Plugins iç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 page Cache-Control: private, no-store (collage ayarlar) ile ve her response'ta yeni bir ETag ile 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; asla plugins-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.Handle ile 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'i protect'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. silent ile ise kabul edilmiş bir form'un cevabı gibi, form'a geri dönen bir 303'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.Plugins iç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ığı yere FLASH_KEY= (openssl rand -hex 32) yazın. keyEnv başka bir değişkenin adını verir ve önceliklidir; ardından Options.Key, en son FLASH_KEY gelir. Adı verilen değişkenin ayarlı olması gerekir, FLASH_KEY boş 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ı veren keyEnv oldu (Go'daki Options.Key değişmedi). maxAge saniye yerine bir süre string'idir, varsayılanı "5m". Eski bir key, uygulamayı unknown key "key" ile durdurur.
  • Mesajlar imzalı, HttpOnly bir cookie içinde taşınır. collage.IsHTTPS request'in HTTPS ile geldiğini söylediğinde cookie Secure olur. 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-Cookie satı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-store olarak 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 de SESSION_PREVIOUS_KEYS'ten hiçbir şey ayarlanmadan okunur: .env.development'a ve production'ın çalıştığı yere SESSION_KEY= (openssl rand -hex 32) yazın. keyEnv ve previousKeysEnv baş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 RegisterPlugin de onu kabul eder.
  • v0.3.0'da değişenler: key'ler artık plugins-config.json'a girmez. keyEnv hex key'i tutan ortam değişkeninin, previousKeysEnv ise önceki key'leri virgülle ayrılmış olarak tutan değişkenin adını verir. Go'dan Options.Key ve Options.PreviousKeys byte'ları doğrudan alır. maxAge ve idleTimeout saniye yerine süre string'leridir ("168h", "30m"). Eski bir key ya da previousKeys, uygulamayı unknown key ile durdurur.
  • RequireUser(loginPath) (v0.2.0'dan beri), session'ında session.UserKey ("user") altında bir değer bulunan okuyucuyu içeri alır. Diğer herkesi 303 ile loginPath'e gönderir; gitmek istedikleri yer next iç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'i ErrNoSession ile başarısız kılar. Her okuyucuyu, onu asla içeri alamayacak bir login'e göndermez. Login action'ı next'e redirect etmeden önce next'i collage.SafeRedirect'ten geçirin: collage.SafeRedirect(rc.Request.URL.Query().Get("next"), "/").
  • RequireUserPage(loginPage) login page'inin path'ini yazmak yerine adını alan RequireUser'dır. Path her request için collage.URL ile, 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) ve RequireGuestPage(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'teki nextcollage.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) 303 ile gönderilir. Auth page'lerinin layout'unda: WithGuard(session.RequireGuestPage("account")).
  • Metotları Get, Set, Delete, Clear, Regenerate ve ID'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-store olarak 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 HttpOnly ve SameSite=Lax'tir, yalnızca session değiştiğinde yazılır ve collage.IsHTTPS request'in HTTPS ile geldiğini söylediğinde Secure olur. 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'ten globex.test'e kopyalanan bir cookie orada anonimdir. Tek siteli bir uygulamada domain ayarlanı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 orada domain ayarlamayın. Host, request'in Host'udur: onu yeniden yazan bir proxy'nin arkasında orijinal Host'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 RegisterPlugin de onu kabul eder. Plugin'i bir değişkende tutun: action u.Receive'i çağırır, uygulama da u.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ı gerekiyorsa app.Handle çağrısına collage.WithMiddleware() ekleyin.
  • v0.2.0'da değişenler: tek bir constructor var, uploads.New(uploads.Options{…}): New(store) artık New(uploads.Options{Store: store}), NewWith(uploads.Config{Dir: d}) ise New(uploads.Options{Dir: d})'dir. Handler argüman almaz; Cache-Control değeri yapılandırmada cacheControl, Go'da Options.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 ve Receive parse edilmiş form'u okur. Bu, onlarca MB'a kadar dosyalar için uygundur. WithStreamingBody() ile kurulmuş bir action'da ise body'yi MultipartReader ile dolaşır ve her dosyayı doğrudan store'a stream eder. Böyle bir action token'ı yalnızca X-CSRF-Token header'ından alır, bu yüzden ona fetch() ile post edin. Form'u önce parse eden her şey (validate.Form dahil) 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'ı ve ErrTooLarge, ErrType, ErrTooMany ya da ErrUnexpectedField'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 Receive dönmeden önce silinir. Başarılı olduktan sonra dosyalar sizindir. Action bundan sonra başarısız olursa onları u.Store().Delete ile 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'iyle X-Content-Type-Options: nosniff, Content-Security-Policy: sandbox ve yeniden sniff edilmiş tipiyle sunar. Dosya bir PNG, JPEG, GIF ya da WebP resmi değilse Content-Disposition: attachment ekler. 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'ı ve MaxSize'ı dar tutun, path'e rate limit koyun, store'u kendine ait bir volume'da tutun ve action'a WithBodyTimeout verin. Proxy'ler için Deployment sayfasına bakın. Receive ile 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.Plugins içinde olmalıdır: {{cspNonce}}'ı ekler. Listedeki yeri fark etmez: nonce, PersonaliseHook ile 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-Policy ve Cross-Origin-Opener-Policy gönderir. Strict-Transport-Security'yi ise TLS üzerinden ya da X-Forwarded-Proto: https gönderen bir proxy'nin arkasında gönderir. v0.3.0'dan beri bu header'a, Server.TrustedProxies doluysa yalnızca oradaki bir proxy'den geldiğinde inanılır (collage.IsHTTPS). Permissions-Policy ve CSP, ayarlandıklarında gönderilir. "-" bir header'ı dışarıda bırakır; X-Content-Type-Options da 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 page Cache-Control: private, no-store (collage ayarlar) ile ve her response'ta yeni bir ETag ile gönderilir. Diğer her response conditional request'lere her zamanki gibi cevap verir: bir feed, bir document ya da mount edilmiş bir dosya 304'ü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 asla plugins-config.json'a girmez: keyEnv başka bir değişkenin adını verir ve önceliklidir, ya da Options.Key byte'ları Go'dan alır ve SECURE_KEY'e göre önceliklidir (v0.3.0; key ve Options.KeyHex kaldı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 bir SECURE_KEY uygulamanın başlamasını engeller; key'i gizli tutun.
  • Policy yoksa ya da policy {nonce} içermiyorsa adlandırılacak bir nonce da yoktur: nonce attribute'u static build'deki gibi kaldırılır, page sabit bir ETag ile 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 nonce attribute'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, HEAD ve OPTIONS dışı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/, /healthz ve /readyz) ve bir kuralın pathPrefix'i tam segment eşleşir, sondaki / olsa da olmasa da: /login, /login-help'i kapsamaz. Response'lar RateLimit-Limit, RateLimit-Remaining ve RateLimit-Reset taşır.
  • Bir istemci IP adresidir, IPv6'da ise /64'üdür. Bir reverse proxy'nin arkasında proxy'leri collage'ın Server.TrustedProxies'ine yazın; istemci o zaman collage.ClientIP'dir. Plugin'in kendi trustProxy ve trustedProxies ayarları v0.2.0'da kaldırıldı; bunları içeren eski bir yapılandırma başlangıçta durur. Go'daki KeyFunc baş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 /64 saldırganın tamamı değildir: bir tunnel broker ücretsiz bir /48 verir, birçok hosting sağlayıcısı da her sunucuya bir /48 ya da /56 verir; bu, her biri kendi bucket'ına sahip 65536 ya da 256 /64 demektir. 48, bütün bir /48'i tek istemci ve tek bucket yapar; o /48'deki herkes onu paylaşır. 128 tek 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 RateLimit header'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, disabled ayarlanmadıkça uygulama başlamaz. skip'in varsayılanı /healthz, /readyz ve /_collage/'dır.
  • collage'ın middleware'inden geçeni kapsar: her page, document, action, mount edilmiş dizin ve plugin handler'ı. Uygulamanın kendisinin app.Handle ile 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çin app.Handle("/api/", api, collage.WithMiddleware()) ile mount edin; protect ve skip ona 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:y gö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ği GET'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.
  • disabled ya da COLLAGE_BASICAUTH_DISABLED=true, aynı binary'nin bir deploy'unu, production'dakini, açık bırakır.
  • Kimliği doğrulanmış her response'ta public, private ile değiştirilir ve response Vary: Authorization taşı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 build basicauth-exported uyarı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ı 500 döner. collage plugin add elagoht/oauth önce elagoht/session'ı ekler. OnLogin ve Store kod 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, keyEnv ve previousKeysEnv ile verir (v0.2.0'dan beri; key, previousKeys ve Options.KeyHex kaldırıldı, eski bir yapılandırma başlangıçta durur).
  • v0.3.0'dan beri ne keyEnv/previousKeysEnv ne de Go option'ları key vermezse key OAUTH_KEY'den, önceki key'ler OAUTH_PREVIOUS_KEYS'ten okunur: Store token saklıyorsa .env.development'a ve production'ın çalıştığı yere OAUTH_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}/login ve {prefix}/{name}/callback'tir (prefix /auth), yalnızca GET. Sağlayıcıya {origin}/auth/google/callback adresini kaydedin. Origin Config.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 issuerhttps olmalıdır (düz http yalnızca localhost'a ya da bir loopback IP'ye), yoksa site başlamaz. Böyle olmayan bir endpoint adlandıran discovery document girişi unavailable ile bitirir. Token ve revocation çağrıları hiçbir redirect'i izlemez. elagoht/session'ın sameSite ayarı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 üzerinden Secure, ve sonucu ne olursa olsun callback tarafından silinir. Bir girişi herkes başlatabilir; session ise imzalıdır, maxAge boyunca yaşar ve taşıyanı için page cache'i kapatır: önceden login route'una tek bir anonim GET, 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 bir nextafterLogin'de biter. Yapılandırmada değiştirilecek bir şey yoktur; yükseltme sırasında süren bir giriş state ile başarısız olur. Önceki bir sürümün bu yolla ürettiği session'lar, session key'i değiştirilmezse maxAge sonuna kadar geçerli kalır.
  • microsoft preset'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çin issuer'ı onunkine ayarlayın (https://login.microsoftonline.com/<tenant-id>/v2.0): ayarlanmış bir issuer birebir eşleşmelidir. Microsoft email_verified göndermez, bu yüzden onun için EmailVerified false'tur. offline, preset'i olmayan bir sağlayıcıdan offline_access scope'unu ister.
  • Bir giriş state, nonce ve PKCE kullanır, id_token'ın claim'lerini kontrol eder, session'a yeni bir ID verir (ya da bir session başlatır) ve okuyucuyu collage.SafeRedirect ile 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 + Subject ile eşleyin. E-postaya da yalnızca EmailVerified true 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 Store ve bir key (en az 32 byte: Go'dan Options.Key ya da keyEnv'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.Client döndürür. errors.Is(err, oauth.ErrNotLinked) okuyucuyu yeniden girişe göndermek demektir; Revoke bağlantıyı koparır. Key'i değiştirmek için eskisini PreviousKeys'e (ya da previousKeysEnv'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 next kontrol 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 bir RequestHook'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/accesslog ondan önce gelebilir: yalnızca satırı yazar ve ilk sırada bir ban'ın 403'ü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-For taşıyan ama ClientIP'si yine o adres olan bir request sayılmaz ve tek bir Warn TrustedProxies'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 /48 sahibinin (ü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. 128 tek 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; bir Ban'ın Prefix'i bloğunkidir.
  • probe jail'i (10m içinde 3 strike, 1h ban) bir probe path'i isteyen (/.env, /.git/, /wp-login.php gibi, ayrıca herhangi bir yerde .env ile başlayan ya da .git olan bir segment; kendinizinkini probePaths ile 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, 404 ya da başka bir hatayla yanıtlanmadıkça sayılmaz. notfound jail'i (1m içinde 50, 10m ban) diğer her 404'e strike verir, bir mount'unki hariç. Tarayıcının bir alt kaynak request'i (image ya da script gibi bir Sec-Fetch-Dest) asla strike vermez; Sec-Fetch-Site: cross-site olarak 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ızca Report'ta strike verir; herhangi birini adıyla override edebilir ya da "disabled": true ile kapatabilirsiniz (v0.2.0'a kadar "off"). Süreler string olarak yazılır ("10m", "1h30m"); "banTime": 3600 gibi çıplak bir sayı, key'i adlandırarak uygulamayı durdurur.
  • Tekrarlanan ban iki katına çıkar, maxBanTime'a (24h) kadar. Banlı istemci düz bir 403 Forbidden alır, sitenin error page'ini asla. Encoded slash'li ya da kirli path'li bir request için collage'ın kendi 404'ü ya da redirect'i yine de ona ulaşır.
  • Ban bir middleware'dir. Düz app.Handle ile 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 zaten findTime sonunda düşer. allow, hiç sayılmayan ve banlanmayan adresleri ve aralıkları listeler. Ban, Unban ve Bans elle kullanılan API'dir (Ban bir 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 inDevelopment ayarlanmadı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 bir Warn, fail2ban: the ban table is full der; Go'dan Ban da aynı şekilde reddedilir. Önceden bir saldırgan, maxBans kadar başka adresi banlatarak kendi ban'ını kaldırabilirdi. maxBans'i yükseltin ya da suçlular tek bir /48'in /64'leriyse ipv6Prefix'i 48 yapı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. required bir kategori her zaman onaylıdır ve cookie'ye yazılmaz. text varsayılan locale'in metnidir ve her kategoriyi etiketlemelidir; diğer locale'ler locales'te durur ve eksik key'leri text'ten alır (v0.2.0'dan beri; eski text: {"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 sonra document üzerinde collage:consent event'i. data-consent-open taşı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'da consent.Granted(rc, "analytics") çağırın. Page cache cookie başına değil, seçim başına bir kayıt tutar. serverPaths dışında, static export'ta ve build'in capture request'inde Granted false döner (required kategori için true). Bu path'lerdeki her response Vary: Cookie taşı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_consent adlı first-party cookie'de tutulur ve script onu okur. Bu yüzden onu sunucudan ya da HttpOnly olarak 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üzden style-src onun hash'ine izin vermelidir; güncel hash plugin'in README'sindedir ('unsafe-inline' de işe yarar). Bekletilen inline script'in kendi nonce'u ya da metninin 'sha256-…' hash'i script-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, required bir kategori için bile false döner. Analytics için elagoht/analytics'te consentCategory ayarlayı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.Plugins iç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'ın collage.put'u ile girer. collage plugin add elagoht/live client'ı da ekler; client yoksa collage.New baş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'u Init'inin yanı sıra Configure'ından da çağırabilir; son çağrı geçerlidir (v0.5.2).
  • keepAlive ve maxStreamAge süre string'leridir (live.Options içinde collage.Duration): bir sayı, negatif bir süre ya da negatif bir maxFragments uygulamayı durdurur, null ise varsayılanı bırakır. v0.5.0'dan beri live.New() ve live.NewWith(live.Config{…}) tek bir live.New(live.Options{…}) oldu.
  • Container'ın sahibi page'dir, içindekinin sahibi fragment'tir. data-collage-interval belli aralıklarla fetch eder, data-collage-push fragment'i stream'den alır, data-collage-swap="morph" DOM'u collage-client'ın morph'uyla yerinde patch eder. Bir form üzerindeki data-collage-target ise form'u fetch ile gönderir ve cevabı bir element'in içine koyar. Bunu başarı durumunda ya da bir 422 geldiğ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'ın Collage-Fetch header'ı 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:swap collage-client'tan gelir ve detail: { url: null, mode, inner: true } taşır.
  • Client elindeki ETag'i gönderir ve 304 gelirse 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'i data-collage-stale ile 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 ve collageLive.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 element data-collage-paused taşı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:swap ise değişiklikten sonra tetiklenir. data-collage-transition her cevabı document.startViewTransition içinde yerine koyar: push'lar, poll'lar, form cevapları ve put da dahil. Böylece bir cevaptan diğerine view-transition-name'ini koruyan kartlar yeni yerlerine kayar. API yoksa ya da prefers-reduced-motion: reduce açıksa cevap hemen yerine konur. Daha fazla kontrol için collage:before-swap, element değişmeden hemen önce element üzerinde tetiklenir. preventDefault çağıran bir listener e.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ılan swap() hiçbir şey yapmaz. Element sabit tutulurken çağrılan bir swap() 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 bir collage.Cached ile çeker. Böylece bir fragment'in tick'i diğerlerini yeniden render ettirmez. Shared olmayan bir fragment her bağlantı için render edilir; data cache açıkken Cached, ç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 maxStreamAge bağ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'iniz text/event-stream'e dokunmamalıdır. Aksi hâlde stream ancak bittiğinde ulaşır. noStream açı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/websocket collage-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 yoksa collage.New baş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 yine data-collage-push taşı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'ın keepAlive aralığında ping'lenir ve live'ın maxStreamAge süresi dolunca kapatılır. Live'da noStream açı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ü. Path ve Ping kalktı; config'te path ya da ping bilinmeyen 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.Plugins iç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önen querySelectorAll'dur. İkinci argüman olarak bir root verilmedikçe ikisi de document üzerinde çalışır.
  • collage.replace(target, url?) bir fragment'i çeker ve onu, outerHTML'in yapacağı gibi, target'ın yerine koyar. target bir selector ya da bir Element'tir. url'in varsayılanı element'in data-src'sidir; WithFragmentPath ile 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 onu replace edin.
  • 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'un fetch'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. inner olmadan içerik tek bir element olmalıdır. inner ile element yerinde kalır ve çocukları içerikle değiştirilir ya da morph edilir. innerHTML gibi o da hiçbir origin kontrolü yapmaz, bu yüzden ziyaretçinin yazdığı bir şeyi asla ona vermeyin. Element üzerinde süren bir replace ya da morph'u iptal eder.
  • Herhangi biri bittikten sonra page'deki element'ten bir collage:swap event'i bubble eder. detail'i { url, mode, inner }'dir: mode"replace" ya da "morph"'tur, url ise put için null'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 bir GET'tir. Cevap güvenilir markup olarak eklenir. Bu yüzden url page'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 da data-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 replace ya da morph, 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 url ne de data-src olması, 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 bir Error ile reject olur, örneğin collage: 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 layout collage dev altında yine çalışır, çünkü orada policy yalnızca raporlar; production'da ise script'i yüklemeyi bırakır.
  • Script /_client/client.<hash>.js adresinde sunulur, immutable olarak bir yıl cache'lenir ve defer ile 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ı da put ile 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.Plugins içinde olmalıdır. Mount edilen dosya sistemlerini sarmalar ve bu işlem uygulama kurulurken yapılır.
  • Sıfır değerli Options HTML, JSON ve CSS'i minify eder; noHTML, noJSON ve noCSS bunlardan 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() ve NewWith(Config{…}) artık New(Options{…})'dur. "html": false, "json": false ve "css": false yerine "noHTML": true, "noJSON": true ve "noCSS": true yazılır; "html": true gibi 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ğin text/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 Range request'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.Plugins iç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 (width ve height'ı koruyan, temizlenmiş yorumlar) bir ziyaretçinin boyut belirtmesine izin verir: 2×2 bir görselde width="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) ve maxDiskBytes (1 GiB), v0.5.0'dan beri, tutulanı sınırlar. maxRecipes, plugin'in nasıl yapacağını bildiği görselleri, bellekte ve cacheDir içinde <name>.json olarak 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üzden maxRecipes'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() ve NewWith(Config{…}) artık New(Options{…})'dur. allowedOrigins, {scheme, host} nesneleri değil origin string'lerinden ("https://cms.example.com") oluşan bir listedir ve her biri collage.ParseOrigin ile denetlenir. fetchTimeout ve originMaxAge, "10s" gibi string'lerdir; çıplak bir sayı uygulamayı durdurur. Negatif bir boyut, piksel sayısı ya da kalite hatadır.
  • allowedOrigins boşsa ve Files da 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ılmadan staticFS'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 immutable değ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örsel public, max-age=<originMaxAge> ile sunulur. originMaxAge bir süredir, varsayılanı "24h"'tır ve en az bir saniye olmalıdır. Adı içeriğinin digest'ini taşıyan, sitenin kendi Files'ından bir görsel public, max-age=31536000, immutable değerini korur.
  • Yalnızca hem width hem de height değ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.webp gibi 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.
  • webp değeri false (varsayılan), true ya 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-image içinde tutulur (cacheDir). p.Purge() ve p.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.Plugins içinde olmalıdır: {{bundle}}'ı ekler.
  • minify ve sourcemap değeri "" (yazılmazsa; minify yalnı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ık true ya da false uygulamayı 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 üzerinden Host.OpenMounted ile okunur: development'ta diskten, build edildikten sonra binary'nin embed ettiği kopyadan. source ve svg başka bir dosyayı gösterir. / ile başlayan bir değer bir URL'dir ve aynı şekilde okunur. Diğer her path diskten ya da FS'ten okunur. SourceBytes ve SVGBytes byte'ları Go'da verir. Başlangıç page'inin key'i startURL'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: PersonaliseHook ile, her middleware'in içinde yeniden yazarlar. elagoht/health, compress'ten önce de sonra da listelenebilir.
  • En az minSize byte'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 bir Range request'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'ü private ya da no-store taşı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ılan false), Cache-Control'ü private ya da no-store taşı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 .br ve bir .gz yazar; noPrecompress bunu kapatır.
  • noCache (v0.2.0'dan beri) sıkıştırılmış body saklamaz. Negatif bir cacheBytes'ın yerini alır; negatif cacheBytes artı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
  }
}
  • cloudflare ile webhook'tan en az biri ve bir origin zorunludur: Config.BaseURL ya da bir origin resolver.
  • v0.3.0'da değişenler:baseURL kaldırıldı (Config.BaseURL'i ayarlayın); force artık inDevelopment'tır. cloudflare.apiToken ve webhook.token yerine, token'ı tutan ortam değişkeninin adını veren apiTokenEnv ve tokenEnv gelir (Go'dan APIToken ve Token değeri doğrudan alır). Süreler string'dir; negatif bir retries hatadır. Eski bir key uygulamayı başlangıçta durdurur.
  • Tam olarak bir invalidation'ın ulaştığı path'leriConfig.BaseURL altında purge eder ve her entry'yi, bir OriginResolver plugin'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 window boyunca toplanır, invalidate eden goroutine'in dışında gönderilir, bir 429 ya da 5xx gelirse yeniden denenir ve shutdown'da gönderilir. Bir development sunucusu, inDevelopment ayarlanmadı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.Plugins içinde olmalıdır: /sw.js'de sunulan worker'ı kuran {{offlineScript}}'i ekler.
  • v0.2.0'da değişenler:version artık buildID, inDev artık inDevelopment'tır. Negatif bir maxPages ya da maxAssets (her şeyi sakla) hatadır; onun yerine büyük bir sayı yazın. Bir assets prefix'i, sonunda / olsun olmasın, path segmentlerini bütün olarak kapsar.
  • Page'ler önce ağdan çekilir ve saklanır. assets altındaki static dosyalar stale-while-revalidate ile sunulur. Ne ulaşılabilen ne de saklanan bir page için fallback page'i gösterilir. no-store ya da private olarak 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-cache ile gider; basicauth da page'lerini private olarak 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 bunu Cache-Control: private ya da no-store ile 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'ın Host.BuildID'sidir, yani Config.Cache.Version ya da çalıştırılabilir dosyanın parmak izi.
  • Development'ta /sw.js, inDevelopment ayarlanmadıkça kendi kaydını siler. Static build sw.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, vercel ya da github-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.
  • netlify ve cloudflare için _headers ve _redirects, vercel için bir vercel.json yazılır. github-pages için her sabit redirect'e bir meta-refresh page'i ve bir .nojekyll yazı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-Type asla bir wildcard kurala girmez. Dosyanın uzantısından anlaşılan bir Content-Type ise 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, _redirects ya da vercel.json dosyası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 RedirectSource plugin'inden alır. Header'larını ise header yakalamasından alır. Bu yüzden build'i production modunda ve gerçek BaseURL ile 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 inProduction anahtarı 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-link ve diğerleri. Her biri varsayılan olarak error ya da warn seviyesindedir. rules bir kuralın seviyesini değiştirir ya da onu off ile kapatır. Plugin'in tanımadığı bir kural adı uygulamanın başlamasını engeller. htmlcheck.Rules() hepsini listeler.
  • ignoreLinks prefix'leri sondaki / olsun olmasın segment'lerin tamamını kapsar ve / ile başlamalıdır. Negatif bir titleMax, descriptionMax ya da pageBudget uygulamayı 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.ClientIP belirler; yani Server.TrustedProxies iç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, yani Server.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 position onu başka bir köşeye ya da üst veya alt kenarın ortasına koyar: top-left, top, top-right, bottom-right, bottom ya da bottom-left. Go'da devtoolbar.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.
  • DevMode olmadan 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-Type olmadan 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 /healthz ve /readyz varsayılan olarak atlanır. Bir skip prefix'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/../admin atlanmaz.
  • 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 bir elagoht/fail2ban'ın reddettiği bir ban, kendinden önce listelenen bir elagoht/health'in geri çevirdiği bir request, çıplak bir app.Handle mount'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çin 404'ü. Bu satırlarda bytes yoktur, response'larında da X-Request-ID yoktur. Eskisinden fazla satır bekleyin, banlı bir istemcinin 403'leri de aralarında. accesslog.RequestID çıplak bir app.Handle handler'ında da çalışır.
  • Satırın tamamı için onu Config.Plugins'te ilk sıraya koyun, elagoht/health ve elagoht/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 bir Host'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.Logger ile yazılır; bir 5xx, ERROR seviyesinde log'lanır.
  • Bir id'ye benzeyen X-Request-ID korunur, değilse yenisi üretilir. Id response'ta geri gönderilir ve accesslog.RequestID(ctx) ile okunur.
  • sample, 2xx response'ların bir kısmını log'lar, diğerlerinin hiçbirini atlamaz. İstemcinin adresi collage.ClientIP'dir; bir proxy'nin arkasındaysanız onu Server.TrustedProxies'e yazın. trustProxy ve trustedProxies anahtarları kaldırıldı, X-Real-IP hiç 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: true header'ı 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ın Metrics'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/a ve /blog/b ikisi de page:post, /robots.txtdocument:robots, bir mount mount:/static/, bir 404 ise other olur. Böylece path uyduran bir crawler yeni time series üretemez. routes seç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: tokenEnv onu tutan ortam değişkeninin adını verir ya da Options.Token onu Go'dan ayarlar; bir token anahtarı 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 olarak collage.http, collage.render ve collage.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 bir RequestHook iç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.http onun, render ve her fragment de collage.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'in 404'ü) bir route adlandırmaz: span'i adı olarak metodu korur ve yalnızca collage.route.kind=rejected taşı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.traceparent herkesin gönderebileceği bir iddiadır: herkesten sürdürülürse internetteki bir istemcinin, bir ParentBased sampler'ı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 istemcinin traceparent'ını olduğu gibi iletir; proxy trace'i başlatmıyorsa traceparent, tracestate ve baggage'ı proxy'de silin ya da "never" ayarlayın.
  • v0.4.0'dan beri metot da sınırlıdır: RFC 9110'unkiler ve PATCH dışındaki bir metot http.request.method'da _OTHER'dır, gönderildiği hali http.request.method_original'dadır ve span'in adında HTTP yazar (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.
  • skip prefix'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ında https olur.

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'nin websiteID'si, Google Analytics'in measurementID'si.
  • Plausible, Umami ve GoatCounter ziyaretleri cookie olmadan sayar. Google Analytics 4 cookie ayarlar; onu requireConsent ile kullanın.
  • respectDNT ya da requireConsent ile 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. requireConsent ile de page window.collageAnalyticsConsent() çağırana kadar hiçbir şey yüklenmez.
  • exclude, snippet almayan page'leri adlandırır.
  • Sitede elagoht/consent varsa requireConsent yerine consentCategory ayarlayın (örneğin "analytics"). Plugin'in yazdığı her tag, ziyaretçi o kategoriyi kabul edince consent plugin'inin çalıştırdığı bir type="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, requireConsent ile birlikte kullanılamaz: ikisi birden verilirse ya da ad küçük harf, rakam ve tire dışında bir şey içerirse uygulama başlamaz. respectDNT yine 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
  }
}
  • tenants ya da bir Resolve fonksiyonu (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-After ile 503 alır ve bu cache'lenmez. Bir tenant ttl boyunca, v0.3.0'dan beri "tenant yok" cevabı da unknownTTL boyunca 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. bypass host'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 bir Host gönderen bir istemci önceden her biri için bir Resolve çağrısı yaptırırdı. Bütçe bitince, cevabı tutulmayan bir host, bütçe dolana kadar Resolve çağrılmadan Retry-After ile 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: onu tenants altı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'in StaticParams'ı, 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, cdnpurge ve robots host'u izler: yazdıkları URL'ler tenant'ın origin'idir.
  • acme.localhostcollage dev ile çalışır. Static build'in host'u yoktur; tenant'sız render eder ve tenant-no-host uyarı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 da bypass'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 bir DSN ya da DSNEnv gerekir: yoksa başlangıç başarısız olur. Bunun tek istisnası inDevelopment verilmemiş 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ızca sendPath ile), değerleri [filtered] olan query anahtarları ve altı request header'ı; sendPath verilmedikçe Referer yalnızca origin'ine indirilir; URL'nin scheme'i collage.IsHTTPS'i izler. Cookie'ler, Authorization, body ve client adresi hiçbir zaman gönderilmez (adres yalnızca sendIP ile, collage.ClientIP'nin verdiği hâliyle). Bir kullanıcı, ancak User callback'inizin döndürdüğü kadarıyla gönderilir.
  • Mesaj, hatalı kodun yazdığı gibi gönderilir ve bir sır taşıyabilir. BeforeSend ile temizleyin; o event'i düzenleyebilir ya da false dönerek düşürebilir.
  • minStatus (500) neyin raporlanacağını belirler; panic'ler her zaman raporlanır. sampleRate, perMinute (60) ve queueSize (100) hacmi sınırlar: aşan event'ler düşürülür ve sayılır, yeniden denenmez; bir 429 gönderimi duraklatır.
  • Kaydettiğiniz plugin üzerindeki Capture(ctx, err), bir arka plan işi gibi request dışında oluşan bir hatayı raporlar. inDevelopment verilmedikç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": 2 anahtarı adlandırarak uygulamayı durdurur; "2s" yazın.
  • /healthz (livePath), process bir request'e cevap verdiği sürece 200 ok döner ve hiçbir check çalıştırmaz. /readyz (readyPath) 200 ok döner; bir check başarısız olduğu sürece 503 unavailable, bir drain başladıktan sonra ise 503 draining döner. İkisi de GET ve HEAD'e Cache-Control: no-store ile 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 /healthz document'ına hiç ulaşılmaz. Onu silin ya da livePath'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 biri checkTimeout (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. details ile readiness, her check'i ok ya da failing olarak 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 draining olur 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 hemen Retry-After: 1 ile 503 overloaded cevabı 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 404 ile 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ğinde bytes olmadan, önce listelendiğinde eksiksiz. Probe'lar accesslog'un varsayılan skip'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 j gibi bir değişkende tutun: collage plugin addjobs.New(jobs.Options{})'u doğrudan listeye yazar, orada kimse onun üzerinde Every ç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 disabled ile değil, ortama bakarak jobs.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 her d sü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 * 1 ayın 1'inde ve her pazartesi çalışır. Hatalı yazılmış ya da hiçbir zaman eşleşemeyecek bir ifade Cron'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 scratch bir image'da bu yoktur. main içinde import _ "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], T tipindeki 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. OnFailure son hatayla bir kez çağrılır. Enqueue hiçbir zaman bloklamaz: dolu bir queue'da ErrQueueFull, yalnızca plugin'in Shutdown'ı başladıktan sonra ise ErrDraining dö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 ise abandoned olarak loglanır. Onunla bir durdurma DrainDelay + ShutdownTimeout + 1s kadar 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. Kendi http.Server'ını çalıştıran bir uygulama plugin'i j.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.App olmadan startup başarısız olur. plugins argüman alabilir: collage plugin add ve del listesini 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 yerine gesso.NewRemote(url, nil) ile çağrılır, lifecycle'ını kendi Run'ı 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 503 döner, problem kodu unavailable: 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. OnShutdown hook'ları API hiç başlamadığında da (bir build'den sonra) çalışır; böylece kapattıkları bir veritabanı kapanmış olur.
  • collagetest ile 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), PathNamed ile StaticParams'ın yazdığı n path parametresini okur; v0.1'de parametrenin adını alırdı. paginate.Version kaldı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.
  • New Redis'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öylece GET ile 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 BuildFinishedHook plugin'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.Handle mount'unun etrafında değil. v0.67.0'dan beri uygulamanın app.Handle ile 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 kendi Host.Handle endpoint'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ızca ListenAndServe çağırır: bir static export, bir plugin komutu ve app.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.