v/vlib/vweb/README.md

# vweb - the V Web Server

A simple yet powerful web server with built-in routing, parameter handling, templating, and other
features.
The [gitly](https://gitly.org/) site is based on vweb.

**_Some features may not be complete, and have some bugs._**

## Getting start
Just run **`v new <name> web`** in your terminal

## Features

- **Very fast** performance of C on the web.
- **Small binary** hello world website is <100 KB.
- **Easy to deploy** just one binary file that also includes all templates. No need to install any
  dependencies.
- **Templates are precompiled** all errors are visible at compilation time, not at runtime.

### Examples

There are some examples
that can be explored [here](https://github.com/vlang/v/tree/master/examples/vweb).

And others like:

- [vweb_orm_jwt](https://github.com/vlang/v/tree/master/examples/vweb_orm_jwt) (back-end)
- [vorum](https://github.com/vlang/vorum) (front-end)
- [gitly](https://github.com/vlang/gitly) (full-stack)

**Front-end getting start example**
`src/main.v`

```v ignore
module main

import vweb
import os

struct App {
	vweb.Context
}

struct Object {
	title       string
	description string
}

fn main() {
	vweb.run_at(new_app(), vweb.RunParams{
		port: 8081
	}) or { panic(err) }
}

fn new_app() &App {
	mut app := &App{}
	// makes all static files available.
	app.mount_static_folder_at(os.resource_abs_path('.'), '/')
	return app
}

['/']
pub fn (mut app App) page_home() vweb.Result {
	// all this constants can be accessed by src/templates/page/home.html file.
	page_title := 'V is the new V'
	v_url := 'https://github.com/vlang/v'

	list_of_object := [
		Object{
			title: 'One good title'
			description: 'this is the first'
		},
		Object{
			title: 'Other good title'
			description: 'more one'
		},
	]
	// $vweb.html() in `<folder>_<name> vweb.Result ()` like this
	// render the `<name>.html` in folder `./templates/<folder>`
	return $vweb.html()
}

```

`$vweb.html()` compiles an HTML template into V during compilation, and embeds the resulting code
into the current action.

That means that the template automatically has access to that action's entire environment.

`src/templates/page/home.html`

```html
<html>
  <header>
    <title>${page_title}</title>
    @css 'src/templates/page/home.css'
  </header>
  <body>
    <h1 class="title">Hello, Vs.</h1>
    @for var in list_of_object
    <div>
      <a href="${v_url}">${var.title}</a>
      <span>${var.description}</span>
    </div>
    @end
    <div>@include 'component.html'</div>
  </body>
</html>
```

`src/templates/page/component.html`

```html
<div>This is a component</div>
```

`src/templates/page/home.css`

```css
h1.title {
  font-family: Arial, Helvetica, sans-serif;
  color: #3b7bbf;
}
```

V supports [Template directives](/vlib/v/TEMPLATES.md) like
`@css`, `@js` for static files in \<path\>
`@if`, `@for` for conditional and loop
and
`@include` to include html components.

## Deploying vweb apps

Everything, including HTML templates, is in one binary file. That's all you need to deploy.

## Getting Started

To start with vweb, you have to import the module `vweb` and define a struct to hold vweb.Context
(and any other variables your program will need).
The web server can be started by calling `vweb.run(&App{}, port)` or `vweb.run(&App{}, RunParams)`

**Example:**

```v ignore
import vweb

struct App {
    vweb.Context
}

fn main() {
	vweb.run(&App{}, 8080)
	// // or
	// vweb.run_at(new_app(), vweb.RunParams{
	// 	host: 'localhost'
	// 	port: 8099
	// 	family: .ip
	// }) or { panic(err) }
}
```

### Defining endpoints

To add endpoints to your web server, you have to extend the `App` struct.
For routing you can either use auto-mapping of function names or specify the path as an attribute.
The function expects a response of the type `vweb.Result`.

**Example:**

```v ignore
// This endpoint can be accessed via http://localhost:port/hello
fn (mut app App) hello() vweb.Result {
	return app.text('Hello')
}

// This endpoint can be accessed via http://localhost:port/foo
["/foo"]
fn (mut app App) world() vweb.Result {
	return app.text('World')
}
```

#### - HTTP verbs

To use any HTTP verbs (or methods, as they are properly called),
such as `[post]`, `[get]`, `[put]`, `[patch]` or `[delete]`
you can simply add the attribute before the function definition.

**Example:**

```v ignore
[post]
fn (mut app App) world() vweb.Result {
	return app.text('World')
}

['/product/create'; post]
fn (mut app App) create_product() vweb.Result {
	return app.text('product')
}
```

#### - Parameters

Parameters are passed directly in endpoint route using colon sign `:` and received using the same
name at function
To pass a parameter to an endpoint, you simply define it inside an attribute, e. g.
`['/hello/:user]`.
After it is defined in the attribute, you have to add it as a function parameter.

**Example:**

```v ignore
          vvvv
['/hello/:user']            vvvv
fn (mut app App) hello_user(user string) vweb.Result {
	return app.text('Hello $user')
}
```

You have access to the raw request data such as headers
or the request body by accessing `app` (which is `vweb.Context`).
If you want to read the request body, you can do that by calling `app.req.data`.
To read the request headers, you just call `app.req.header` and access the
header you want example. `app.req.header.get(.content_type)`. See `struct Header`
for all available methods (`v doc net.http Header`).
It has, too, fields for the `query`, `form`, `files`.

#### - Query
To handle the query context, you just need use the  `query` field

**Example:**

```v
module main

import vweb

struct App {
	vweb.Context
}

fn main() {
	vweb.run(&App{}, 8081)
}

['/user'; get]
pub fn (mut app App) controller_get_user_by_id() vweb.Result {
	// http://localhost:3000/user?q=vpm&order_by=desc => { 'q': 'vpm', 'order_by': 'desc' }
	return app.text(app.query.str())
}
```
### Middleware

V haven't a well defined middleware.
For now, you can use `before_request()`. This method called before every request.
Probably you can use it for check user session cookie or add header
**Example:**

```v ignore
pub fn (mut app App) before_request() {
    app.user_id = app.get_cookie('id') or { '0' }
}
```

### Redirect

Used when you want be redirected to an url
**Examples:**

```v ignore
pub fn (mut app App) before_request() {
    app.user_id = app.get_cookie('id') or { app.redirect('/') }
}
```

```v ignore
['/articles'; get]
pub fn (mut app App) articles() vweb.Result {
    if !app.token {
        app.redirect('/login')
    }
    return app.text("patatoes")
}
```

### Responses

#### - set_status

Sets the response status
**Example:**

```v ignore
['/user/get_all'; get]
pub fn (mut app App) controller_get_all_user() vweb.Result {
    token := app.get_header('token')

    if !token {
        app.set_status(401, '')
        return app.text('Not valid token')
    }

    response := app.service_get_all_user() or {
        app.set_status(400, '')
        return app.text('$err')
    }
    return app.json(response)
}
```

#### - html

Response HTTP_OK with payload with content-type `text/html`
**Example:**

```v ignore
pub fn (mut app App) html_page() vweb.Result {
    return app.html('<h1>ok</h1>')
}
```

#### - text

Response HTTP_OK with payload with content-type `text/plain`
**Example:**

```v ignore
pub fn (mut app App) simple() vweb.Result {
    return app.text('A simple result')
}
```

#### - json

Response HTTP_OK with payload with content-type `application/json`
**Examples:**

```v ignore
['/articles'; get]
pub fn (mut app App) articles() vweb.Result {
    articles := app.find_all_articles()
    json_result := json.encode(articles)
    return app.json(json_result)
}
```

```v ignore
['/user/create'; post]
pub fn (mut app App) controller_create_user() vweb.Result {
    body := json.decode(User, app.req.data) or {
        app.set_status(400, '')
        return app.text('Failed to decode json, error: $err')
	}

    response := app.service_add_user(body.username, body.password) or {
        app.set_status(400, '')
        return app.text('error: $err')
    }

    return app.json(response)
}
```

#### - json_pretty

Response HTTP_OK with a pretty-printed JSON result
**Example:**

```v ignore
fn (mut app App) time_json_pretty() {
    app.json_pretty({
        'time': time.now().format()
    })
}
```

#### - file

Response HTTP_OK with file as payload

#### - ok

Response HTTP_OK with payload
**Example:**

```v ignore
['/form_echo'; post]
pub fn (mut app App) form_echo() vweb.Result {
    app.set_content_type(app.req.header.get(.content_type) or { '' })
    return app.ok(app.form['foo'])
}
```

#### - server_error

Response a server error
**Example:**

```v ignore
fn (mut app App) sse() vweb.Result {
    return app.server_error(501)
}
```

#### - not_found

Response HTTP_NOT_FOUND with payload
**Example:**

```v ignore
['/:user/:repo/settings']
pub fn (mut app App) user_repo_settings(username string, repository string) vweb.Result {
    if username !in known_users {
        return app.not_found()
    }
    return app.html('username: $username | repository: $repository')
}
```

### Requests

#### - get_header

Returns the header data from the key
**Example:**

```v ignore
['/user/get_all'; get]
pub fn (mut app App) controller_get_all_user() vweb.Result {
    token := app.get_header('token')
    return app.text(token)
}
```

#### - get_cookie

Sets a cookie
**Example:**

```v ignore
pub fn (mut app App) before_request() {
    app.user_id = app.get_cookie('id') or { '0' }
}
```

#### - add_header

Adds an header to the response with key and val
**Example:**

```v ignore
['/upload'; post]
pub fn (mut app App) upload() vweb.Result {
    fdata := app.files['upfile']

    data_rows := fdata[0].data.split('\n')

    mut output_data := ''

    for elem in data_rows {
        delim_row := elem.split('\t')
        output_data += '${delim_row[0]}\t${delim_row[1]}\t'
        output_data += '${delim_row[0].int() + delim_row[1].int()}\n'
	}

    output_data = output_data.all_before_last('\n')

    app.add_header('Content-Disposition', 'attachment; filename=results.txt')
    app.send_response_to_client('application/octet-stream', output_data)

    return $vweb.html()
}
```

#### - set_cookie

Sets a cookie
**Example:**

```v ignore
pub fn (mut app App) cookie() vweb.Result {
    app.set_cookie(name: 'cookie', value: 'test')
    return app.text('Response Headers\n$app.header')
}
```

#### - set_cookie_with_expire_date

Sets a cookie with a `expire_data`
**Example:**

```v ignore
pub fn (mut app App) cookie() vweb.Result {
    key := 'cookie'
    value := 'test'
    duration := time.Duration(2 * time.minute ) // add 2 minutes
    expire_date := time.now().add(duration)

    app.set_cookie_with_expire_date(key, value, expire_date)
    return app.text('Response Headers\n$app.header')
}
```

#### - set_content_type

Sets the response content type
**Example:**

```v ignore
['/form_echo'; post]
pub fn (mut app App) form_echo() vweb.Result {
    app.set_content_type(app.req.header.get(.content_type) or { '' })
    return app.ok(app.form['foo'])
}
```

### Template

#### -handle_static

handle_static is used to mark a folder (relative to the current working folder) as one that
contains only static resources (css files, images etc).

If `root` is set the mount path for the dir will be in '/'

**Example:**

```v ignore
fn main() {
    mut app := &App{}
    app.serve_static('/favicon.ico', 'favicon.ico')
    // Automatically make available known static mime types found in given directory.
    os.chdir(os.dir(os.executable()))?
    app.handle_static('assets', true)
    vweb.run(app, port)
}
```

#### -mount_static_folder_at

makes all static files in `directory_path` and inside it, available at http://server/mount_path.

For example: suppose you have called .mount_static_folder_at('/var/share/myassets', '/assets'),
and you have a file /var/share/myassets/main.css .
=> That file will be available at URL: http://server/assets/main.css .

#### -serve_static

Serves a file static.
`url` is the access path on the site, `file_path` is the real path to the file, `mime_type` is the
file type

**Example:**

```v ignore
fn main() {
    mut app := &App{}
    app.serve_static('/favicon.ico', 'favicon.ico')
    app.mount_static_folder_at(os.resource_abs_path('.'), '/')
    vweb.run(app, 8081)
}
```

### Others

#### -ip

Returns the ip address from the current user

**Example:**

```v ignore
pub fn (mut app App) ip() vweb.Result {
    ip := app.ip()
    return app.text('ip: $ip')
}
```

#### -error

Set a string to the form error

**Example:**

```v ignore
pub fn (mut app App) error() vweb.Result {
    app.error('here as an error')
    println(app.form_error) //'vweb error: here as an error'
}
```
# Cross-Site Request Forgery (CSRF) protection
## Provides protection against Cross-Site Request Forgery 

## Usage

When building a csrf-protected service, first of all create a `struct`that implements `csrf.App`

```v ignore
module main

import vweb
import vweb.csrf

// embeds the csrf.App struct in order to empower the struct to protect against CSRF
struct App {
	csrf.App
}
```

Start a server e.g. in the main function.

```v ignore
fn main() {
	vweb.run_at(&App{}, vweb.RunParams{
        port: 8080
    }) or { panic(err) }
}
```

### Enable CSRF-protection

Then add a handler-function to define on which route or on which site the CSRF-Token shall be set.

```v ignore
fn (mut app App) index() vweb.Result {

    // Set a Csrf-Cookie (Token will be generated automatically)
	app.set_csrf_cookie()

	// Get the token-value from the csrf-cookie that was just set
	token := app.get_csrf_token() or { panic(err) }

	return app.text("Csrf-Token set! It's value is: $token")
}
```

If you want to set the cookies's HttpOnly-status to false in order to make it  
 accessible to scripts on your site, you can do it like this:
`app.set_csrf_cookie(csrf.HttpOnly{false})`
If no argument is passed the value will be set to true by default.


### Protect against CSRF

If you want to protect a route or a site against CSRF just add  
`app.csrf_protect()` at the beginning of the handler-function.

```v ignore
fn (mut app App) foo() vweb.Result {
    // Protect this handler-function against CSRF
	app.csrf_protect()
	return app.text("Checked and passed csrf-guard")
}
```
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`# vweb - the V Web Server`
update vweb readme 2019-07-29 20:46:26 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`A simple yet powerful web server with built-in routing, parameter handling, templating, and other`
			`features.`
			`The [gitly](https://gitly.org/) site is based on vweb.`
vweb: readme: list some features of vweb 2019-12-10 00:16:39 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`_Some features may not be complete, and have some bugs._`
update vweb readme 2019-07-29 20:46:26 +03:00
vweb: add the `v new <name> web` command for starting new projects to the README.md (#16904) 2023-01-08 19:33:17 +03:00			`## Getting start`
			Just run `v new <name> web` in your terminal

docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`## Features`
vweb example 2019-07-30 22:15:17 +03:00
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00			`- Very fast performance of C on the web.`
			`- Small binary hello world website is <100 KB.`
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`- Easy to deploy just one binary file that also includes all templates. No need to install any`
			`dependencies.`
			`- Templates are precompiled all errors are visible at compilation time, not at runtime.`

			`### Examples`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`There are some examples`
			`that can be explored [here](https://github.com/vlang/v/tree/master/examples/vweb).`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`And others like:`
vweb example 2019-07-30 22:15:17 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`- [vweb_orm_jwt](https://github.com/vlang/v/tree/master/examples/vweb_orm_jwt) (back-end)`
			`- [vorum](https://github.com/vlang/vorum) (front-end)`
			`- [gitly](https://github.com/vlang/gitly) (full-stack)`

			`Front-end getting start example`
			`src/main.v`
vweb documentation 2019-07-29 19:50:25 +03:00
docs_ci: check all md files except thirdparty (#6855) 2020-11-18 20:28:28 +03:00			```v ignore
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`module main`

			`import vweb`
			`import os`

			`struct App {`
			`vweb.Context`
vweb documentation 2019-07-29 19:50:25 +03:00			`}`

docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`struct Object {`
			`title string`
			`description string`
			`}`

			`fn main() {`
			`vweb.run_at(new_app(), vweb.RunParams{`
			`port: 8081`
			`}) or { panic(err) }`
			`}`

			`fn new_app() &App {`
			`mut app := &App{}`
			`// makes all static files available.`
			`app.mount_static_folder_at(os.resource_abs_path('.'), '/')`
			`return app`
vweb documentation 2019-07-29 19:50:25 +03:00			`}`
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00
			`['/']`
			`pub fn (mut app App) page_home() vweb.Result {`
			`// all this constants can be accessed by src/templates/page/home.html file.`
			`page_title := 'V is the new V'`
			`v_url := 'https://github.com/vlang/v'`

			`list_of_object := [`
			`Object{`
			`title: 'One good title'`
			`description: 'this is the first'`
			`},`
			`Object{`
			`title: 'Other good title'`
			`description: 'more one'`
			`},`
			`]`
			// $vweb.html() in `<folder>_<name> vweb.Result ()` like this
			// render the `<name>.html` in folder `./templates/<folder>`
			`return $vweb.html()`
			`}`

vweb documentation 2019-07-29 19:50:25 +03:00			```

docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`$vweb.html()` compiles an HTML template into V during compilation, and embeds the resulting code
			`into the current action.`

			`That means that the template automatically has access to that action's entire environment.`

			`src/templates/page/home.html`
vweb documentation 2019-07-29 19:50:25 +03:00
update vweb readme 2019-07-29 20:46:26 +03:00			```html
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`<html>`
			`<header>`
			`<title>${page_title}</title>`
			`@css 'src/templates/page/home.css'`
			`</header>`
			`<body>`
			`<h1 class="title">Hello, Vs.</h1>`
			`@for var in list_of_object`
			`<div>`
			`<a href="${v_url}">${var.title}</a>`
			`<span>${var.description}</span>`
			`</div>`
			`@end`
			`<div>@include 'component.html'</div>`
			`</body>`
			`</html>`
vweb documentation 2019-07-29 19:50:25 +03:00			```

docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`src/templates/page/component.html`
vweb documentation 2019-07-29 19:50:25 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			```html
			`<div>This is a component</div>`
			```
update vweb readme 2019-07-29 20:46:26 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`src/templates/page/home.css`
update vweb readme 2019-07-29 20:46:26 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			```css
			`h1.title {`
			`font-family: Arial, Helvetica, sans-serif;`
			`color: #3b7bbf;`
			`}`
			```
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00
vweb: fix a typo in the README.md (#15913) * Fix typo * Update vlib/vweb/README.md Co-authored-by: JalonSolov <JalonSolov@gmail.com> Co-authored-by: Delyan Angelov <delian66@gmail.com> Co-authored-by: JalonSolov <JalonSolov@gmail.com> 2022-09-29 14:29:02 +03:00			`V supports [Template directives](/vlib/v/TEMPLATES.md) like`
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`@css`, `@js` for static files in \<path\>
			`@if`, `@for` for conditional and loop
			`and`
			`@include` to include html components.
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`## Deploying vweb apps`
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`Everything, including HTML templates, is in one binary file. That's all you need to deploy.`

			`## Getting Started`

			To start with vweb, you have to import the module `vweb` and define a struct to hold vweb.Context
			`(and any other variables your program will need).`
			The web server can be started by calling `vweb.run(&App{}, port)` or `vweb.run(&App{}, RunParams)`
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00
			`Example:`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			```v ignore
			`import vweb`

			`struct App {`
			`vweb.Context`
			`}`

			`fn main() {`
vweb: a minor readme update 2021-05-17 08:51:49 +03:00			`vweb.run(&App{}, 8080)`
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`// // or`
			`// vweb.run_at(new_app(), vweb.RunParams{`
			`// host: 'localhost'`
			`// port: 8099`
			`// family: .ip`
			`// }) or { panic(err) }`
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			`}`
			```

docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`### Defining endpoints`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			To add endpoints to your web server, you have to extend the `App` struct.
			`For routing you can either use auto-mapping of function names or specify the path as an attribute.`
			The function expects a response of the type `vweb.Result`.

			`Example:`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			```v ignore
			`// This endpoint can be accessed via http://localhost:port/hello`
			`fn (mut app App) hello() vweb.Result {`
			`return app.text('Hello')`
			`}`

			`// This endpoint can be accessed via http://localhost:port/foo`
			`["/foo"]`
			`fn (mut app App) world() vweb.Result {`
			`return app.text('World')`
			`}`
			```

docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`#### - HTTP verbs`

			`To use any HTTP verbs (or methods, as they are properly called),`
			such as `[post]`, `[get]`, `[put]`, `[patch]` or `[delete]`
			`you can simply add the attribute before the function definition.`
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00
			`Example:`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			```v ignore
			`[post]`
			`fn (mut app App) world() vweb.Result {`
			`return app.text('World')`
			`}`
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00
			`['/product/create'; post]`
			`fn (mut app App) create_product() vweb.Result {`
			`return app.text('product')`
			`}`
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			```

docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`#### - Parameters`

docs: fix typos using codespell (#17332) 2023-02-16 12:43:39 +03:00			Parameters are passed directly in endpoint route using colon sign `:` and received using the same
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`name at function`
			`To pass a parameter to an endpoint, you simply define it inside an attribute, e. g.`
			`['/hello/:user]`.
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			`After it is defined in the attribute, you have to add it as a function parameter.`

			`Example:`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			```v ignore
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`vvvv`
			`['/hello/:user'] vvvv`
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			`fn (mut app App) hello_user(user string) vweb.Result {`
			`return app.text('Hello $user')`
			`}`
			```

http: use Header struct for headers (#9462) 2021-04-09 19:17:33 +03:00			`You have access to the raw request data such as headers`
docs: add a basic vweb getting started example (#9073) 2021-03-03 15:39:04 +03:00			or the request body by accessing `app` (which is `vweb.Context`).
			If you want to read the request body, you can do that by calling `app.req.data`.
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00			To read the request headers, you just call `app.req.header` and access the
vweb: document the .query field (#15572) 2022-08-28 09:55:18 +03:00			header you want example. `app.req.header.get(.content_type)`. See `struct Header`
doc: vweb README (#10106) 2021-05-15 05:53:25 +03:00			for all available methods (`v doc net.http Header`).
vweb: document the .query field (#15572) 2022-08-28 09:55:18 +03:00			It has, too, fields for the `query`, `form`, `files`.
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00
vweb: document the .query field (#15572) 2022-08-28 09:55:18 +03:00			`#### - Query`
			To handle the query context, you just need use the `query` field

			`Example:`

			```v
			`module main`

			`import vweb`

			`struct App {`
			`vweb.Context`
			`}`

			`fn main() {`
			`vweb.run(&App{}, 8081)`
			`}`

			`['/user'; get]`
			`pub fn (mut app App) controller_get_user_by_id() vweb.Result {`
			`// http://localhost:3000/user?q=vpm&order_by=desc => { 'q': 'vpm', 'order_by': 'desc' }`
			`return app.text(app.query.str())`
			`}`
			```
docs: improve vlib/vweb/README.md (#15146) 2022-08-20 12:06:24 +03:00			`### Middleware`

			`V haven't a well defined middleware.`
			For now, you can use `before_request()`. This method called before every request.
			`Probably you can use it for check user session cookie or add header`
			`Example:`

			```v ignore
			`pub fn (mut app App) before_request() {`
			`app.user_id = app.get_cookie('id') or { '0' }`
			`}`
			```

			`### Redirect`

			`Used when you want be redirected to an url`
			`Examples:`

			```v ignore
			`pub fn (mut app App) before_request() {`
			`app.user_id = app.get_cookie('id') or { app.redirect('/') }`
			`}`
			```

			```v ignore
			`['/articles'; get]`
			`pub fn (mut app App) articles() vweb.Result {`
			`if !app.token {`
			`app.redirect('/login')`
			`}`
			`return app.text("patatoes")`
			`}`
			```

			`### Responses`

			`#### - set_status`

			`Sets the response status`
			`Example:`

			```v ignore
			`['/user/get_all'; get]`
			`pub fn (mut app App) controller_get_all_user() vweb.Result {`
			`token := app.get_header('token')`

			`if !token {`
			`app.set_status(401, '')`
			`return app.text('Not valid token')`
			`}`

			`response := app.service_get_all_user() or {`
			`app.set_status(400, '')`
			`return app.text('$err')`
			`}`
			`return app.json(response)`
			`}`
			```

			`#### - html`

			Response HTTP_OK with payload with content-type `text/html`
			`Example:`

			```v ignore
			`pub fn (mut app App) html_page() vweb.Result {`
			`return app.html('<h1>ok</h1>')`
			`}`
			```

			`#### - text`

			Response HTTP_OK with payload with content-type `text/plain`
			`Example:`

			```v ignore
			`pub fn (mut app App) simple() vweb.Result {`
			`return app.text('A simple result')`
			`}`
			```

			`#### - json`

			Response HTTP_OK with payload with content-type `application/json`
			`Examples:`

			```v ignore
			`['/articles'; get]`
			`pub fn (mut app App) articles() vweb.Result {`
			`articles := app.find_all_articles()`
			`json_result := json.encode(articles)`
			`return app.json(json_result)`
			`}`
			```

			```v ignore
			`['/user/create'; post]`
			`pub fn (mut app App) controller_create_user() vweb.Result {`
			`body := json.decode(User, app.req.data) or {`
			`app.set_status(400, '')`
			`return app.text('Failed to decode json, error: $err')`
			`}`

			`response := app.service_add_user(body.username, body.password) or {`
			`app.set_status(400, '')`
			`return app.text('error: $err')`
			`}`

			`return app.json(response)`
			`}`
			```

			`#### - json_pretty`

			`Response HTTP_OK with a pretty-printed JSON result`
			`Example:`

			```v ignore
			`fn (mut app App) time_json_pretty() {`
			`app.json_pretty({`
			`'time': time.now().format()`
			`})`
			`}`
			```

			`#### - file`

			`Response HTTP_OK with file as payload`

			`#### - ok`

			`Response HTTP_OK with payload`
			`Example:`

			```v ignore
			`['/form_echo'; post]`
			`pub fn (mut app App) form_echo() vweb.Result {`
			`app.set_content_type(app.req.header.get(.content_type) or { '' })`
			`return app.ok(app.form['foo'])`
			`}`
			```

			`#### - server_error`

			`Response a server error`
			`Example:`

			```v ignore
			`fn (mut app App) sse() vweb.Result {`
			`return app.server_error(501)`
			`}`
			```

			`#### - not_found`

			`Response HTTP_NOT_FOUND with payload`
			`Example:`

			```v ignore
			`['/:user/:repo/settings']`
			`pub fn (mut app App) user_repo_settings(username string, repository string) vweb.Result {`
			`if username !in known_users {`
			`return app.not_found()`
			`}`
			`return app.html('username: $username \| repository: $repository')`
			`}`
			```

			`### Requests`

			`#### - get_header`

			`Returns the header data from the key`
			`Example:`

			```v ignore
			`['/user/get_all'; get]`
			`pub fn (mut app App) controller_get_all_user() vweb.Result {`
			`token := app.get_header('token')`
			`return app.text(token)`
			`}`
			```

			`#### - get_cookie`

			`Sets a cookie`
			`Example:`

			```v ignore
			`pub fn (mut app App) before_request() {`
			`app.user_id = app.get_cookie('id') or { '0' }`
			`}`
			```

			`#### - add_header`

			`Adds an header to the response with key and val`
			`Example:`

			```v ignore
			`['/upload'; post]`
			`pub fn (mut app App) upload() vweb.Result {`
			`fdata := app.files['upfile']`

			`data_rows := fdata[0].data.split('\n')`

			`mut output_data := ''`

			`for elem in data_rows {`
			`delim_row := elem.split('\t')`
			`output_data += '${delim_row[0]}\t${delim_row[1]}\t'`
			`output_data += '${delim_row[0].int() + delim_row[1].int()}\n'`
			`}`

			`output_data = output_data.all_before_last('\n')`

			`app.add_header('Content-Disposition', 'attachment; filename=results.txt')`
			`app.send_response_to_client('application/octet-stream', output_data)`

			`return $vweb.html()`
			`}`
			```

			`#### - set_cookie`

			`Sets a cookie`
			`Example:`

			```v ignore
			`pub fn (mut app App) cookie() vweb.Result {`
			`app.set_cookie(name: 'cookie', value: 'test')`
			`return app.text('Response Headers\n$app.header')`
			`}`
			```

			`#### - set_cookie_with_expire_date`

			Sets a cookie with a `expire_data`
			`Example:`

			```v ignore
			`pub fn (mut app App) cookie() vweb.Result {`
			`key := 'cookie'`
			`value := 'test'`
			`duration := time.Duration(2 * time.minute ) // add 2 minutes`
			`expire_date := time.now().add(duration)`

			`app.set_cookie_with_expire_date(key, value, expire_date)`
			`return app.text('Response Headers\n$app.header')`
			`}`
			```

			`#### - set_content_type`

			`Sets the response content type`
			`Example:`

			```v ignore
			`['/form_echo'; post]`
			`pub fn (mut app App) form_echo() vweb.Result {`
			`app.set_content_type(app.req.header.get(.content_type) or { '' })`
			`return app.ok(app.form['foo'])`
			`}`
			```

			`### Template`

			`#### -handle_static`

			`handle_static is used to mark a folder (relative to the current working folder) as one that`
			`contains only static resources (css files, images etc).`

			If `root` is set the mount path for the dir will be in '/'

			`Example:`

			```v ignore
			`fn main() {`
			`mut app := &App{}`
			`app.serve_static('/favicon.ico', 'favicon.ico')`
			`// Automatically make available known static mime types found in given directory.`
			`os.chdir(os.dir(os.executable()))?`
			`app.handle_static('assets', true)`
			`vweb.run(app, port)`
			`}`
			```

			`#### -mount_static_folder_at`

			makes all static files in `directory_path` and inside it, available at http://server/mount_path.

			`For example: suppose you have called .mount_static_folder_at('/var/share/myassets', '/assets'),`
			`and you have a file /var/share/myassets/main.css .`
			`=> That file will be available at URL: http://server/assets/main.css .`

			`#### -serve_static`

			`Serves a file static.`
			`url` is the access path on the site, `file_path` is the real path to the file, `mime_type` is the
			`file type`

			`Example:`

			```v ignore
			`fn main() {`
			`mut app := &App{}`
			`app.serve_static('/favicon.ico', 'favicon.ico')`
			`app.mount_static_folder_at(os.resource_abs_path('.'), '/')`
			`vweb.run(app, 8081)`
			`}`
			```

			`### Others`

			`#### -ip`

			`Returns the ip address from the current user`

			`Example:`

			```v ignore
			`pub fn (mut app App) ip() vweb.Result {`
			`ip := app.ip()`
			`return app.text('ip: $ip')`
			`}`
			```

			`#### -error`

			`Set a string to the form error`

			`Example:`

			```v ignore
			`pub fn (mut app App) error() vweb.Result {`
			`app.error('here as an error')`
			`println(app.form_error) //'vweb error: here as an error'`
			`}`
			```
doc: one single file for vweb (#16248) 2022-10-29 06:33:48 +03:00			`# Cross-Site Request Forgery (CSRF) protection`
			`## Provides protection against Cross-Site Request Forgery`

			`## Usage`

			When building a csrf-protected service, first of all create a `struct`that implements `csrf.App`

			```v ignore
			`module main`

			`import vweb`
			`import vweb.csrf`

			`// embeds the csrf.App struct in order to empower the struct to protect against CSRF`
			`struct App {`
			`csrf.App`
			`}`
			```

			`Start a server e.g. in the main function.`

			```v ignore
			`fn main() {`
			`vweb.run_at(&App{}, vweb.RunParams{`
			`port: 8080`
			`}) or { panic(err) }`
			`}`
			```

			`### Enable CSRF-protection`

			`Then add a handler-function to define on which route or on which site the CSRF-Token shall be set.`

			```v ignore
			`fn (mut app App) index() vweb.Result {`

			`// Set a Csrf-Cookie (Token will be generated automatically)`
			`app.set_csrf_cookie()`

docs: fix typos using codespell (#17332) 2023-02-16 12:43:39 +03:00			`// Get the token-value from the csrf-cookie that was just set`
doc: one single file for vweb (#16248) 2022-10-29 06:33:48 +03:00			`token := app.get_csrf_token() or { panic(err) }`

			`return app.text("Csrf-Token set! It's value is: $token")`
			`}`
			```

			`If you want to set the cookies's HttpOnly-status to false in order to make it`
			`accessible to scripts on your site, you can do it like this:`
			`app.set_csrf_cookie(csrf.HttpOnly{false})`
			`If no argument is passed the value will be set to true by default.`


			`### Protect against CSRF`

			`If you want to protect a route or a site against CSRF just add`
			`app.csrf_protect()` at the beginning of the handler-function.

			```v ignore
			`fn (mut app App) foo() vweb.Result {`
			`// Protect this handler-function against CSRF`
			`app.csrf_protect()`
			`return app.text("Checked and passed csrf-guard")`
			`}`
			```