Configuring HTTP
****************

.[perex]
Overview of configuration options for the Nette HTTP.

If you are not using the whole framework, but only this library, read [how to load the configuration|bootstrap:].


HTTP Headers
============

```neon
http:
	# headers that are sent with each request
	headers:
		X-Powered-By: MyCMS
		X-Content-Type-Options: nosniff
		X-XSS-Protection: '1; mode=block'

	# affects header X-Frame-Options
	frames: ...      # (string|bool) defaults to 'SAMEORIGIN'
```

For security reasons, the framework sends a header `X-Frame-Options: SAMEORIGIN`, which says that a page can be displayed inside another page (in element `<iframe>`) only if it is on the same domain. This can be unwanted in certain situations (for example, if you are developing a Facebook application), so the behavior can be changed by setting `frames: http://allowed-host.com` or `frames: true`.


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

Headers `Content-Security-Policy` (hereinafter referred to as CSP) can be easily assembled, their description can be found in [CSP description |https://content-security-policy.com]. CSP directives (such as `script-src`) can be written either as strings according to specification or as arrays of values ​​for better readability. Then there is no need to write quotation marks around keywords such as `'self'`. Nette will also automatically generate a value of `nonce`, so `'nonce-y4PopTLM=='` will be send in the header.

```neon
http:
	# Content Security Policy
	csp:
		# string according to CSP specification
		default-src: "'self' https://example.com"

		# array of values
		script-src:
			- nonce
			- strict-dynamic
			- self
			- https://example.com

		# bool in the case of switches
		upgrade-insecure-requests: true
		block-all-mixed-content: false
```

Use `<script n:nonce>...</script>` in the templates and the nonce value will be filled in automatically. Making secure websites in Nette is really easy.

Similarly, headers `Content-Security-Policy-Report-Only` (which can be used in parallel with CSP) and [Feature Policy |https://developers.google.com/web/updates/2018/06/feature-policy] can be added:

```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
```


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

You can change the default values of some parameters of the [Nette\Http\Response::setCookie() |response#setCookie] and session methods.

```neon
http:
	# cookie scope by path
	cookiePath: ...          # (string) defaults to '/'

	# which hosts are allowed to receive the cookie
	cookieDomain: 'example.com'  # (string|domain) defaults to unset

	# to send cookies only via HTTPS?
	cookieSecure: ...        # (bool|auto) defaults to auto

	# disables the sending of the cookie that Nette uses as protection against CSRF
	disableNetteCookie: ...  # (bool) defaults to false
```

The `cookieDomain` option determines which domains (origins) can accept cookies. If not specified, the cookie is accepted by the same (sub)domain as is set by it, *excluding* their subdomains. If `cookieDomain` is specified, then subdomains are also included. Therefore, specifying `cookieDomain` is less restrictive than omitting.

For example, if `cookieDomain: nette.org` is set, cookie is also available on all subdomains like `doc.nette.org`. This can also be achieved with the special value `domain`, ie `cookieDomain: domain`.

The default value of `cookieSecure` is `auto` which means that if the website is running on HTTPS, cookies will be sent with the `Secure` flag and will therefore only be available via HTTPS.

.[warning]
For version 3.0, only the `cookieSecure` parameter can be configured and its default value is `false`.


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

If the site is running behind an HTTP proxy, enter the IP address of the proxy so that detection of HTTPS connections works correctly, as well as the client IP address. That is, so that [Nette\Http\Request::getRemoteAddress()|request#getRemoteAddress] and [isSecured()|request#isSecured] return the correct values and links are generated with the `https:` protocol in the templates.

```neon
http:
	# IP address, range (ie. 127.0.0.1/8) or array of these values
	proxy: 127.0.0.1       # (string|string[]) defaults to none
```


Session
=======

Basic [sessions] settings:

```neon
session:
	# shows session panel in Tracy Bar?
	debugger: ...        # (bool) defaults to false

	# inactivity time after which the session expires
	expiration: 14 days  # (string) defaults to '3 hours'

	# when to start the session?
	autoStart: ...       # (smart|always|never) defaults to 'smart'

	# handler, service that implements the SessionHandlerInterface interface
	handler: @handlerService
```

The `autoStart` option controls when to start the session. The value `always` means that the session is always started when the application starts. The `smart` value means that the session will be started when the application starts only if it already exists, or at the moment we want to read from or write to it. Finally, the value `never` disables the automatic start of the session. This has been in use since "nette/http 3.1.5":[https://github.com/nette/http/releases/tag/v3.1.5].

You can also set all PHP [session directives |https://www.php.net/manual/en/session.configuration.php] (in camelCase format) and also [readAndClose |https://www.php.net/manual/en/function.session-start.php#refsect1-function.session-start-parameters]. Example:

```neon
session:
	# 'session.name' written as 'name'
	name: MYID

	# 'session.save_path' written as 'savePath'
	savePath: "%tempDir%/sessions"
```


Session Cookie
--------------

The session cookie is sent with the same parameters as [other cookie|#HTTP cookie], but you can change these for it:

```neon
session:
	# which hosts are allowed to receive the cookie
	cookieDomain: 'example.com'   # (string|domain)

	# restrictions when accessing cross-origin request
	cookieSamesite: None          # (Strict|Lax|None) defaults to Lax (not set in version 3.0)
```

The `cookieSamesite` option affects whether the cookie is sent with [cross-origin requests |nette:glossary#SameSite cookie], which provides some protection against [Cross-Site Request Forgery|nette:glossary#cross-site-request-forgery-csrf] attecks.


DI Services
===========

These services are added to the DI container:

| Name            | Type                       | Description
|-----------------------------------------------------
| `http.request`	  | [api:Nette\Http\Request]   | [HTTP request| request]
| `http.response`	  | [api:Nette\Http\Response]  | [HTTP response| response]
| `session.session` |	[api:Nette\Http\Session]   | [session management| sessions]