Referans21 dk okuma

Config

collage.Config ve alt struct'larının her alanı, varsayılan değerleri ve validation'ın neleri kontrol ettiği.

Bir uygulamanın config'i tek bir collage.Config değeridir ve bu değer collage.New'a verilir. Her alanın kullanılabilir bir sıfır değeri vardır. Bu yüzden bir config'e yalnızca varsayılanlardan farklı olanları yazarsınız:

app, err := collage.New(&collage.Config{
	Template: collage.TemplateConfig{Root: "templates"},
})

New bu değerle sırasıyla üç şey yapar:

  1. Varsayılanları doldurur. Varsayılanı olan ve sıfır değerde duran her alanı ayarlar. Verdiğiniz değeri yerinde değiştirdiği için uygulamanın tam olarak hangi değerlerle kurulduğunu sonradan okuyabilirsiniz.
  2. Validation yapar. Sonucu kontrol eder ve bulduğu ilk sorunu hata olarak döner. Ayrıntılar için Validation bölümüne bakın.
  3. Uygulamayı kurar. Var olmayan bir template root'u, parse edilemeyen bir template ya da bir plugin'in Configure metodunun başarısız olması bu adımda bildirilir. Bu hataların hiçbiri ilk request'e kadar beklemez.

nil verirseniz bir hata alırsınız. nil bir config varsayılanları istemek anlamına gelmez, bir hatadır. Çünkü template'lerinizin nerede olduğunu config söyler.

Scaffold edilmiş bir proje config'ini main.go'daki newApp'te kurar. Sizin makinenizle bir sunucu arasında değişen şeyler ortamdan gelir; geri kalanı orada yazılıdır:

Scaffold edilmiş main.go, collage.Config'in her alanını nereden alır. Ortamdan: DevMode COLLAGE_DEV=1'den, BaseURL BASE_URL'den, Server.Host HOST'tan, Server.Port varsayılanı PORT ya da 6060 olan -port flag'inden, Security.CSRFKey COLLAGE_CSRF_KEY'den. main.go'da ve yanındaki dosyalarda: PluginConfig plugins-config.json'dan, Plugins plugins.go'daki plugins()'ten, Template embed edilmiş templates dizininden, Cache ise .cache altında varsayılan TTL'i beş dakika olan bir disk cache. Atanmayan ve varsayılanında kalanlar: Locale (yalnızca en), Logger, DevWatch, TrailingSlash ve Observability. Değerin tamamı collage.New'a gider; New varsayılanları doldurur, validation yapar ve uygulamayı kurar.scaffold'un main.go'sundacollage.Config alanıortamdan okunurCOLLAGE_DEV=1DevModeBASE_URLBaseURLHOSTServer.Host-port, PORT ya da 6060Server.PortCOLLAGE_CSRF_KEYSecurity.CSRFKeymain.go'da ve yanındaki dosyalardaplugins-config.jsonPluginConfigplugins.go'da plugins()Pluginsembed edilen templates/Templatedisk, .cache, 5mCacheatanmaz: her biri varsayılanında kalırLocale (yalnızca en), Logger, DevWatch,TrailingSlash, Observabilitycollage.Newvarsayılanlar, validation, kurulum
Scaffold edilmiş main.go, collage.Config'in her alanını nereden alır. Development modu, public origin, sunucunun dinlediği adres ve forgery key'i ortamdan gelir; böylece tek bir binary hem sizin makinenizde hem bir sunucuda çalışır. Port'un -port flag'inin varsayılanı PORT, o da yoksa 6060'tır. Plugin'ler, config'leri, embed edilmiş template'ler ve disk cache main.go'da ve yanındaki dosyalarda yazılıdır. Locale, Logger, DevWatch, TrailingSlash ve Observability atanmaz, bu yüzden her biri varsayılanında kalır. collage.New değerin tamamını alır.

Alanlar ve varsayılanları aşağıdaki tablolardadır. Eksiksiz bir config scaffold'un kodunu, Örnek: development ve production için tek bir config ise production'daki bir uygulamanın ona ne eklediğini gösterir.

Config

AlanTipVarsayılanAnlamı
DevModeboolfalseFramework genelinde development modu.
DevWatch[]stringyokDeğiştiğinde development'taki page'i yeniden yükleyen ek dizinler.
Logger*slog.Loggerbaşlangıçta seçilirFramework'ün ve plugin'lerin log yazdığı logger.
ServerServerConfigHTTP sunucusu.
BaseURLstringyokSitenin public origin'i, https://example.com; bir render'ın başka türlü bilemeyeceği mutlak URL'ler için.
SecuritySecurityConfigRequest forgery koruması.
TemplateTemplateConfigTemplate'lerin yüklenmesi ve render edilmesi.
CacheCacheConfigPage cache.
LocaleLocaleConfigURL'lerin hangi locale'leri taşıdığı.
TrailingSlashboolfalseHer page'in URL'si / ile biter.
ObservabilityObservabilityConfigMetric'ler ve tracing.
Plugins[]PluginyokUygulama kurulurken register edilen plugin'ler.
PluginConfigmap[string]json.RawMessageyokHer plugin'in kendi config'i, plugin adına göre key'lenmiş.

DevMode

Development modunu açar. Bu modda:

  • template'ler her render'dan önce diskten yeniden yüklenir;
  • page'ler tarayıcıda kendilerini yeniler;
  • başarısız fragment'ler page'in üzerinde gösterilir;
  • page cache'ten hiç okunmaz ve disk cache'in yerini memory alır;
  • DevWatch'ta adı geçen dizinler izlenir;
  • built-in error page hatanın hangi fragment'te başladığını söyler, hatanın sebebiyle başlar (template kaynaklı bir hatada başarısız olan çağrının dosyası, satırı ve sütunu) ve hata zincirinin tamamını gösterir.

Production'da kapalı olmalıdır. Bu tanı bilgileri dosya yollarını, host adlarını ve hata mesajlarında ne varsa hepsini içerir.

Tek şalter DevMode'dur; development modunu başka hiçbir şey açmaz. Bir plugin onu host.DevMode() ile okur. Scaffold edilmiş bir proje bu alanı COLLAGE_DEV=1'e göre ayarlar. collage dev bu değişkeni sizin yerinize set eder.

DevWatch

Template'ler ve mount'lar dışında, değiştiğinde development'taki page'i yeniden yükleyen dizinlerdir. Uygulamanızın diskten kendisinin okuduğu Markdown ya da JSON gibi içerikler için kullanılır.

app, err := collage.New(&collage.Config{
	DevMode:  os.Getenv("COLLAGE_DEV") == "1",
	DevWatch: []string{"content"},
	// ...
})

Var olmayan bir dizin hata sayılmaz, atlanır. Çünkü aynı config, binary nerede başlatılırsa orada çalışır. Development dışında bu alan dikkate alınmaz. Bir dizini izlemek yalnızca tarayıcıyı yeniler. Yeni içeriği başlangıçta yüklenmiş bir kopyadan değil de bir sonraki render'da okumak sizin kodunuzun işidir.

Logger

Varsayılan değer olan nil, seçimi framework'e bırakır ve framework uygulamayı kurarken seçer:

  • Terminalde, ve yalnızca slog'un varsayılan handler'ını hiçbir şey değiştirmemişse, insanların okuması için tasarlanmış kompakt bir handler kullanılır. Bu handler her kaydı tek satırda ve renkli bir level işaretiyle yazar.
  • Diğer bütün ortamlardaslog.Default() olduğu gibi kullanılır. İstisnası, NO_COLOR ayarlı değilken FORCE_COLOR'ın ayarlı olmasıdır: collage dev renkli bir terminalde çalıştırdığı program için bunu ayarlar.

slog.SetDefault'u çağırmış bir uygulama kendi handler'ını korur. Sonuçtan emin olmak istiyorsanız bir logger verin, örneğin makinelerin okuyacağı loglar için bir JSON handler. New bu alanı nil bırakır.

Plugins ve PluginConfig

Plugins içindeki plugin'ler, New çalışırken sırayla register edilir. Template'ler parse edilmeden önce devreye girmesi gereken bir plugin, örneğin template fonksiyonu ekleyen ya da mount'ları saran bir plugin, app.RegisterPlugin ile değil bu alanla verilmelidir.

PluginConfig her plugin'in bölümünü ham JSON olarak tutar. Framework hiçbir dosya okumaz. Bu alanı istediğiniz gibi doldurabilir ya da collage.LoadPluginConfig("plugins-config.json")'u kullanabilirsiniz. Bu fonksiyon dosya yoksa nil döner. Scaffold edilmiş bir newApp'in çağırdığı Env.PluginConfig'i de kullanabilirsiniz: çalışma dizininde dosya varsa onu, yoksa binary'ye embed edilmiş kopyayı okur. Register edilmiş hiçbir plugin'in adına karşılık gelmeyen bir key, uygulamanın başlamasını ErrUnknownPluginConfig ile engeller; bir bölümün içinde plugin'in tanımadığı bir key de aynısını yapar. Ayrıntılar için Plugin'leri yapılandırmak bölümüne bakın.

TrailingSlash

Her page'in tek bir adresi vardır. TrailingSlash bu adresin / ile bitip bitmeyeceğini belirler. Açıksa page /blog/hello/ adresindedir ve /blog/hello oraya 301 ile redirect edilir. Varsayılan olan kapalı durumda bunun tersi geçerlidir. İsimle üretilen link'ler (pageURL, pageURLIn, localeURL, app.URL) seçilen yazımla çıkar. Bir locale'in ana sayfası da buna dahildir: açıkken /tr/, kapalıyken /tr.

Static bir host'a export ettiğiniz bir sitede bu ayarı açın. Export bir page'i <path>/index.html olarak yazar. Host bu dosyayı /blog/hello/ adresinden sunar, /blog/hello adresinden ise ancak bir redirect ile ulaşılır. Bu yüzden ayar kapalıyken her canonical link, her sitemap girdisi ve her iç link bir redirect'e işaret eder.

Bu ayar yalnızca page'lere uygulanır. Bir document bir dosyadır ve path'ini yazıldığı gibi korur, yani iki durumda da /sitemap.xml olarak kalır. Bir action ise her zaman sonda slash olmadan yazılır. Yine de her birinin tek bir adresi vardır: /sitemap.xml/ oraya 301 ile redirect edilir, /login/ adresine yapılan bir POST ise 308 ile; böylece body yeniden gönderilir.

ServerConfig

AlanTipVarsayılanAnlamı
Hoststring"localhost"Sunucunun dinlediği adres.
Portint6060TCP port'u, 1–65535.
ReadTimeouttime.Duration15sBir request'i okumanın en fazla ne kadar sürebileceği.
ReadHeaderTimeouttime.Duration0Yalnızca request header'larını okumanın en fazla ne kadar sürebileceği. Sıfır, ReadTimeout'u kullanır.
WriteTimeouttime.Duration30sBir response'u yazmanın en fazla ne kadar sürebileceği.
IdleTimeouttime.Duration60sBir keep-alive bağlantısının en fazla ne kadar boşta bekleyebileceği.
ShutdownTimeouttime.Duration10sGraceful shutdown'ın devam eden request'leri ne kadar beklediği.
DrainDelaytime.Duration0Bir shutdown başladıktan sonra, port kapanmadan önce sunucunun keep-alive'lar kapalı olarak ne kadar daha hizmet verdiği; development'ta yok sayılır. Bkz. Deployment.
MaxBodyBytesint644 MiBRequest'in yönlendirildiği action kendi sınırını koymadığında request body'sine uygulanan sınır. Middleware'den önce uygulanır.
TrustedProxies[]stringyokSunucunun önündeki proxy'lerin adresleri ve CIDR aralıkları; bunların X-Forwarded-For'una inanılır. Liste set edilmişse X-Forwarded-Proto'suna da inanılır.

Host'un varsayılanı localhost'tur ve bu adrese makinenin dışından erişilemez. Container içinde bu alanı 0.0.0.0 yapın.

Scaffold edilen bir proje Host ve Port'u HOST ve PORT ortam değişkenlerinden doldurur. collage dev altında bu değişkenler, collage dev'in seçtiği bir loopback adresidir; sizin adresinizde ise collage dev'in kendisi dinler. Bu yüzden onları ortamdan okumaya devam edin. Bkz. CLI.

MaxBodyBytes'ı New doldurmaz. Sıfır, request geldiğinde uygulanan yerleşik 4 MiB (4 << 20 byte) demektir. Negatif bir değer ise sınır olmadığı anlamına gelir. Sınırsız bir body, boyutunu anonim bir çağıranın belirlediği bir bellek kullanımıdır. Bu yüzden bunu bilerek seçin. Bir action kendi sınırını WithMaxBodyBytes ile koyabilir. Ayrıntılar için Form'lar ve action'lar sayfasına bakın.

TrustedProxies, bir reverse proxy'nin arkasında istemcinin adresini bilmeyi sağlayan alandır; orada her request'in RemoteAddr'i proxy'ninkidir. Her girdi bir adres ya da CIDR aralığıdır ("10.0.0.0/8", "127.0.0.1"). İkisinden de olmayan bir girdi collage.New'ı, girdiyi adıyla anarak başarısız kılar. Boşken, yani varsayılanda, X-Forwarded-For hiç okunmaz; bu yüzden istemci onu taklit edemez ve collage.ClientIP(r), RemoteAddr'in host'udur:

Server: collage.ServerConfig{
	TrustedProxies: []string{"10.0.0.0/8", "127.0.0.1"},
},

Güvenilen bir proxy'den gelen request, istemcisini X-Forwarded-For'da bildirir ve header sağdan okunur: güvenilen proxy olmayan ilk adres istemcidir. Adreslerin hepsine güveniliyorsa en soldaki adres istemcidir.

  • Bir girdi port (9.9.9.9:4567, [2001:db8::1]:443) ya da köşeli parantez ([2001:db8::1]) taşıyabilir.
  • Güvenilmeyen bir adresten önce gelen ve adres olmayan bir girdi (unknown) istemciyi bilinmez kılar: ClientIP sıfır değerli netip.Addr olur, hiçbir zaman proxy'nin adresi olmaz.

Bir CDN'in yayımladığı aralıklar dahil her hop'u listeye yazın. Yalnızca kendi işlettiğiniz proxy'leri ya da platformunuzun belgelediği aralıkları yazın. İstemcinin request gönderebildiği bir aralığa güvenmek, o istemcinin istediği adresi kendine vermesine izin vermektir. Sıfır bitlik bir aralık (0.0.0.0/0, ::/0) herkese güvenir ve collage.New bunun için bir Warn log'lar.

Forgery cookie'sinin kimden gelen bir X-Forwarded-Proto ile Secure olarak işaretleneceğine de aynı liste karar verir. Liste boşken bu header'a herkesten inanılır; bu, yalnızca bir proxy'nin ulaşabildiği bir sunucu için doğrudur. Bkz. Deployment.

SecurityConfig

AlanTipVarsayılanAnlamı
CSRFKey[]byteher process için üretilirForgery token'larını imzalayan key. Production'da ayarlayın.
CSRFCookieNamestring"collage_csrf"Token'ı taşıyan cookie.
CSRFFieldNamestring"_csrf"Token'ın gönderildiği form alanı.
CSRFHeaderNamestring"X-CSRF-Token"Token'ın alternatif olarak gönderilebileceği header.
CSRFTrustedOrigins[]stringyokForm'ları buraya post edebilecek diğer origin'ler. Her biri scheme://host[:port] biçimindedir.
DisableCSRFboolfalseForgery kontrolünü bütün uygulama için kapatır.
CSRFTokenTTLtime.Duration12hBir forgery token'ının üretildikten sonra ne kadar geçerli kaldığı. Sıfır varsayılan demektir; negatif bir değer, token'ı imzası doğrulandığı sürece geçerli tutar.
FrameOptionsstring"SAMEORIGIN"Her response'ta gönderilen X-Frame-Options; "-" hiçbirini göndermez, başka her değer olduğu gibi gönderilir.
DisableNoSniffboolfalseHer response'ta gönderilen X-Content-Type-Options: nosniff header'ını durdurur.

Production'da CSRFKey'i ayarlayın. Key en az 32 byte rastgele veri olmalı, diğer secret'larınızla birlikte saklanmalı ve her instance'ta aynı olmalıdır.

Boş bırakılırsa her process için yeni bir key üretilir. Bu ilk çalıştırma için yeterlidir ama deploy için yanlıştır. Çünkü üretilen key her process'te farklıdır: restart'tan önce üretilmiş bir token restart'tan sonra, bir instance'ın ürettiği token da bir sonrakinde reddedilir. Böylece bir restart'ı aşan ya da bir filonun başka bir instance'ına giden form gönderimi başarısız olur. Uygulama key ürettiğini log'lar. Development dışında bu bir uyarı, development'ta ise info seviyesinde bir kayıttır. Bu log yalnızca unsafe bir method'a (POST, PUT, PATCH, DELETE) cevap veren ve WithoutCSRF ile muaf tutulmamış bir action varsa yazılır. Çünkü token'ı yalnızca böyle bir action doğrular.

Key disk cache'in namespace'ine dahil değildir, bu yüzden cache yeni bir key'e rağmen korunur. İçinde form olan ve eski key ile saklanmış cache'lenmiş bir page ise sunulmaz, yeniden render edilir. Ayrıntılar için Caching sayfasına bakın. Scaffold edilmiş main.go key'i COLLAGE_CSRF_KEY'den okur. openssl rand -hex 32 ile bir key üretebilirsiniz.

CSRFTrustedOrigins, bu origin dışında form'ları buraya post edebilecek origin'leri belirtir. Diğer her origin, geçerli bir token taşısa bile reddedilir. Ayrıntılar için Form'lar ve action'lar sayfasına bakın.

Yukarıdaki isim varsayılanlarını ve CSRFTokenTTL'in 12h'ini New değil forgery guard uygular. Bu yüzden bu alanlar Config'inizde boş kalır. CSRFFieldName alanın adını iki tarafta birden değiştirir. {{csrfToken}} kontrolün okuduğu adı yazdığı için form'larınızda değişiklik gerekmez. Ancak token'ı form'dan okuyan script'lerin (input[name="_csrf"]) yeni adı kullanması gerekir.

CSRFTokenTTL, her token'a imzalanmış üretilme zamanına göre kontrol edilir: bu yaşı geçmiş bir token reddedilir ve bir sonraki form için yenisi üretilir.

DisableCSRF, tarayıcıdan gönderilen hiçbir form'u olmayan uygulamalar içindir, örneğin kendi authentication'ının arkasında duran bir API. Bu ayar açıkken {{csrfToken}}, gönderilmesi anlamsız olacak bir form'u render etmek yerine render'ı başarısız kılar. Yalnızca tek bir action'ı muaf tutmak istiyorsanız o action'da WithoutCSRF kullanın.

TemplateConfig

AlanTipVarsayılanAnlamı
FSfs.FSnilTemplate'lerin yüklendiği dosya sistemi. nil disk demektir.
Rootstringdiskte "./templates"Template'lerin yüklendiği dizin. Her template adının başından çıkarılır.
Extensionstring".html"Template dosyalarının uzantısı.
Funcstemplate.FuncMapyokBuilt-in fonksiyonların üzerine eklenen ek template fonksiyonları.
Timeouttime.Duration5sData handler'ların varsayılan timeout'u; kendi timeout'unu koymayan her document handler'ın da varsayılanı.

FS ve Root

FSnil ise Root diskte, çalışma dizinine göre bir path'tir ve varsayılanı ./templates'tir. FS ayarlıysa Root onun içinde slash ile ayrılmış bir dizindir ve varsayılan değer almaz. Boş bir Root, FS'in kendi kökü demektir.

Bir binary'nin herhangi bir dizinden çalışabilmesini sağlayan şey embed etmektir:

//go:embed all:templates
var templates embed.FS

app, err := collage.New(&collage.Config{
	Template: collage.TemplateConfig{FS: templates, Root: "templates"},
})

Development'ta embed edilmiş bir template seti değişemez. Bu yüzden collage, diskteki dizin varsa onu tercih eder. Var olmayan bir Root için NewErrTemplateRootMissing döner. Altındaki bir template bir symlink üzerinden dışarıya çözümleniyorsa ErrTemplateEscapesRoot döner.

Funcs

Bu fonksiyonlar template'ler parse edilirken built-in fonksiyonlara eklenir. Built-in bir fonksiyonla aynı adı taşıyan bir kayıt o built-in fonksiyonun yerini alır. Bir plugin'in eklediği bir adı taşıyan kayıt da plugin'in fonksiyonunun yerini alır (AddTemplateFunc ya da AddRenderFunc ile eklenmiş olsun); New bu adların her birini bir kez log'lar. Bu alan New'dan önce ayarlanmalıdır. Çünkü bir template yalnızca parse edildiği anda var olan bir fonksiyonu çağırabilir. Bilinmeyen bir adı çağıran template New'da hata verir. Her render'a bağlanan fonksiyonlar (slot, hoist, asset, stylesheet, csrfToken, pageURL, pageURLIn, localeURL, actionURL, fragmentURL, fragmentURLIn, withQuery) her render'da yeniden bağlanır. Bu yüzden onları override etmenin hiçbir etkisi olmaz; New, verilen her birini adıyla anan bir uyarı log'lar. Ayrıntılar için Template fonksiyonları sayfasına bakın.

Timeout

Fragment'i WithTimeout ile kendi süresini koymamış bir data handler'ın deadline'ıdır. DocumentBuilder.WithTimeout ile kendi süresini koymamış her document handler'ın da deadline'ıdır. Bu yüzden yavaş bir feed kendi bütçesini orada yükseltir; bunu her fragment ve document için bu değeri yükselterek yapmaz. collage'daki bütün timeout'lar gibi bu da handler'a verilen context'i sınırlar. ctx.Done()'ı hiç kontrol etmeyen bir handler bu süreyi aşabilir.

CacheConfig

AlanTipVarsayılanAnlamı
EnabledboolfalsePage cache'in ana şalteri.
StoreCachenilKendi cache implementasyonunuz.
TypeCacheTypeaçıksa CacheMemoryStorenil olduğunda kullanılan built-in cache: collage.CacheMemory ya da collage.CacheDisk.
DefaultTTLtime.Duration5mBuilt-in bir store'un, sıfır ya da daha küçük bir TTL ile yazılan bir entry'ye verdiği ömür.
MaxEntriesint10000Cache entry sayısının ve tek bir tag altında izlenen key sayısının üst sınırı; memory ve disk için de geçerli. Negatif değer sınırsız entry demektir.
MaxBytesint64memory için 256 MiB, disk için 1 GiBBuilt-in bir cache'in sakladığı toplam boyutun üst sınırı. Negatif değer sınırsız demektir. Bir disk cache'in memory katmanı 256 MiB tutar, MaxBytes bundan küçükse de MaxBytes kadar tutar.
DirstringyokDisk cache'in entry'leri, Dir/data/ altında ise collage.Cached değerlerini sakladığı yer. CacheDisk için zorunludur. Her instance'ın kendi dizini olmalıdır: bir dizini paylaşan instance'lar bir cache'i paylaşmaz.
Versionstringbinary'den türetilirDisk cache'teki entry'lerin hangi build'e ait olduğunu belirler.
WarmLimitint1000Tek bir invalidation'ın arka planda yeniden render ettiği page sayısının üst sınırı; en yeniler önce gelir. Negatif değer warming'i kapatır.

Caching varsayılan olarak kapalıdır.Enabled false iken bir Store ayarlı olsa bile hiçbir şey cache'lenmez. Type'ın varsayılanı yalnızca Enabled true ve Storenil olduğunda collage.CacheMemory olur. Tipsiz bir literal, Type: "disk", yine derlenir; bir değişkenden okunan string'in ise dönüştürülmesi gerekir: Type: collage.CacheType(v).

DefaultTTL built-in bir store'un yedeğidir, bir page'in ömrü değildir. Memory ve disk cache'ler onu sıfır ya da daha küçük bir TTL ile yazılan bir entry'ye verir; negatif bir değeri New reddeder. Bir page ya da document ona hiç ulaşmaz: Incremental(ttl) ve document'taki karşılığı pozitif olmayan bir TTL'i reddeder, static bir page ise invalidate edilene kadar saklanır. Yani framework'ün yazdığı her entry kendi TTL'ini taşır. Kendi Store'unuza bu değer verilmez; o, TTL'i sıfır olan bir Set'e kendi varsayılanını uygular. collage.Cached kendi TTL'ini alır ve orada sıfır, değerin hiç expire olmaması demektir.

Bir Store, validation dahil Type'ın yerini tamamen alır. Page'leri Redis'e ya da başka bir yere koymak için collage.Cache'i (Get, Set, InvalidateKey, Clear) implement edin. collage.TaggedCache'i (SetTagged, Invalidate) de implement eden bir store'a her entry yazılırken o entry'nin tag'leri de verilir ve tag'e göre invalidate etmesi istenir. Ayrıca collage.StaleCache'i (GetStale, MarkStaleKey, MarkStale) implement eden bir store'dan, invalidate edilen entry'leri silmek yerine stale olarak işaretlemesi istenir. Böyle bir store başarısız bir yeniden render'a eski page'le cevap verebilir. Bkz. Caching. collage.SharedCache'i implement eden bir store, örneğin collage-redis, bir filo tarafından paylaşılır: page'ler ve collage.Cached verisi onda tutulur ve herhangi bir instance'taki invalidation hepsine ulaşır. Bkz. Caching. Somut bir tipin nil pointer'ını atamak yerine alanı boş bırakın. Böyle bir pointer nil olmayan bir interface'tir ve ilk lookup'ta panic'e yol açar.

Disk cache process'ten uzun yaşar. Entry'leri Dir altında, adı Version'ın hash'i olan bir alt dizinde durur. Böylece yeni bir build farklı bir dizini okur ve stale hiçbir şey bulmaz. Version'ı boş bırakırsanız değeri çalışan executable'ın hash'i olur. Bu hash tam da çıktının değişebileceği durumlarda değişir. Page'lerin nasıl görüneceğini binary dışındaki bir şey belirliyorsa Version'ı kendiniz ayarlayın, örneğin bir commit ya da release tag'i ile. Executable'ın hash'i alınamazsa bir uyarıyla birlikte memory cache kullanılır. Dizin oluşturulamadığında da (örneğin salt okunur bir dosya sisteminde) aynısı olur: collage.New başarısız olmak yerine bir uyarı verir ve memory ile devam eder. Uygulama çalışırken başarısız olan bir yazma log'lanır ve page cache'lenmeden sunulur. Development'ta disk cache hiç kullanılmaz, onun yerine bir memory cache devreye girer.

Disk cache'in önünde memory vardır. Bir hit, memory katmanından sunulur. Bu katmanı MaxEntries ve 256 MiB (MaxBytes bundan küçükse MaxBytes) sınırlar. Katman açılışta geçerli build'in dizininden, en yenilerden başlanarak doldurulur. Böylece bir restart son page'lerini hemen memory'den sunar. Her instance'ın kendi katmanı vardır, bu yüzden her instance'a kendi Dir'ini verin. Paylaşılan bir dizinde, bir instance'taki invalidation'dan sonra diğerleri kendi memory'lerindeki kopyayı taze diye sunmaya devam eder. Bkz. Caching.

Dir/data/, disk cache'in collage.Cached değerlerini tutar. Böylece uygulama restart'tan sonra boş bir data cache'le başlamaz. Entry'lerin aksine bu değerler build'in alt dizininde durmaz ve şifrelenmez. Bkz. Caching.

MaxEntries, collage.Cached'in request'ler arasında tuttuğu değerleri de sınırlar.

MaxBytes, built-in bir cache'in ne kadar yer kapladığını sınırlar: sıfır, tipin varsayılanını seçer. Sınırın tamamından büyük bir page sunulur ama saklanmaz. Kendi Store'unuz bunu yok sayar. Bkz. Caching.

MaxEntries framework'ün dependency tracker'ını da sınırlar. Bu tracker, her process'te bir tag'i cache key'lerine eşleyen bir index'tir. Store ne olursa olsun, kendi Store'unuz dahil, hem tag başına hem de toplamda sınırlanır. Negatif bir MaxEntries iki sınırı da 10000'de tutar.

Her farklı query string ayrı bir key'dir. Cache bir entry'yi evict ettiğinde ya da entry'nin süresi dolduğunda key tracker'dan silinmez. Bu yüzden bir üst sınır olmasa bir client bu index'i sınırsızca büyütebilirdi. Bir tag sınıra ulaştığında, yeni bir key kaydedilirken o tag'in en eski key'i düşürülür ve o key'in cache entry'si de onunla birlikte silinir: tracker'ın bıraktığı bir key, InvalidateTags'in artık ulaşamayacağı bir key'dir, bu yüzden stale olarak sunulmak üzere cache'te bırakılmaz. Page, cache onu evict etmiş gibi bir sonraki request'te yeniden render edilir. Bkz. Caching.

MaxEntries ve MaxBytes'ta sıfır varsayılan değer demektir. Sınırsız anlamına gelen tek değer negatif bir değerdir. Ayrıntılar için Caching sayfasına bakın.

LocaleConfig

AlanTipVarsayılanAnlamı
Defaultstring"en"Locale prefix'i olmayan bir URL'nin locale'i.
Supported[]string[Default]Uygulamanın sunduğu bütün locale'ler.
PrefixDefaultboolfalseDefault'un page'leri de prefix alır: /en/about.

Locale'i seçen tek şey URL'dir. /aboutDefault locale'indedir, /tr/hakkinda ise "tr" locale'indedir. collage locale'i hiçbir zaman Accept-Language'ten ya da bir cookie'den seçmez. Çünkü farklı okuyuculara farklı şey ifade eden bir URL'yi cache'ler, crawler'lar ve paylaşılan link'ler hep yanlış ele alır.

Varsayılan locale'in kendi prefix'i olan /en/about, /about'a kalıcı olarak redirect edilir. PrefixDefault ayarlıysa durum tersine döner: adres /en/about olur ve /about oraya redirect edilir. Ayrıntılar için Link'ler ve locale'ler sayfasına bakın.

Dili kendiniz belirlemek istiyorsanız bunu middleware'de yapın. Türkçe bir tarayıcıyı /tr'ye redirect edebilirsiniz. Ya da tek bir URL'yi her dil için ayrı render edip bunu collage.Vary ile bildirebilirsiniz. Ayrıntılar için Link'ler ve locale'ler sayfasına bakın.

ObservabilityConfig

AlanTipVarsayılanAnlamı
MetricsMetricsno-opCounter'ları ve süre ölçümlerini alır.
TracerTracerno-opRequest'lerin, render'ların ve fragment'lerin etrafında span başlatır.

İkisi de collage'ı kendi backend'inize bağlamak için implement ettiğiniz interface'lerdir. nil no-op demektir. Metrics, Tracer ve Span v1 boyunca yeni method kazanmaz: framework'ün ileride raporladığı bir sinyal ayrı, opsiyonel bir interface olarak gelir ve type assertion ile bulunur. Bir implementasyona collage.NoopMetrics, NoopTracer ve NoopSpan'i embed edin ve yalnızca ihtiyaç duyduğu method'ları tanımlayın; ne eklenirse eklensin derlenmeye devam eder.

type Metrics interface {
	RenderDuration(ctx context.Context, page string, d time.Duration, cacheHit bool)
	FragmentDuration(ctx context.Context, page, fragment string, d time.Duration, err error)
	CacheEvent(ctx context.Context, event collage.CacheEvent, key string)
	HTTPResponse(ctx context.Context, status int, path string, d time.Duration)
	Invalidation(ctx context.Context, tags []string, keys int)
}

type Tracer interface {
	StartSpan(ctx context.Context, name string) (context.Context, collage.Span)
}

type Span interface {
	SetAttribute(key, value string)
	RecordError(err error)
	End()
}

Yalnızca response'ları sayan, başka hiçbir şeyle ilgilenmeyen bir metrics köprüsü:

type responseCounter struct {
	collage.NoopMetrics
	responses atomic.Int64
}

func (m *responseCounter) HTTPResponse(ctx context.Context, status int, path string, d time.Duration) {
	m.responses.Add(1)
}

CacheEvent şu değerlerden biridir: collage.CacheHit, CacheMiss, CacheSet, CacheEvict, CacheInvalidate, CacheCoalesced, CacheStale ve CacheWarm. CacheCoalesced, bir request'in aynı key için zaten çalışmakta olan bir render tarafından karşılandığı anlamına gelir. CacheStale ise bir collage.Cached değerinin ya da cache'lenmiş bir page'in stale olarak sunulduğu anlamına gelir. Sunulan her değer ya da response için bir kez sayılır. CacheWarm ise bir invalidation'ın ulaştığı bir page ya da document'ın arka planda yeniden render edilip saklandığı anlamına gelir. Her key için bir kez sayılır.

HTTPResponse'un path'i request'in path'idir ve onu client seçer; bunun yerine sınırlı olan collage.RouteInfo(ctx) ile etiketleyin. Path normalleştirmesinin reddettiği bir request için de (kirli bir path'in redirect'i, hiçbir route'un eşleşemeyeceği bir path) boş bir path ile ve RouteInfo türü "rejected", adı "normalise" olarak çağrılır. collage.http span'i http.method'u gruplayarak kaydeder: standart metotlar kendileri olarak, başka her şey OTHER olarak. Bkz. Path'ler önce temizlenir.

Validation

New, varsayılanları doldurduktan sonra aşağıdaki durumlardan bulduğu ilkini döner:

KoşulHata
Server.Port1–65535 aralığının dışındaErrInvalidPort
Cache.Enabled açık, Store yok ve Type ne CacheMemory ne CacheDiskErrInvalidCacheType
Cache.Enabled açık, Store yok, TypeCacheDisk ve Cache.Dir boşErrEmptyCacheDir
Locale.Default, Locale.Supported içinde yokErrLocaleDefaultNotSupported
Server.ReadTimeout, ReadHeaderTimeout, WriteTimeout, IdleTimeout, ShutdownTimeout, DrainDelay, Template.Timeout ya da Cache.DefaultTTL negatifErrNegativeDuration
BaseURL set edilmiş ve yalın bir scheme://host[:port] değilErrInvalidOrigin

Negatif süre hatası sekiz alanın hepsi için tek bir sentinel error'dır. Mesaj, hataya yol açan alanın adını verir, örneğin server.read_timeout. Varsayılanlar önce uygulandığı için New üzerinden gelen sıfır bir port ya da boş bir varsayılan locale validation'a hiç ulaşmaz. Yalnızca açıkça set ettiğiniz bir değer hataya yol açabilir. Bu hataları errors.Is ile karşılaştırın. Tam liste Hatalar sayfasındadır.

Varsayılanları doldurmak ve validation ayrı ayrı export edilmez. İkisinin çalıştığı tek yer New'dur, bu yüzden bir test bir config'i onu çağırarak kontrol eder:

_, err := collage.New(&collage.Config{Server: collage.ServerConfig{Port: 70000}})
// errors.Is(err, collage.ErrInvalidPort)

Varsayılanları doldurmak idempotent'tir. Varsayılanları zaten taşıyan bir config olduğu gibi kalır.

Eksiksiz bir config

Aşağıdaki, scaffold edilmiş bir projenin başladığı config'dir. Ortama göre değişen kısımlar ortam değişkenlerinden okunur:

pluginConfig, err := env.PluginConfig(files)
if err != nil {
	return nil, err
}

app, err := collage.New(&collage.Config{
	DevMode: env.Dev,
	BaseURL: os.Getenv("BASE_URL"),
	Server:  collage.ServerConfig{Host: env.Host, Port: env.Port},
	Template: collage.TemplateConfig{
		FS:        files,
		Root:      "templates",
		Extension: ".html",
	},
	Cache: collage.CacheConfig{
		Enabled:    true,
		Type:       collage.CacheDisk,
		Dir:        env.CacheDir,
		DefaultTTL: 5 * time.Minute,
	},
	PluginConfig: pluginConfig,
	Plugins:      plugins(),
	Security: collage.SecurityConfig{
		CSRFKey: []byte(os.Getenv("COLLAGE_CSRF_KEY")),
	},
})

env, collage.Main'in scaffold edilmiş newApp'e verdiği collage.Env'dir: Dev, COLLAGE_DEV=1 demektir; Host, HOST ya da localhost'tur; Port, -port, PORT ya da 6060'tır; CacheDir ise .cache'tir. files projenin embed edilmiş dosya sistemidir, development build'inde ise proje dizininin kendisidir. plugins() ise collage plugin add ve del komutlarının yönettiği plugins.go'dan gelir. collage.Main, newApp çalışmadan önce .env'i yükler, böylece os.Getenv onu görür; bkz. CLI.

Örnek: development ve production için tek bir config

Ekibin iş listesi (her üye giriş yapar, admin ekibin her görevini, member ise yalnızca kendi görevlerini değiştirebilir) bir geliştiricinin makinesinde collage dev altında, production'da ise bir load balancer'ın arkasındaki iki sunucuda çalışır. Page'leri İngilizce ve Türkçedir. Ekibin kendi subdomain'indeki admin paneli de buraya form post eder.

İki ortama da tek bir binary hizmet verir. Bu binary'nin newApp fonksiyonu scaffold'unkiyle aynıdır, yalnızca production ayarları eklenmiştir. İki ortam arasında farklı olan her şey ya ortamdan okunur ya da env.Dev'e göre belirlenir:

func newApp(env collage.Env) (*collage.App, error) {
	pluginConfig, err := env.PluginConfig(files)
	if err != nil {
		return nil, err
	}

	cfg := &collage.Config{
		DevMode: env.Dev,
		BaseURL: os.Getenv("BASE_URL"), // collage dev's own address unless the environment file sets it
		Server: collage.ServerConfig{
			Host:              env.Host,
			Port:              env.Port,
			ReadHeaderTimeout: 5 * time.Second,
			DrainDelay:        5 * time.Second, // ignored in development
		},
		Template: collage.TemplateConfig{
			FS:        files,
			Root:      "templates",
			Extension: ".html",
		},
		Cache: collage.CacheConfig{
			Enabled:    true,
			Type:       collage.CacheDisk,
			Dir:        env.CacheDir,
			DefaultTTL: 5 * time.Minute,
		},
		Locale: collage.LocaleConfig{
			Default:   "en",
			Supported: []string{"en", "tr"},
		},
		PluginConfig: pluginConfig,
		Plugins:      plugins(),
		Security: collage.SecurityConfig{
			// Empty in development: a key is generated per process.
			CSRFKey: []byte(os.Getenv("COLLAGE_CSRF_KEY")),
		},
	}

	if !env.Dev {
		// The load balancer in front of both servers, and the admin
		// panel whose forms post here.
		cfg.Server.TrustedProxies = []string{"10.0.1.10"}
		cfg.Security.CSRFTrustedOrigins = []string{"https://admin.tasks.example.com"}
	}

	app, err := collage.New(cfg)
	if err != nil {
		return nil, err
	}
	// Routes and the static mount as scaffolded.
	return app, nil
}

Her ayarın iki ortamdaki değeri ve bunun nedeni şöyledir:

AyarDevelopmentProductionNeden
DevModeaçık: collage dev, COLLAGE_DEV=1 set ederkapalı: değişken set edilmezDevelopment'ın error page'leri dosya yollarını ve hata zincirlerini taşır. Bir development sunucusu ayrıca yalnızca Host'u bu makineyi adlandıran request'lere cevap verir; bkz. Deployment.
Server.Host, Server.Portcollage dev'in seçtiği loopback adresiHOST ve PORT, ya da -portSizin adresinizde collage dev'in kendisi dinler ve request'leri iletir; bkz. CLI.
BaseURLenvironment dosyası BASE_URL'i set etmedikçe collage dev'in kendi adresi, http://localhost:6060BASE_URL'den https://tasks.example.comBoş olması hata değildir: hiç mutlak URL üretmeyen bir site için gerekmez. Set edilmişse yalın bir origin olmalıdır, yoksa NewErrInvalidOrigin ile başarısız olur.
Security.CSRFKeyboş: her process'e bir key, info seviyesinde log'lanıren az 32 byte rastgele veri, iki sunucuda da aynıÜretilmiş bir key, bir restart'tan önce ya da diğer sunucunun ürettiği her token'ı reddeder.
Security.CSRFTrustedOriginsyokadmin panelinin origin'iDiğer her origin, geçerli bir token taşısa bile reddedilir.
Server.TrustedProxiesyokload balancerBu olmadan her istemcinin adresi load balancer'ınkidir.
Server.DrainDelay5s, yok sayılır5sLoad balancer, port kapanmadan önce trafik göndermeyi bırakır.
Server.ReadHeaderTimeout5s5sHeader'ları byte byte gönderen bir istemci erkenden düşürülür; bir body ise yine ReadTimeout'un tamamını kullanır.
Cacheaynı satırlar: yerine memory geçer, hiç okunmaz.cache altında bir disk cache, her sunucuda bir taneDevelopment az önce düzenlediğiniz template'i gösterir. Bir disk cache restart'tan sonra sıcak açılır.
Localeen, tren, trLocale'i URL seçer, bu yüzden binary'nin nerede çalıştığına bağlı hiçbir yanı yoktur.
WriteTimeout, Template.Timeoutvarsayılanlar, 30s ve 5svarsayılanlar, 30s ve 5sTemplate.Timeout'u WriteTimeout'un epey altında tutmak, yavaş bir upstream'i page'in yarısında kapanan bir bağlantı yerine bir fragment'in fallback'ine çevirir; bkz. Deployment.

Development tarafında hiçbir şey yazmanız gerekmez: collage dev, COLLAGE_DEV, HOST ve PORT'u set eder. Go kodu değiştiğinde collage dev'in yaptığı restart'larda bir form açık kalsın istiyorsanız development'a environment dosyasında (.env'de, ya da tutuyorsanız .env.development'ta) kendine ait bir key verin. Bu key hiçbir zaman production'daki key olmamalıdır; bkz. CLI.

Production tarafı, binary'nin çalıştığı yerde set edilen dört değişkendir: HOST, PORT, BASE_URL ve COLLAGE_CSRF_KEY. Bunlara bir plugin'in KeyEnv ile adlandırdığı değişkenler eklenir. Bunlar binary'nin çalışma dizinindeki bir .env dosyasında da set edilebilir. Bu dosyayı collage.Main yükler, sunucunun kendi değişkenleri ise dosyadakileri ezer; bkz. Deployment.