Site kurmak11 dk okuma
Static asset'ler
Stylesheet'leri, script'leri, görselleri ve indirilecek dosyaları bir dizinden ya da gömülü bir dosya sisteminden, bir yıl cache'lenebilen URL'lerle sunmak.
Stylesheet'ler, script'ler, görseller, font'lar ve indirilecek dosyalar bir asset mount tarafından sunulur. Asset mount, bir URL prefix'i altında sunulan bir dosya sistemidir ve içindekileri dosya olarak sunar.
root, err := os.OpenRoot("static")
if err != nil {
log.Fatal(err)
}
if err := app.Mount("/static/", root.FS()); err != nil {
log.Fatal(err)
}
app.Mount herhangi bir fs.FS kabul eder. Böylece önemli olan iki kaynağın ikisi de kapsanır: diskteki bir dizin ve binary'nin içine derlenmiş bir embed.FS. Artık static/app.css dosyası /static/app.css adresinden sunulur.
Mount'lar page değildir. Page cache'e hiç girmezler, tag almazlar ve InvalidateTags onlara ulaşmaz. Page'lere göre boyutlandırılmış bir cache'e 50 MB'lık bir video girseydi, binlerce page'i dışarı iterdi. Bu yüzden dosyalar dosya olarak sunulur.
os.DirFS değil, os.OpenRoot kullanın
Bir dizini sunmanın akla gelen ilk yolu os.DirFS gibi görünür, ama internete açık bir sunucu için yanlış yoldur. Kendi dokümantasyonu, symlink traversal'ı engellemediğini söyler. Dizinin içinde olup dışını gösteren bir symlink takip edilir ve gösterdiği şey her neyse sunulur.
os.OpenRoot ise bu sınırı işletim sistemi düzeyinde uygular. Açtığı her path, tuttuğu dizinin içinde çözümlenir. Dizinin dışına çıkan bir symlink ise hiç açılamaz. os.OpenRoot, Go 1.24'ten beri vardır.
collage bu açığı sizin yerinize kapatamaz. collage'a bir fs.FS verilir ve collage onun üzerinde Open'ı çağırır. Dosya sisteminin kendi dizini içinde kalıp kalmaması, dosya sisteminin bir özelliğidir.
collage'ın yaptığı şey şudur: Open çağrılmadan önce URL'deki path'i path.Clean ile temizler:
- Mount'un içinde kalan bir
..ya da.normalize edilir ve dosya sunulur; örneğin/static/css/../app.css,/static/app.cssolarak ele alınır. - Mount'un dışına çıkan bir path ya da boş bir elemanla başlayan bir path (
/static//…) ise404ile reddedilir.
Bu kontrol URL'ye yazılmış bir traversal'ı durdurur, ama diskteki symlink'lerle kurulmuş bir traversal'ı durdurmaz.
*os.Root'u process boyunca açık tutun, çünkü onun dosya sistemi her request'i sunar.
Embed etmek
Bir embed.FS içinde symlink yoktur, dolayısıyla yapısı gereği güvenlidir. Ayrıca binary'nin herhangi bir çalışma dizininden çalışabilmesini sağlar. Dizin adını çıkarmak için fs.Sub kullanın. Aksi hâlde stylesheet /static/static/app.css adresinden sunulur:
//go:embed all:static
var staticFS embed.FS
func mountAssets(app *collage.App) error {
static, err := fs.Sub(staticFS, "static")
if err != nil {
return err
}
return app.Mount("/static/", static)
}
Development'ta ise diskteki dizini kullanmak istersiniz. Gömülü kopya binary build edildiği anda sabitlenmiştir, bu yüzden bir dosyayı düzenlemek hiçbir şeyi değiştirmez. Bu seçimi Env.Static yapar. Scaffold edilmiş bir projenin newApp'i de onun döndürdüğünü mount eder:
return app, app.Mount("/static/", env.Static(files, "static"))
Env.Dev açıkken diskteki dizini os.OpenRoot ile açar. Değilse embed edilmiş kopya olan fs.Sub(files, "static")'i döner.
collage bu seçimi template'ler için kendisi yapar, çünkü Template.Root template'lerin diskte nerede olduğunu ona söyler. Bir mount'a ise yalnızca bir fs.FS verilir. Dosyalarının nereden geldiğini yalnızca sizin kodunuz bilir.
Content-addressed URL'ler
Mount edilmiş bir dosyaya link verirken path'ini elle yazmayın, asset kullanın:
<link rel="stylesheet" href="{{asset "/static/app.css"}}">
<script src="{{asset "/static/app.js"}}" defer></script>
Page'e yazılan şey, içinde dosya içeriğinin hash'i bulunan bir dosya adıdır:
<link rel="stylesheet" href="/static/app.0d5f2b53aebf6c72.css">
Bu URL şu header ile sunulur:
Cache-Control: public, max-age=31536000, immutable
Bu header bir yıl anlamına gelir ve dosyanın hiç değişmeyeceğine dair bir söz verir.
Söz dürüsttür, çünkü ad byte'lardan türetilir. Dosya değiştiğinde ad da değişir, page'ler yeni ada link verir ve eski URL bir daha hiç istenmez. Tarayıcılar ve CDN'ler dosyayı bir yıl boyunca tutar ve hiç revalidate etmez. Kimseye de page ile uyuşmayan bir stylesheet sunulmaz.
Düz bir ad ise hangi süreyle olursa olsun bu şekilde cache'lenemez. Er ya da geç birine bugünün HTML'iyle birlikte dünün stylesheet'ini verir.
Üç ayrıntı:
- Var olmayan bir dosya URL üretmez, hata üretir.
{{asset "/static/typo.css"}}, fragment'icollage.ErrUnknownAssetile başarısız kılar. Aksi hâlde page "başarıyla" render edilir, ama 404 dönen bir stylesheet'e link verir. Mount'un sunmayacağı bir ad da hatadır: bir dotfile ya da mount içinde geçerli bir path olmayan bir ad. Dosya adının her segment'i escape edilir; örneğin100%.css,100%25.cssolarak link verilir. - Request'teki hash kontrol edilir. Hash'i dosyanın güncel hash'iyle eşleşmeyen bir URL, dosyayı değil 404 döner. O dosyayı sunmak, shared cache'in arkasındaki herkese bir yıl boyunca yanlış bir cevabı sabitlemek olurdu.
- Düz adlar da çalışır.
/static/app.cssde sunulur, ama mount'un kendi, daha kısaCache-Controldeğeriyle. URL'nin sabit kalması gereken yerlerde bunu kullanın. Site dışından referans verilen bir favicon ya da bir e-postadan link verilen bir dosya buna örnektir.
{{asset}}'in link verdiği hash'li ad bir yıl boyunca, immutable ile sunulur. Düz ad, mount'un kendi Cache-Control değeriyle sunulur; WithCacheControl başka bir değer vermedikçe bu public, max-age=3600'dür. Dosyanın güncel hash'i olmayan bir hash ya da var olmayan bir dosya, no-store ile düz metin bir 404'tür. DevMode açıkken hash her request'te yeniden hesaplanır ve hiçbir şey cache'lenebilir değildir.Go'dan
URL'ye ihtiyaç duyan bir data handler, örneğin bir Open Graph görseli ya da bir preload hint'i için, URL'yi render context'ten ister:
cover, err := rc.Asset("/static/covers/" + post.Slug + ".jpg")
if err != nil {
return postView{}, nil, err
}
rc.HoistProperty("og:image", siteOrigin+cover)
rc.Asset, {{asset}}'in render ettiği değerin aynısını döndürür. Hiçbir mount'un sunmadığı bir path için collage.ErrUnknownAsset döndürür. Bir document'ın handler'ında da çalışır; örneğin bir web manifest'indeki ikon URL'si için. Stylesheet'ler için rc.HoistStylesheet ve {{stylesheet}}, lookup'ı ve <link>'i tek adımda yapar. Ayrıntılar için Head ve SEO sayfasına bakın.
Seçenekler
err := app.Mount("/media/", media.FS(),
collage.WithCacheControl("public, max-age=86400"),
collage.WithoutBuildCopy(),
)
| Seçenek | Etkisi |
|---|---|
collage.WithCacheControl(value) | Düz adlarıyla istenen dosyalar için Cache-Control değeri. Varsayılanı public, max-age=3600 |
collage.WithoutBuildCopy() | Static export bu mount'u çıktısına kopyalamaz |
collage.WithAttachments() | Bir .html, .xhtml, .svg ya da .xml dosyası Content-Disposition: attachment ile sunulur; böylece tarayıcı onu çalıştırmak yerine kaydeder. Upload'ların mount'u içindir |
WithCacheControl yalnızca düz adları etkiler. Content-addressed URL'ler her zaman bir yıl ve immutable ile sunulur, çünkü adları bunu hak eder. Düz bir adın ne kadar süre tutulabileceği, o adın altındaki dosyanın ne sıklıkla değiştiğine bağlıdır. Bunu yalnızca siz bilirsiniz, bu yüzden ayarlamak da size kalır.
WithoutBuildCopy, production'da başka bir yerden (örneğin bir CDN'den) sunulan ya da her build'e kopyalanamayacak kadar büyük olan bir mount içindir.
Upload'ların mount'u WithAttachments() ister
Bir mount dosyayı adının söylediği gibi sunar: up.htmltext/html, up.svg ise image/svg+xml olur ve bunlar sitenizin origin'inde, script'leri cookie'lerinizle çalışacak biçimde sunulur. İçeriğin hiçbir zaman HTML'e sniff edilmemesi kuralı yalnızca uzantısı olmayan dosyayı kapsar. Okuyucuların yüklediklerinin mount'u bu yüzden WithAttachments() kullanır: .html, .xhtml, .svg ya da .xml dosyasını Content-Disposition: attachment ile sunar, böylece tarayıcı onu çalıştırmak yerine indirir. Ya da hangi uzantıların saklanabileceğini kendiniz denetlersiniz. İkisi de otomatik değildir: kendi yazdığınız bir dizinin düz mount'unun bunun bedelini ödemesi için bir neden yoktur.
Bir dosya response'u neleri içerir
Bir mount, http.FileServer üzerine değil, fs.Open ve Go'nun http.ServeContent'i üzerine kurulmuş ince bir katmandır:
| Method'lar | GET ve HEAD. Diğer her method Allow: GET, HEAD ile birlikte 405 alır |
Content-Type | Dosya uzantısından belirlenir. Adı bir tip belirtmeyen dosya ilk 512 byte'ından sniff edilir, ama hiçbir zaman çalıştırılabilen bir tipe dönüşmez: HTML ya da XML'e benzeyen bir dosya text/plain olur. Her zaman X-Content-Type-Options: nosniff ile gider |
ETag | Dosya içeriğinin strong hash'idir. İlk request'te hesaplanır ve hatırlanır; bir dosya için eşzamanlı ilk request'ler tek bir hash'i paylaşır |
Range | If-Range ve 206 Partial Content ile desteklenir |
| Dizinler | Hiçbir zaman listelenmez. Bir dizin ya da yalnızca prefix 404 döner |
index.html | Hiçbir zaman örtük olarak sunulmaz |
| Dotfile'lar | Hiçbir zaman sunulmaz ve export tarafından da kopyalanmaz. Bir elemanı . ile başlayan path (.env, .git/, bir editörün swap dosyası) 404 döner. Tek istisna .well-known'dur. Mount.URL böyle bir dosyaya link üretmeyi reddeder |
| Sondaki slash | /static/app.css/ 404 döner, dosya değil |
| Olmayan bir dosya | Düz metin bir 404, no-store ile döner. Sizin HTML not-found page'iniz asla dönmez |
Range request'leri, tarayıcının bir ses ya da video dosyasında dosyayı baştan indirmeden ileri sarabilmesini ya da bir indirmeye kaldığı yerden devam edebilmesini sağlar. Bu destek http.ServeContent'ten gelir. Dosyaların document'lardan ayrı bir mekanizma olmasının nedeni de budur, çünkü document'ların body'si bellekte bir bütün olarak üretilir.
ETag bir içerik hash'idir. Bunun nedeni, bir Go programında asset'lerin en yaygın kaynağı olan embed.FS'in her dosya için sıfır modification time bildirmesidir. Bu yüzden Last-Modified ve boyut ile tarihe dayalı validation onun için hiç çalışmaz. Dosyanın kendisi değil, yalnızca hash'i hatırlanır. Bu yüzden harcanan bellek dosyaların boyutuyla değil, sayısıyla artar.
Olmayan bir stylesheet için sitenizin not-found page'i yerine düz metin bir 404 dönmesi bilinçli bir tercihtir. CSS isteyen bir tarayıcıya HTML bir error page vermek, hangi taraftan bakılırsa bakılsın bir hatadır.
Prefix'ler ve route'lar
Bir prefix / ile başlamalı ve / ile bitmelidir. Prefix tek başına / olamaz, çünkü kökteki bir mount bütün page'leri yutardı (collage.ErrInvalidPrefix). Nil bir dosya sistemi collage.ErrNilFS hatasını verir.
Bir mount'un prefix'i altına düşen bir request'e mount cevap verir ve request router'a hiç ulaşmaz. Bu güvenlidir, çünkü uygulama başlarken bir page'in, document'ın ya da redirect'in zaten cevap verdiği bir URL'yi gölgeleyecek bir prefix reddedilir. Locale prefix'li URL'ler de buna dahildir. Örneğin Türkçe page'leri olan bir sitede /tr/ altındaki bir mount başarısız olur (collage.ErrMountShadowsRoute). Prefix'leri çakışan iki mount da reddedilir (collage.ErrMountConflict). İki kontrol de register aşaması kapandığında çalışır. Bu yüzden Mount ve RegisterPage'i hangi sırayla çağırdığınızın bir önemi yoktur.
Bu kontrol prefix'leri register edilmiş pattern'lerle karşılaştırır. Bu yüzden prefix'in üst seviyesindeki bir catch-all'u göremez. Örneğin /{rest...} adresindeki bir page /static/… ile de eşleşirdi, ama bu URL'leri mount alır. Bir prefix'i sahiplenmenin bedeli budur.
Development'ta
Content-addressed bir URL ile düzenlemekte olduğunuz bir dosya birbiriyle çelişir. Development dışında hash bir kez hesaplanır ve hatırlanır, URL için de bir yıllık söz verilir. Process çalışırken dosyayı düzenlerseniz page eski ada link vermeye devam eder. Oysa tarayıcıya o adın hiç değişmeyeceği söylenmiştir.
Bu yüzden DevMode açıkken her mount, bir dosyanın hash'ini her request'te yeniden hesaplar ve her şeyi no-store ile sunar. Düzenlenen bir dosya yeni bir URL alır, page bu URL'ye link verir ve tarayıcı dosyayı yeniden çeker. Ayrıca development'taki reload script'i, mount edilmiş bir dosya değiştiğinde page'i yeniler. (Handler'larınızın okuduğu Markdown dosyaları gibi mount edilmemiş bir dizin, Config.DevWatch içinde belirtildiğinde page'i yeniler.)
Development dışında ise diskte değişen bir dosya, process yeniden başlatılana kadar hatırlanan hash'ini korur. Mount'lar, çalışan bir sunucunun altında düzenlenen dosyalar için değil, deploy edilen dosyalar içindir.
Static export
Static export, her mount'u kendi prefix'i altında çıktıya kopyalar. Örneğin /static/app.css, dist/static/app.css olur. Buna ek olarak, bir page'in {{asset}} ile gerçekten link verdiği her dosyanın content-addressed bir kopyasını da çıktıya ekler. Yalnızca bu dosyaların kopyası eklenir. Böylece bir medya dizini, hiçbir page'in kullanmadığı adlar için ikiye katlanmaz. collage.WithoutBuildCopy() bir mount'u bu kopyalamanın dışında bırakır.
Örnek: bir blogun stylesheet'i, script'i ve görselleri
Template'ler sayfasındaki blogun sunacağı üç tür dosya vardır:
| Dosya | Nereden link verilir | Ne zaman değişir |
|---|---|---|
static/app.css | Layout'tan, her page'de | Bir yeniden tasarımla |
static/app.js | Layout'tan, her page'de | Nadiren |
static/img/harbour.jpg | Bir yazının template'inden | Yayımlandıktan sonra hiçbir zaman |
Mount etmek
Dosyalar embed edilir, böylece binary herhangi bir dizinden çalışır. collage dev ise bunun yerine diskteki dizini sunar. env.Static, Embed etmek bölümündeki seçimdir:
//go:embed all:static
var staticFS embed.FS
func main() {
collage.Main(newApp)
}
func newApp(env collage.Env) (*collage.App, error) {
app, err := collage.New(&collage.Config{
DevMode: env.Dev,
Template: collage.TemplateConfig{Root: "templates"},
})
if err != nil {
return nil, err
}
// register pages
return app, app.Mount("/static/", env.Static(staticFS, "static"))
}
Link vermek
Layout stylesheet'e ve script'e, yazı da kendi görseline link verir. Her biri düz path'iyle yazılır:
<link rel="stylesheet" href="{{asset "/static/app.css"}}">
<script src="{{asset "/static/app.js"}}" defer></script>
<img src="{{asset "/static/img/harbour.jpg"}}" alt="The harbour at dawn">
Okurun tarayıcısına ulaşan HTML'de her dosyanın hash'i bulunur:
<link rel="stylesheet" href="/static/app.b988912693d9423d.css">
<script src="/static/app.dc18125931ff948b.js" defer></script>
<img src="/static/img/harbour.9e00fefaa8d22370.jpg" alt="The harbour at dawn">
Tarayıcı ardından bu adları ister ve mount şöyle cevap verir:
| Request | Status | Cache-Control |
|---|---|---|
/static/app.b988912693d9423d.css | 200 | public, max-age=31536000, immutable |
/static/app.css | 200 | public, max-age=3600 |
/static/app.0000000000000000.css | 404, düz metin | no-store |
POST /static/app.css | 405, Allow: GET, HEAD | no-store |
collage dev altında da aynı adlara link verilir ve aynı adlar sunulur, ama her 200no-store ile gider.
Değişen bir stylesheet'i deploy etmek
Bir yeniden tasarım static/app.css'i değiştirir ve yeni byte'ları gömülü yeni bir binary deploy edilir. Ardından:
- Yeni process'in render ettiği ilk page yeni dosyanın hash'ini hesaplar ve
/static/app.0a044e6f01a45071.cssadresine link verir. - Okurun tarayıcısı bu adı hiç görmemiştir. Stylesheet'i bir kez çeker ve bir yıl boyunca tutar.
- Eski
app.b988912693d9423d.csso tarayıcının cache'inde kullanılmadan kalır, çünkü artık hiçbir page ona link vermez. - Eski ad istendiğinde yeni process
404,no-storeile cevap verir. Artık elinde olmayan eski byte'ları sunmaz. Yeni byte'ları da onları tarif etmeyen bir adın altında sunmaz.
Hiçbir şeyin purge edilmesi gerekmedi ve hiçbir okura yeni HTML eski stylesheet'le birlikte gösterilmedi.
Bu güvence düz adda biter. Deploy'dan kısa süre önce /static/app.css'i çekmiş bir okura, çektiği andan itibaren bir saat dolana kadar eski kopyası verilebilir. Page'lerin {{asset}} ile link vermesinin ve düz adın sizin kontrolünüz dışındaki URL'ler için ayrılmasının nedeni budur.
Hiçbir mount'un sunmadığı bir path
Yazının template'inde bir yazım hatası:
<img src="{{asset "/static/img/hrabour.jpg"}}" alt="The harbour at dawn">
Böyle bir dosya yoktur, bu yüzden {{asset}} yazı fragment'ini collage.ErrUnknownAsset ile başarısız kılar. Log, fragment'i, template'in satırını ve path'i gösterir. Okurun ne alacağını fragment'in failure policy'si belirler:
- Yazı
Required()olduğu için page başarısız olur: bir500ve error page döner, kırık görselli bir yazı asla dönmez. - Opsiyonel bir fragment'te, örneğin bir sidebar'da, page o fragment olmadan sunulur,
200döner,no-storeile gider ve cache'lenmez. Hata bir warning olarak log'lanır.
Her iki durumda da hata, okurun network panelinde bir 404 olarak değil, ona ulaşan ilk render'da görünür. Bu render genellikle development'taki sizin render'ınızdır.
Bir request ise başka bir konudur. /static/ altında hiçbir dosyayı adlandırmayan bir URL, mount'tan düz metin bir 404 alır. Hiçbir mount'un prefix'i altına düşmeyen bir URL ise hiçbir mount'a ulaşmaz: ona router, sitenin kendi not-found page'iyle cevap verir.
Mount'ların yapmadıkları
- Sıkıştırma yapmazlar. Gzip ya da Brotli yoktur, önceden sıkıştırılmış sidecar dosyalar da desteklenmez. Önüne bir reverse proxy ya da CDN koyun,
app.Handler()'ı wrap edin ya da elagoht/compress'i register edin. - Bundling, minification ya da görsel işleme yapmazlar. Bir mount kendisine verilen byte'ları olduğu gibi sunar. Daha fazlası için plugin'ler kullanılabilir: elagoht/bundle script'leri ve stylesheet'leri esbuild ile bundle eder, elagoht/minimizer bir mount'un sunduklarını minify eder, elagoht/opti-image görselleri yeniden boyutlandırır, elagoht/favicon bir sitenin ikonlarını tek bir görselden üretir, elagoht/offline ise page'leri ve static dosyaları ağ olmadan okumak için saklar.
- Yalnızca
fs.FSkaynaklarıyla çalışırlar. S3 gibi bir object store birfs.FSdeğildir. Onuapp.Handleile kendiniz sunun ya da doğrudan ona link verin.