Konfiguracja HTTP
*****************

.[perex]
Przegląd opcji konfiguracyjnych dla Nette HTTP.

Jeśli nie używasz całego frameworku, tylko tej biblioteki, przeczytaj, [jak wczytać konfigurację|bootstrap:].


Nagłówki HTTP
=============

```neon
http:
	# nagłówki wysyłane z każdą odpowiedzią
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# wpływa na nagłówek X-Frame-Options
	frames: ...      # (string|bool|null) domyślnie 'SAMEORIGIN'
```

Ze względów bezpieczeństwa framework wysyła nagłówek `X-Frame-Options: SAMEORIGIN`, który mówi, że stronę można wyświetlić wewnątrz innej strony (w elemencie `<iframe>`) tylko wtedy, gdy znajduje się w tej samej domenie. W pewnych sytuacjach może to być niepożądane (na przykład gdy tworzysz aplikację dla Facebooka), więc zachowanie można zmienić, ustawiając `frames: http://allowed-host.com`, żeby dopuścić konkretny host, `frames: true`, żeby dopuścić osadzanie skądkolwiek (nagłówek zostaje pominięty), albo `frames: false`, żeby całkowicie tego zabronić (`X-Frame-Options: DENY`).

Domyślnie Nette wysyła też nagłówki `X-Powered-By: Nette Framework 3` i `Content-Type: text/html; charset=utf-8`. Dowolny nagłówek, także te domyślne, możesz usunąć, ustawiając jego wartość na pusty ciąg.


Content Security Policy
-----------------------

Nagłówki `Content-Security-Policy` (CSP) da się łatwo skonfigurować; ich opis znajdziesz w [specyfikacji CSP |https://content-security-policy.com]. Dyrektywy CSP (jak `script-src`) można zapisać albo jako ciągi zgodne ze specyfikacją, albo jako tablice wartości dla lepszej czytelności. Wtedy nie trzeba używać cudzysłowów wokół słów kluczowych jak `'self'`. Nette wygeneruje też automatycznie wartość `nonce`, więc w nagłówku wyśle się coś w rodzaju `'nonce-y4PopTLM=='`.

```neon
http:
	# Content Security Policy
	csp:
		# ciąg zgodny ze specyfikacją CSP
		default-src: "'self' https://example.com"

		# tablica wartości
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool w przypadku przełączników
		upgrade-insecure-requests: true
		block-all-mixed-content: false
```

W szablonach używaj `<script n:nonce>...</script>`, a wartość nonce zostanie uzupełniona automatycznie. Tworzenie bezpiecznych stron w Nette jest naprawdę łatwe.

Podobnie można skonfigurować nagłówki `Content-Security-Policy-Report-Only` (których można używać równolegle z CSP) oraz [Feature Policy|https://developers.google.com/web/updates/2018/06/feature-policy]:

```neon
http:
	# Content Security Policy Report-Only
	cspReportOnly:
		default-src: self
		report-uri: 'https://my-report-uri-endpoint'

	# Feature Policy
	featurePolicy:
		unsized-media: none
		geolocation:
			- self
			- https://example.com
```


Cookie HTTP
-----------

Możesz zmienić domyślne wartości niektórych parametrów metody [Nette\Http\Response::setCookie() |response#setCookie()] i obsługi sesji.

```neon
http:
	# zasięg cookie według ścieżki
	cookiePath: ...          # (string) domyślnie '/'

	# domeny, które mogą przyjąć cookie
	cookieDomain: 'example.com'  # (string|domain) domyślnie nieustawione

	# wysyłać cookies tylko przez HTTPS?
	cookieSecure: ...        # (bool|auto) domyślnie auto

	# wyłącza wysyłanie cookie, którego Nette używa do ochrony przed CSRF
	disableNetteCookie: ...  # (bool) domyślnie false
```

Atrybut `cookieDomain` określa, które domeny (origins) mogą przyjmować cookies. Jeśli nie zostanie podany, cookie przyjmuje ta sama (sub)domena, która je ustawiła, *z wyłączeniem* jej subdomen. Jeśli `cookieDomain` zostanie podany, subdomeny również są objęte. Podanie `cookieDomain` jest więc mniej restrykcyjne niż jego pominięcie.

Na przykład jeśli ustawione jest `cookieDomain: nette.org`, cookies są dostępne również we wszystkich subdomenach, jak `doc.nette.org`. To samo osiągniesz też wartością specjalną `domain`, czyli `cookieDomain: domain`.

Domyślna wartość `auto` dla atrybutu `cookieSecure` oznacza, że jeśli witryna działa na HTTPS, cookies będą wysyłane z flagą `Secure` i tym samym będą dostępne tylko przez HTTPS.


Proxy HTTP
----------

Jeśli witryna działa za proxy HTTP, podaj adres IP proxy, żeby poprawnie działało wykrywanie połączenia HTTPS i adresu IP klienta. Czyli żeby [Nette\Http\Request::getRemoteAddress() |request#getRemoteAddress()] i [isSecured() |request#isSecured()] zwracały poprawne wartości, a w szablonach generowały się odnośniki z protokołem `https:`.

```neon
http:
	# adres IP, zakres (np. 127.0.0.1/8) albo tablica tych wartości
	proxy: 127.0.0.1       # (string|string[]) domyślnie nieustawione
```


Wymuszenie HTTPS .{data-version:3.3.4}
--------------------------------------

Bezwarunkowo wymusza schemat żądania HTTPS. Przydaje się to dla witryn działających wyłącznie na HTTPS za load balancerem albo reverse proxy, które terminuje TLS, ale nie przekazuje nagłówka `X-Forwarded-Proto`, przez co standardowe wykrywanie HTTPS (nawet przy skonfigurowanym [#Proxy HTTP]) by tego nie wychwyciło.

```neon
http:
	# wymusza schemat HTTPS dla wszystkich żądań
	forceHttps: true       # (bool) domyślnie false
```


Sesja
=====

Podstawowe ustawienia [sesji |sessions]:

```neon
session:
	# pokazać panel sesji w Tracy Bar?
	debugger: ...        # (bool) domyślnie false

	# czas nieaktywności, po którym sesja wygasa
	expiration: 14 days  # (string) domyślnie '3 hours'

	# kiedy sesja ma się uruchomić?
	autoStart: ...       # (smart|always|never) domyślnie 'smart'

	# handler, usługa implementująca SessionHandlerInterface
	handler: @handlerService
```

Opcja `autoStart` steruje tym, kiedy sesja ma się uruchomić. Wartość `always` oznacza, że sesja uruchamia się zawsze przy starcie aplikacji. Wartość `smart` oznacza, że sesja uruchamia się przy starcie aplikacji tylko wtedy, gdy już istnieje, albo w momencie, gdy chcemy z niej czytać albo do niej pisać. Wreszcie wartość `never` wyłącza automatyczne uruchamianie sesji.

Poza tym możesz ustawić wszystkie [dyrektywy sesji |https://www.php.net/manual/en/session.configuration.php] PHP (w formacie camelCase), a także [readAndClose |https://www.php.net/manual/en/function.session-start.php#refsect1-function.session-start-parameters]. Przykład:

```neon
session:
	# 'session.name' zapisane jako 'name'
	name: MYID

	# 'session.save_path' zapisane jako 'savePath'
	savePath: "%tempDir%/sessions"
```


Cookie sesji
------------

Cookie sesji wysyłane jest z tymi samymi parametrami co [pozostałe cookies |#Cookie HTTP], ale możesz je zmienić specjalnie dla niego:

```neon
session:
	# domeny, które mogą przyjąć cookie
	cookieDomain: 'example.com'   # (string|domain)

	# ograniczenie przy dostępie cross-origin
	cookieSamesite: None          # (Strict|Lax|None) domyślnie Lax
```

Atrybut `cookieSamesite` wpływa na to, czy cookie jest wysyłane przy [żądaniach cross-origin |nette:glossary#Cookie SameSite], co daje pewną ochronę przed atakami [Cross-Site Request Forgery |nette:glossary#Cross-Site Request Forgery (CSRF)] (CSRF).


Usługi DI
=========

Do kontenera DI dodawane są te usługi:

| Nazwa           | Typ                        | Opis
|-----------------|----------------------------|---------------------------
| `http.request`  | [api:Nette\Http\Request]   | [żądanie HTTP| request]
| `http.response` | [api:Nette\Http\Response]  | [odpowiedź HTTP| response]
| `session.session`| [api:Nette\Http\Session]   | [zarządzanie sesją| sessions]
| `http.requestFactory`| [api:Nette\Http\RequestFactory] | fabryka tworząca żądanie HTTP