vweb - the V Web Server

A simple yet powerful web server with built-in routing, parameter handling, templating, and other features.

Alpha level software

Some features may not be complete, and there may still be bugs. However, it is still a very useful tool. The gitly site is based on vweb.

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.

There is no formal documentation yet - here is a simple example

There's also the V forum, vorum

vorum.v contains all GET and POST actions.

pub fn (app mut App) index() {
    posts := app.find_all_posts()
    $vweb.html()
}

// TODO ['/post/:id/:title']
// TODO `fn (app App) post(id int)`
pub fn (app App) post() {
    id := app.get_post_id()
    post := app.retrieve_post(id) or {
        app.redirect('/')
        return
    }
    comments := app.find_comments(id)
    show_form := true
    $vweb.html()
}

index.html is an example of the V template language:

@for post in posts
    <div class=post>
        <a class=topic href="@post.url">@post.title</a>
        <img class=comment-img>
        <span class=nr-comments>@post.nr_comments</span>
        <span class=time>@post.time</span>
    </div>
@end

$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.

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. After the import, 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).

Example:

import vweb

struct App {
    vweb.Context
}

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

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')
}

To create an HTTP POST endpoint, you simply add a [post] attribute before the function definition.

Example:

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

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:

['/hello/:user']
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, e.g. app.req.header.get(.content_type). See struct Header for all available methods (v doc net.http Header).

fn not_found() Result

Returns an empty result

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<T>(global_app &T, params RunParams) ?

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

vweb.run_at(app, 'localhost', 8099)

type RawHtml = string

A type which don't get filtered inside templates

struct Context {
mut:
	content_type string = 'text/plain'
	status       string = '200 OK'
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
	static_files      map[string]string
	static_mime_types 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
}

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

fn (ctx Context) init_server()

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

fn (ctx Context) before_request()

Defining this method is optional.
This method called before every request (aka middleware).
Probably you can use it for check user session cookie or add header.

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

vweb intern function

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

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

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

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

fn (mut ctx Context) json<T>(j T) Result

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

fn (mut ctx Context) json_pretty<T>(j T) Result

Response HTTP_OK with a pretty-printed JSON result

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

Response HTTP_OK with file as payload

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

Response HTTP_OK with s as payload

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

Response a server error

fn (mut ctx Context) redirect(url string) Result

Redirect to an url

fn (mut ctx Context) not_found() Result

Send an not_found response

fn (mut ctx Context) set_cookie(cookie Cookie)

Sets a cookie

fn (mut ctx Context) set_content_type(typ string)

Sets the response content type

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

Sets a cookie with a expire_data

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

Gets a cookie by a key

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

Sets the response status

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

Adds an header to the response with key and val

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

Returns the header data from the key

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 (mut ctx Context) mount_static_folder_at(directory_path string, mount_path string) bool

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 (mut ctx Context) serve_static(url string, file_path string)

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 (ctx &Context) ip() string

Returns the ip address from the current user

fn (mut ctx Context) error(s string)

Set s to the form error

struct Cookie {
	name      string
	value     string
	expires   time.Time
	secure    bool
	http_only bool
}

struct Result {}

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

struct RunParams {
	host   string
	port   int = 8080
	family net.AddrFamily = .ip6 // use `family: .ip, host: 'localhost'` when you want it to bind only to 127.0.0.1
}