vweb #

vweb - the V Web Server

A simple yet powerful web server with built-in routing, parameter handling, templating, and other features. The gitly site is based on vweb.

Some features may not be complete, and have some bugs.

Quick Start

Just run v new <name> web in your terminal.

Run your vweb app with a live reload via v -d vweb_livereload watch run .

Now modifying any file in your web app (whether it's a .v file with the backend logic or a compiled .html template file) will result in an instant refresh of your app in the browser. No need to quit the app, rebuild it, and refresh the page in the browser!

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 anydependencies.- Templates are precompiled all errors are visible at compilation time, not at runtime.
Multithreaded by default

Examples

There are some examples that can be explored here.

And others like:

vweb_orm_jwt (back-end)
vorum (front-end)
gitly (full-stack)

Front-end getting start example src/main.v

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() &amp;App {
mut app := &amp;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 codeinto the current action.

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

src/templates/page/home.html

<html>
<head>
<title>${page_title}</title>
@css 'src/templates/page/home.css'
</head>
<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

<div>This is a component</div>

src/templates/page/home.css

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

V supports Template directives like@css, @js for static files in <path>@if, @for for conditional and loopand@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:

import vweb

struct App {
vweb.Context
}

fn main() {
vweb.run(&amp;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:

// 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:

@[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 samename at functionTo 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:

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 headersor 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 theheader you want example. app.req.header.get(.content_type). See struct Headerfor all available methods (v doc net.http Header).It has, too, fields for the query, form, files.

- Parameter Arrays

If you want multiple parameters in your route and if you want to parse the parametersyourself, or you want a wildcard route, you can add ... after the : and name,e.g. ['/:path...'].

This will match all routes after '/'. For example the url /path/to/test would givepath = '/path/to/test'.

vvv
@['/:path...']             vvvv
fn (mut app App) wildcard(path string) vweb.Result {
return app.text('URL path = "${path}"')
}

- Query

To handle the query context, you just need use the query field

Example:

module main

import vweb

struct App {
vweb.Context
}

fn main() {
vweb.run(&amp;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())
}

- Host

To restrict an endpoint to a specific host, you can use the host attributefollowed by a colon : and the host name. You can test the Host feature locallyby adding a host to the "hosts" file of your device.

Example:

@['/'; host: 'example.com']
pub fn (mut app App) hello_web() vweb.Result {
return app.text('Hello World')
}

@['/'; host: 'api.example.org']
pub fn (mut app App) hello_api() vweb.Result {
return app.text('Hello API')
}

// define the handler without a host attribute last if you have conflicting paths.
@['/']
pub fn (mut app App) hello_others() vweb.Result {
return app.text('Hello Others')
}

You can also create a controller to handle all requests from a specifichost in one app.

Middleware

Vweb has different kinds of middleware.The before_request() method is always called before every request before anyother middleware is processed. You could use it to check user session cookies or to add a header.

Example:

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

Middleware functions can be passed directly when creating an App instance and isexecuted when the url starts with the defined key.

In the following example, if a user navigates to /path/to/test the middlewareis executed in the following order: middleware_func, other_func, global_middleware.The middleware is executed in the same order as they are defined and if any function inthe chain returns false the propogation is stopped.

Example:

module main

import vweb

struct App {
vweb.Context
middlewares map[string][]vweb.Middleware
}

fn new_app() &amp;App {
mut app := &amp;App{
middlewares: {
// chaining is allowed, middleware will be evaluated in order
'/path/to/': [middleware_func, other_func]
'/':         [global_middleware]
}
}

// do stuff with app
// ...
return app
}

fn middleware_func(mut ctx vweb.Context) bool {
// ...
return true
}

fn other_func(mut ctx vweb.Context) bool {
// ...
return true
}

fn global_middleware(mut ctx vweb.Context) bool {
// ...
return true
}

Middleware functions will be of type vweb.Middleware and are not methods of App,so they could also be imported from other modules.

pub type Middleware = fn (mut Context) bool

Middleware can also be added to route specific functions via attributes.

Example:

@[middleware: check_auth]
@['/admin/data']
pub fn (mut app App) admin() vweb.Result {
// ...
}

// check_auth is a method of App, so we don't need to pass the context as parameter.
pub fn (mut app App) check_auth () bool {
// ...
return true
}

You can only add 1 middleware to a route specific function via attributes.

Middleware evaluation order

The middleware is executed in the following order:

before_request
The middleware in app.middlewares
The middleware in the [middleware] attribute

If any function of step 2 or 3 returns false the middleware functions that wouldcome after it are not executed and the app handler will also not be executed. Youcan think of it as a chain.

Context values

You can store a value pair in vweb's context. It is especially useful for passing variablesfrom a middleware function to the route handler.

Example:

module main

import vweb

struct App {
vweb.Context
middlewares map[string][]vweb.Middleware
}

pub fn (mut app App) index() vweb.Result {
// get the user or return HTTP 401
user := app.get_value[User]('user') or {
app.set_status(401, '')
return app.text('HTTP 401: Unauthorized')
}

return app.text('welcome ${user.name}')
}

fn main() {
vweb.run(&amp;App{
middlewares: {
'/': [get_session]
}
}, 8080)
}

struct User {
session_id string
name       string
}

fn get_session(mut ctx vweb.Context) bool {
// implement your own logic to get the user
user := User{
session_id: '123456'
name: 'Vweb'
}

// set the user
ctx.set_value('user', user)
return true
}

When you visit the index page the middleware function get_session will run firstThis function sets a User value to a key 'user'.We get this key in index and display it to the user if the 'user' key exists.

Changing Context values

By default context values are immutable when retrieved with get_value. If you want tochange the value later you have to set it again with set_value.

Example:

fn change_user(mut ctx vweb.Context) bool {
user := User{
session_id: '654321'
name: 'tester'
}

// set the user
ctx.set_value('user', user)
return true
}

Redirect

Used when you want be redirected to an url

Examples:

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

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

You can also combine middleware and redirect.

Example:

@[middleware: with_auth]
@['/admin/secret']
pub fn (mut app App) admin_secret() vweb.Result {
// this code should never be reached
return app.text('secret')
}

@['/redirect']
pub fn (mut app App) with_auth() bool {
app.redirect('/auth/login')
return false
}

Custom not found page

You can implement a not_found route that is called when a request is made and nomatching route is found to replace the default HTTP 404 not found page.

Example:

pub fn (mut app App) not_found() vweb.Result {
app.set_status(404, 'Not Found')
return app.html('<h1>Page not found</h1>')
}

Databases

The db field in a vweb app is reserved for database connections. The connection iscopied to each new request.

Example:

module main

import vweb
import db.sqlite

struct App {
vweb.Context
mut:
db sqlite.DB
}

fn main() {
// create the database connection
mut db := sqlite.connect('db')!

vweb.run(&amp;App{
db: db
}, 8080)
}

Multithreading

By default, a vweb app is multithreaded, that means that multiple requests canbe handled in parallel by using multiple CPU's: a worker pool. You canchange the number of workers (maximum allowed threads) by altering the nr_workersoption. The default behaviour is to use the maximum number of jobs (cores in most cases).

Example:

fn main() {
// assign a maximum of 4 workers
vweb.run_at(&amp;App{}, nr_workers: 4)
}

Database Pool

A single connection database works fine if you run your app with 1 worker, of ifyou access a file-based database like a sqlite file.

This approach will fail when using a non-file based database connection like a mysqlconnection to another server somewhere on the internet. Multiple threads would need to accessthe same connection at the same time.

To resolve this issue, you can use the vweb's built-in database pool. The database poolwill keep a number of connections open when the app is started and each worker isassigned its own connection.

Let's look how we can improve our previous example with database pooling and using apostgresql server instead.

Example:

module main

import vweb
import db.pg

struct App {
vweb.Context
db_handle vweb.DatabasePool[pg.DB]
mut:
db pg.DB
}

fn get_database_connection() pg.DB {
// insert your own credentials
return pg.connect(user: 'user', password: 'password', dbname: 'database') or { panic(err) }
}

fn main() {
// create the database pool and pass our `get_database_connection` function as handler
pool := vweb.database_pool(handler: get_database_connection)

// no need to set the `db` field
vweb.run(&amp;App{
db_handle: pool
}, 8080)
}

If you don't use the default number of workers (nr_workers) you have to changeit to the same number in vweb.run_at as in vweb.database_pool

Extending the App struct with `[vweb_global]`

You can change your App struct however you like, but there are some things youhave to keep in mind. Under the hood at each request a new instance of App isconstructed, and all fields are re-initialized with their default type values,except for the db field.

This behaviour ensures that each request is treated equally and in the same context, butproblems arise when we want to provide more context than just the default vweb.Context.

Let's view the following example where we want to provide a secret token to our app:

module main

import vweb

struct App {
vweb.Context
secret string
}

fn main() {
vweb.run(&amp;App{
secret: 'my secret'
}, 8080)
}

fn (mut app App) index() vweb.Result {
return app.text('My secret is: ${app.secret}')
}

When you visit localhost:8080/ you would expect to see the text"My secret is: my secret", but instead there is only the text"My secret is: ". This is because of the way vweb works. We can override the defaultbehaviour by adding the attribute [vweb_global] to the secret field.

Example:

struct App {
vweb.Context
secret string [vweb_global]
}

Now if you visit localhost:8080/ you see the text "My secret is: my secret".

Note: the value of secret gets initialized with the provided value when creatingApp. If you would modify secret in one request the value won't be changed in thenext request. You can use shared fields for this.

Shared Objects across requests

We saw in the previous section that we can persist data across multiple requests,but what if we want to be able to mutate the data? Since vweb works with threads,we have to use shared fields.

Let's see how we can add a visitor counter to our App.

Example:

module main

import vweb

struct Counter {
pub mut:
count int
}

struct App {
vweb.Context
mut:
counter shared Counter // shared fields can only be structs, arrays or maps.
}

fn main() {
// initialize the shared object
shared counter := Counter{
count: 0
}

vweb.run(&amp;App{
counter: counter
}, 8080)
}

fn (mut app App) index() vweb.Result {
mut count := 0
// lock the counter so we can modify it
lock app.counter {
app.counter.count += 1
count = app.counter.count
}
return app.text('Total visitors: ${count}')
}

Drawback of Shared Objects

The drawback of using shared objects is that it affects performance. In the previous exampleApp.counter needs to be locked each time the page is loaded if there are simultaneousrequests the next requests will have to wait for the lock to be released.

It is best practice to limit the use of shared objects as much as possible.

Controllers

Controllers can be used to split up app logic so you are able to have one structper "/". E.g. a struct Admin for urls starting with "/admin" and a struct Foofor urls starting with "/foo"

Example:

module main

import vweb

struct App {
vweb.Context
vweb.Controller
}

struct Admin {
vweb.Context
}

struct Foo {
vweb.Context
}

fn main() {
mut app := &amp;App{
controllers: [
vweb.controller('/admin', &amp;Admin{}),
vweb.controller('/foo', &amp;Foo{}),
]
}
vweb.run(app, 8080)
}

You can do everything with a controller struct as with a regular App struct.The only difference being is that only the main app that is being passed to vweb.runis able to have controllers. If you add vweb.Controller on a controller struct itwill simply be ignored.

Routing

Any route inside a controller struct is treated as a relative route to its controller namespace.

@['/path']
pub fn (mut app Admin) path vweb.Result {
return app.text('Admin')
}

When we created the controller with vweb.controller('/admin', &Admin{}) we toldvweb that the namespace of that controller is "/admin" so in this example we wouldsee the text "Admin" if we navigate to the url "/admin/path".

Vweb doesn't support fallback routes or duplicate routes, so if we add the followingroute to the example the code will produce an error.

@['/admin/path']
pub fn (mut app App) admin_path vweb.Result {
return app.text('Admin overwrite')
}

There will be an error, because the controller Admin handles all routes starting with"/admin"; the method admin_path is unreachable.

Hosts

You can also set a host for a controller. All requests coming from that host will be handledby the controller.

Example:

module main

import vweb

struct App {
vweb.Context
vweb.Controller
}

pub fn (mut app App) index() vweb.Result {
return app.text('App')
}

struct Example {
vweb.Context
}

// You can only access this route at example.com: http://example.com/
pub fn (mut app Example) index() vweb.Result {
return app.text('Example')
}

fn main() {
vweb.run(&amp;App{
controllers: [
vweb.controller_host('example.com', '/', &amp;Example{}),
]
}, 8080)
}

Databases and `[vweb_global]` in controllers

Fields with [vweb_global] have to passed to each controller individually.The db field is unique and will be treated as a vweb_global field at all times.

Example:

module main

import vweb
import db.sqlite

struct App {
vweb.Context
vweb.Controller
mut:
db sqlite.DB
}

struct Admin {
vweb.Context
mut:
db sqlite.DB
}

fn main() {
mut db := sqlite.connect('db')!

mut app := &amp;App{
db: db
controllers: [
vweb.controller('/admin', &amp;Admin{
db: db
}),
]
}
}

Using a database pool

Example:

module main

import vweb
import db.pg

struct App {
vweb.Context
vweb.Controller
db_handle vweb.DatabasePool[pg.DB]
mut:
db pg.DB
}

struct Admin {
vweb.Context
db_handle vweb.DatabasePool[pg.DB]
mut:
db pg.DB
}

fn get_database_connection() pg.DB {
// insert your own credentials
return pg.connect(user: 'user', password: 'password', dbname: 'database') or { panic(err) }
}

fn main() {
// create the database pool and pass our `get_database_connection` function as handler
pool := vweb.database_pool(handler: get_database_connection)

mut app := &amp;App{
db_handle: pool
controllers: [
vweb.controller('/admin', &amp;Admin{
db_handle: pool
}),
]
}
}

Responses

- set_status

Sets the response statusExample:

@['/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/htmlExample:

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/plainExample:

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

- json

Response HTTP_OK with payload with content-type application/jsonExamples:

@['/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)
}

@['/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 resultExample:

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 payloadExample:

@['/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 errorExample:

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

- not_found

Response HTTP_NOT_FOUND with payloadExample:

@['/: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 keyExample:

@['/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 cookieExample:

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 valExample:

@['/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 cookieExample:

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_dataExample:

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 typeExample:

@['/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 thatcontains only static resources (css files, images etc).
host_handle_static can be used to limit the static resources to a specific host.

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

Example:

fn main() {
mut app := &amp;App{}
app.serve_static('/favicon.ico', 'favicon.ico')
// app.host_serve_static('localhost', '/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 .

mount_static_folder_at can be used to limit the static resources to a specific host.

-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 thefile type

host_serve_static can be used to limit the static resources to a specific host.

Example:

fn main() {
mut app := &amp;App{}
app.serve_static('/favicon.ico', 'favicon.ico')
// app.host_serve_static('localhost', /favicon.ico', 'favicon.ico')
app.mount_static_folder_at(os.resource_abs_path('.'), '/')
vweb.run(app, 8081)
}

Others

-user_agent

Returns the user-agent from the current user

Example:

pub fn (mut app App) user_agent() vweb.Result {
ua := app.user_agent()
return app.text('User-Agent: $ua')
}

-ip

Returns the ip address from the current user

Example:

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:

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

Vweb has built-in csrf protection. Go to the csrf module to learn howyou can protect your app against CSRF.

Constants #

const methods_with_form = [http.Method.post, .put, .patch]

const headers_close = http.new_custom_header_from_map({
	'Server':                           'VWeb'
	http.CommonHeader.connection.str(): 'close'
}) or { panic('should never fail') }

const http_302 = http.new_response(
	status: .found
	body: '302 Found'
	header: headers_close
)

const http_303 = http.new_response(
	status: .see_other
	body: '303 See Other'
	header: headers_close
)

const http_400 = http.new_response(
	status: .bad_request
	body: '400 Bad Request'
	header: http.new_header(
		key: .content_type
		value: 'text/plain'
	).join(headers_close)
)

const http_404 = http.new_response(
	status: .not_found
	body: '404 Not Found'
	header: http.new_header(
		key: .content_type
		value: 'text/plain'
	).join(headers_close)
)

const http_500 = http.new_response(
	status: .internal_server_error
	body: '500 Internal Server Error'
	header: http.new_header(
		key: .content_type
		value: 'text/plain'
	).join(headers_close)
)

const mime_types = {
	'.aac':    'audio/aac'
	'.abw':    'application/x-abiword'
	'.arc':    'application/x-freearc'
	'.avi':    'video/x-msvideo'
	'.azw':    'application/vnd.amazon.ebook'
	'.bin':    'application/octet-stream'
	'.bmp':    'image/bmp'
	'.bz':     'application/x-bzip'
	'.bz2':    'application/x-bzip2'
	'.cda':    'application/x-cdf'
	'.csh':    'application/x-csh'
	'.css':    'text/css'
	'.csv':    'text/csv'
	'.doc':    'application/msword'
	'.docx':   'application/vnd.openxmlformats-officedocument.wordprocessingml.document'
	'.eot':    'application/vnd.ms-fontobject'
	'.epub':   'application/epub+zip'
	'.gz':     'application/gzip'
	'.gif':    'image/gif'
	'.htm':    'text/html'
	'.html':   'text/html'
	'.ico':    'image/vnd.microsoft.icon'
	'.ics':    'text/calendar'
	'.jar':    'application/java-archive'
	'.jpeg':   'image/jpeg'
	'.jpg':    'image/jpeg'
	'.js':     'text/javascript'
	'.json':   'application/json'
	'.jsonld': 'application/ld+json'
	'.md':     'text/markdown'
	'.mid':    'audio/midi audio/x-midi'
	'.midi':   'audio/midi audio/x-midi'
	'.mjs':    'text/javascript'
	'.mp3':    'audio/mpeg'
	'.mp4':    'video/mp4'
	'.mpeg':   'video/mpeg'
	'.mpkg':   'application/vnd.apple.installer+xml'
	'.odp':    'application/vnd.oasis.opendocument.presentation'
	'.ods':    'application/vnd.oasis.opendocument.spreadsheet'
	'.odt':    'application/vnd.oasis.opendocument.text'
	'.oga':    'audio/ogg'
	'.ogv':    'video/ogg'
	'.ogx':    'application/ogg'
	'.opus':   'audio/opus'
	'.otf':    'font/otf'
	'.png':    'image/png'
	'.pdf':    'application/pdf'
	'.php':    'application/x-httpd-php'
	'.ppt':    'application/vnd.ms-powerpoint'
	'.pptx':   'application/vnd.openxmlformats-officedocument.presentationml.presentation'
	'.rar':    'application/vnd.rar'
	'.rtf':    'application/rtf'
	'.sh':     'application/x-sh'
	'.svg':    'image/svg+xml'
	'.swf':    'application/x-shockwave-flash'
	'.tar':    'application/x-tar'
	'.toml':   'application/toml'
	'.tif':    'image/tiff'
	'.tiff':   'image/tiff'
	'.ts':     'video/mp2t'
	'.ttf':    'font/ttf'
	'.txt':    'text/plain'
	'.vsd':    'application/vnd.visio'
	'.wasm':   'application/wasm'
	'.wav':    'audio/wav'
	'.weba':   'audio/webm'
	'.webm':   'video/webm'
	'.webp':   'image/webp'
	'.woff':   'font/woff'
	'.woff2':  'font/woff2'
	'.xhtml':  'application/xhtml+xml'
	'.xls':    'application/vnd.ms-excel'
	'.xlsx':   'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet'
	'.xml':    'application/xml'
	'.xul':    'application/vnd.mozilla.xul+xml'
	'.zip':    'application/zip'
	'.3gp':    'video/3gpp'
	'.3g2':    'video/3gpp2'
	'.7z':     'application/x-7z-compressed'
}

const max_http_post_size = 1024 * 1024

const default_port = 8080

fn controller #

fn controller[T](path string, global_app &T) &ControllerPath

controller generates a new Controller for the main app

fn controller_host #

fn controller_host[T](host string, path string, global_app &T) &ControllerPath

controller_host generates a controller which only handles incoming requests from the host domain

fn database_pool #

fn database_pool[T](params PoolParams[T]) DatabasePool[T]

database_pool creates a pool of database connections

fn not_found #

fn not_found() Result

Returns an empty result

fn run #

fn run[T](global_app &T, port int)

run - start a new VWeb server, listening to all available addresses, at the specified port

fn run_at #

fn run_at[T](global_app &T, params RunParams) !

run_at - start a new VWeb server, listening only on a specific address host, at the specified port

Example

vweb.run_at(new_app(), vweb.RunParams{ host: 'localhost' port: 8099 family: .ip }) or { panic(err) }

type DatabasePool #

type DatabasePool[T] = fn (tid int) T

type Middleware #

type Middleware = fn (mut Context) bool

type RawHtml #

type RawHtml = string

A type which don't get filtered inside templates

struct Context #

struct Context {
mut:
	content_type string = 'text/plain'
	status       string = '200 OK'
	ctx          context.Context = context.EmptyContext{}
pub:
	// HTTP Request
	req http.Request
	// TODO Response
pub mut:
	done bool
	// time.ticks() from start of vweb connection handle.
	// You can use it to determine how much time is spent on your request.
	page_gen_start i64
	// TCP connection to client.
	// But beware, do not store it for further use, after request processing vweb will close connection.
	conn              &net.TcpConn = unsafe { nil }
	static_files      map[string]string
	static_mime_types map[string]string
	static_hosts      map[string]string
	// Map containing query params for the route.
	// http://localhost:3000/index?q=vpm&order_by=desc => { 'q': 'vpm', 'order_by': 'desc' }
	query map[string]string
	// Multipart-form fields.
	form map[string]string
	// Files from multipart-form.
	files map[string][]http.FileData

	header http.Header // response headers
	// ? It doesn't seem to be used anywhere
	form_error                  string
	livereload_poll_interval_ms int = 250
}

The Context struct represents the Context which hold the HTTP request and response. It has fields for the query, form, files.

fn (Context) init_server #

fn (ctx Context) init_server()

Defining this method is optional. This method called at server start. You can use it for initializing globals.

fn (Context) before_request #

fn (ctx Context) before_request()

Defining this method is optional. This method is called before every request (aka middleware). You can use it for checking user session cookies or to add headers.

fn (Context) send_response_to_client #

fn (mut ctx Context) send_response_to_client(mimetype string, res string) bool

TODO - test vweb intern function

fn (Context) html #

fn (mut ctx Context) html(payload string) Result

Response HTTP_OK with payload with content-type text/html

fn (Context) text #

fn (mut ctx Context) text(s string) Result

Response HTTP_OK with s as payload with content-type text/plain

fn (Context) json #

fn (mut ctx Context) json[T](j T) Result

Response HTTP_OK with json_s as payload with content-type application/json

fn (Context) json_pretty #

fn (mut ctx Context) json_pretty[T](j T) Result

Response HTTP_OK with a pretty-printed JSON result

fn (Context) file #

fn (mut ctx Context) file(f_path string) Result

TODO - test Response HTTP_OK with file as payload

fn (Context) ok #

fn (mut ctx Context) ok(s string) Result

Response HTTP_OK with s as payload

fn (Context) server_error #

fn (mut ctx Context) server_error(ecode int) Result

TODO - test Response a server error

fn (Context) redirect #

fn (mut ctx Context) redirect(url string, params RedirectParams) Result

Redirect to an url

fn (Context) not_found #

fn (mut ctx Context) not_found() Result

Send an not_found response

fn (Context) set_cookie #

fn (mut ctx Context) set_cookie(cookie http.Cookie)

TODO - test Sets a cookie

fn (Context) set_content_type #

fn (mut ctx Context) set_content_type(typ string)

Sets the response content type

fn (Context) set_cookie_with_expire_date #

fn (mut ctx Context) set_cookie_with_expire_date(key string, val string, expire_date time.Time)

TODO - test Sets a cookie with a expire_date

fn (Context) get_cookie #

fn (ctx &Context) get_cookie(key string) !string

Gets a cookie by a key

fn (Context) set_status #

fn (mut ctx Context) set_status(code int, desc string)

TODO - test Sets the response status

fn (Context) add_header #

fn (mut ctx Context) add_header(key string, val string)

TODO - test Adds an header to the response with key and val

fn (Context) get_header #

fn (ctx &Context) get_header(key string) string

TODO - test Returns the header data from the key

fn (Context) set_value #

fn (mut ctx Context) set_value(key context.Key, value context.Any)

set_value sets a value on the context

fn (Context) get_value #

fn (ctx &Context) get_value[T](key context.Key) ?T

get_value gets a value from the context

fn (Context) handle_static #

fn (mut ctx Context) handle_static(directory_path string, root bool) bool

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 '/' Usage:

os.chdir( os.executable() )? app.handle_static('assets', true)

fn (Context) host_handle_static #

fn (mut ctx Context) host_handle_static(host string, directory_path string, root bool) bool

host_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 '/' Usage:

os.chdir( os.executable() )? app.host_handle_static('localhost', 'assets', true)

fn (Context) mount_static_folder_at #

fn (mut ctx Context) mount_static_folder_at(directory_path string, mount_path string) bool

TODO - test 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 .

fn (Context) host_mount_static_folder_at #

fn (mut ctx Context) host_mount_static_folder_at(host string, directory_path string, mount_path string) bool

TODO - test host_mount_static_folder_at - makes all static files in directory_path and inside it, available at http://host/mount_path For example: suppose you have called .host_mount_static_folder_at('localhost', '/var/share/myassets', '/assets'), and you have a file /var/share/myassets/main.css . => That file will be available at URL: http://localhost/assets/main.css .

fn (Context) serve_static #

fn (mut ctx Context) serve_static(url string, file_path string)

TODO - test 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

fn (Context) host_serve_static #

fn (mut ctx Context) host_serve_static(host string, url string, file_path string)

TODO - test 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, host is the host to serve the file from

fn (Context) user_agent #

fn (ctx &Context) user_agent() string

user_agent returns the user-agent header for the current client

fn (Context) ip #

fn (ctx &Context) ip() string

Returns the ip address from the current user

fn (Context) error #

fn (mut ctx Context) error(s string)

Set s to the form error

struct Controller #

struct Controller {
pub mut:
	controllers []&ControllerPath
}

struct ControllerPath #

struct ControllerPath {
pub:
	path    string
	handler ControllerHandler = unsafe { nil }
pub mut:
	host string
}

struct PoolParams #

struct PoolParams[T] {
	handler    fn () T = unsafe { nil } @[required]
	nr_workers int = runtime.nr_jobs()
}

struct RedirectParams #

struct RedirectParams {
	status_code int = 302
}

struct Result #

struct Result {}

A dummy structure that returns from routes to indicate that you actually sent something to a user

struct RunParams #

struct RunParams {
	family               net.AddrFamily = .ip6 // use `family: .ip, host: 'localhost'` when you want it to bind only to 127.0.0.1
	host                 string
	port                 int  = 8080
	nr_workers           int  = runtime.nr_jobs()
	pool_channel_slots   int  = 1000
	show_startup_message bool = true
}

README
Constants
fn controller
fn controller_host
fn database_pool
fn not_found
fn run
fn run_at
type DatabasePool
type Middleware
type RawHtml
struct Context
struct Controller
struct ControllerPath
struct PoolParams
struct RedirectParams
struct Result
struct RunParams

vweb #

vweb - the V Web Server

Quick Start

Features

Examples

Deploying vweb apps

Getting Started

Defining endpoints

- HTTP verbs

- Parameters

- Parameter Arrays

- Query

- Host

Middleware

Middleware evaluation order

Context values

Changing Context values

Redirect

Custom not found page

Databases

Multithreading

Database Pool

Extending the App struct with [vweb_global]

Shared Objects across requests

Drawback of Shared Objects

Controllers

Routing

Hosts

Databases and [vweb_global] in controllers

Using a database pool

Responses

- set_status

- html

- text

- json

- json_pretty

- file

- ok

- server_error

- not_found

Requests

- get_header

- get_cookie

- add_header

- set_cookie

- set_cookie_with_expire_date

- set_content_type

Template

-handle_static

-mount_static_folder_at

-serve_static

Others

-user_agent

-ip

-error

Cross-Site Request Forgery (CSRF) protection

Constants #

fn controller #

fn controller_host #

fn database_pool #

fn not_found #

fn run #

fn run_at #

Example

type DatabasePool #

type Middleware #

type RawHtml #

struct Context #

fn (Context) init_server #

fn (Context) before_request #

fn (Context) send_response_to_client #

fn (Context) html #

fn (Context) text #

fn (Context) json #

fn (Context) json_pretty #

fn (Context) file #

fn (Context) ok #

fn (Context) server_error #

fn (Context) redirect #

fn (Context) not_found #

Extending the App struct with `[vweb_global]`

Databases and `[vweb_global]` in controllers