goyave

README

An Elegant Golang Web Framework

Note: This repository contains the core code of the Goyave framework. If you want to build a Goyave application, visit the Goyave Template Project repository.

Goyave is a progressive and accessible web application framework, aimed at making development easy and enjoyable. It has a philosophy of cleanliness and conciseness to make programs more elegant, easier to maintain and more focused.

Clean Goyave has an expressive and elegant syntax. Minimalist calls and reduced redundancy are among the Goyave's core principles.

Fast Develop faster thanks to concise and clear syntax. Low complexity functions allow for better performance.

Powerful Goyave is accessible, yet powerful, and provides many helpers and built-in functions to make your life easier and let you concentrate on the business logic.

Learning Goyave

The Goyave framework has an extensive documentation covering in-depth subjects and teaching you how to run a project using Goyave from setup to deployment.

Read the documentation

Requirements

• Go 1.13+
• Go modules

Contributing

Thank you for considering contributing to the Goyave framework! You can find the contribution guide in the documentation.

I have many ideas for the future of Goyave. I would be infinitely grateful to whoever want to support me and let me continue working on Goyave and making it better and better.

You can support also me on Patreon:

License

The Goyave framework is MIT Licensed. Copyright © 2019 Jérémy LAMBERT (SystemGlitch)

Documentation

Index

• func ClearStartupHooks()
• func IsReady() bool
• func RegisterStartupHook(hook func())
• func Start(routeRegistrer func(*Router))
• func Stop()
• type Handler
• type Middleware
• type Request
  • func (r *Request) ContentLength() int64
  • func (r *Request) Cookies(name string) []*http.Cookie
  • func (r *Request) Header() http.Header
  • func (r *Request) Method() string
  • func (r *Request) Protocol() string
  • func (r *Request) Referrer() string
  • func (r *Request) RemoteAddress() string
  • func (r *Request) URL() *url.URL
  • func (r *Request) UserAgent() string
• type Response
  • func CreateTestResponse(recorder http.ResponseWriter) *Response
  • func (r *Response) Cookie(cookie *http.Cookie)
  • func (r *Response) Download(file string, fileName string)
  • func (r *Response) Error(err interface{})
  • func (r *Response) File(file string)
  • func (r *Response) Header() http.Header
  • func (r *Response) JSON(responseCode int, data interface{})
  • func (r *Response) Redirect(url string)
  • func (r *Response) Status(status int)
  • func (r *Response) String(responseCode int, message string)
  • func (r *Response) TemporaryRedirect(url string)
  • func (r *Response) Write(data []byte)
• type Router
  • func (r *Router) Middleware(middleware ...Middleware)
  • func (r *Router) Route(methods string, uri string, handler Handler, ...)
  • func (r *Router) Static(uri string, directory string, download bool)
  • func (r *Router) Subrouter(prefix string) *Router

Functions

func ClearStartupHooks

func ClearStartupHooks()

ClearStartupHooks removes all startup hooks.

func IsReady

func IsReady() bool

IsReady returns true if the server has finished initializing and is ready to serve incoming requests.

func RegisterStartupHook

func RegisterStartupHook(hook func())

RegisterStartupHook to execute some code once the server is ready and running.

func Start

func Start(routeRegistrer func(*Router))

Start starts the web server. The routeRegistrer parameter is a function aimed at registering all your routes and middlewares.

 import (
     "github.com/System-Glitch/goyave"
     "routes"
 )

 func main() {
	    goyave.start(routes.Register)
 }

func Stop

func Stop()

Stop gracefully shuts down the server without interrupting any active connections.

Make sure the program doesn't exit and waits instead for Stop to return.

Stop does not attempt to close nor wait for hijacked connections such as WebSockets. The caller of Stop should separately notify such long-lived connections of shutdown and wait for them to close, if desired.

Types

type Handler

type Handler func(*Response, *Request)

Handler is a controller or middleware function

type Middleware

type Middleware func(Handler) Handler

Middleware function generating middleware handler function.

Request data is available to middlewares, but bear in mind that it had not been validated yet. That means that you can modify or filter data. (Trim strings for example)

type Request

type Request struct {
	Rules  validation.RuleSet
	Data   map[string]interface{}
	Params map[string]string
	Lang   string
	// contains filtered or unexported fields
}

Request struct represents an http request. Contains the validated body in the Data attribute if the route was defined with a request generator function

func (*Request) ContentLength

func (r *Request) ContentLength() int64

ContentLength records the length of the associated content. The value -1 indicates that the length is unknown.

func (*Request) Cookies

func (r *Request) Cookies(name string) []*http.Cookie

Cookies returns the HTTP cookies sent with the request.

func (*Request) Header

func (r *Request) Header() http.Header

Header contains the request header fields either received by the server or to be sent by the client. Header names are case-insensitive.

If the raw request has the following header lines,

Host: example.com
accept-encoding: gzip, deflate
Accept-Language: en-us
fOO: Bar
foo: two

then the header map will look like this:

Header = map[string][]string{
	"Accept-Encoding": {"gzip, deflate"},
	"Accept-Language": {"en-us"},
	"Foo": {"Bar", "two"},
}

func (*Request) Method

func (r *Request) Method() string

Method specifies the HTTP method (GET, POST, PUT, etc.).

func (*Request) Protocol

func (r *Request) Protocol() string

Protocol the protocol used by this request, "HTTP/1.1" for example.

func (*Request) Referrer

func (r *Request) Referrer() string

Referrer returns the referring URL, if sent in the request.

func (*Request) RemoteAddress

func (r *Request) RemoteAddress() string

RemoteAddress allows to record the network address that sent the request, usually for logging.

func (*Request) URL

func (r *Request) URL() *url.URL

URL specifies the URI being requested. Use this if you absolutely need the raw query params, url, etc. Otherwise use the provided methods and fields of the "goyave.Request".

func (*Request) UserAgent

func (r *Request) UserAgent() string

UserAgent returns the client's User-Agent, if sent in the request.

type Response

type Response struct {
	// contains filtered or unexported fields
}

Response represents a controller response.

func CreateTestResponse

func CreateTestResponse(recorder http.ResponseWriter) *Response

CreateTestResponse create an empty response with the given response writer. This function is aimed at making it easier to unit test Responses.

writer := httptest.NewRecorder()
response := goyave.CreateTestResponse(writer)
response.Status(http.StatusNoContent)
result := writer.Result()
fmt.Println(result.StatusCode) // 204

func (*Response) Cookie

func (r *Response) Cookie(cookie *http.Cookie)

Cookie add a Set-Cookie header to the response. The provided cookie must have a valid Name. Invalid cookies may be silently dropped.

func (*Response) Download

func (r *Response) Download(file string, fileName string)

Download write a file as an attachment element. Automatically detects the file MIME type and sets the "Content-Type" header accordingly. It is advised to call "filesystem.FileExists()" before sending a file to avoid a panic and return a 404 error if the file doesn't exist. The given path can be relative or absolute.

The "fileName" parameter defines the name the client will see. In other words, it sets the header "Content-Disposition" to "attachment; filename="${fileName}""

If you want the file to be sent as an inline element ("Content-Disposition: inline"), use the "File" function instead.

func (*Response) Error

func (r *Response) Error(err interface{})

Error print the error in the console and return it with an error code 500. If debugging is enabled in the config, the error is also written in the response and the stacktrace is printed in the console.

func (*Response) File

func (r *Response) File(file string)

File write a file as an inline element. Automatically detects the file MIME type and sets the "Content-Type" header accordingly. It is advised to call "filesystem.FileExists()" before sending a file to avoid a panic and return a 404 error if the file doesn't exist. The given path can be relative or absolute.

If you want the file to be sent as a download ("Content-Disposition: attachment"), use the "Download" function instead.

func (*Response) Header

func (r *Response) Header() http.Header

Header returns the header map that will be sent.

func (*Response) JSON

func (r *Response) JSON(responseCode int, data interface{})

JSON write json data as a response. Also sets the "Content-Type" header automatically

func (*Response) Redirect

func (r *Response) Redirect(url string)

Redirect send a permanent redirect response

func (*Response) Status

func (r *Response) Status(status int)

Status write the given status code

func (*Response) String

func (r *Response) String(responseCode int, message string)

String write a string as a response

func (*Response) TemporaryRedirect

func (r *Response) TemporaryRedirect(url string)

TemporaryRedirect send a temporary redirect response

func (*Response) Write

func (r *Response) Write(data []byte)

Write writes the data as a response.

type Router

type Router struct {
	// contains filtered or unexported fields
}

Router registers routes to be matched and dispatches a handler.

func (*Router) Middleware

func (r *Router) Middleware(middleware ...Middleware)

Middleware apply one or more middleware(s) to the route group.

func (*Router) Route

func (r *Router) Route(methods string, uri string, handler Handler, validationRules validation.RuleSet)

Route register a new route.

Multiple methods can be passed using a pipe-separated string.

"PUT|PATCH"

The validation rules set is optional. If you don't want your route to be validated, pass "nil".

func (*Router) Static

func (r *Router) Static(uri string, directory string, download bool)

Static serve a directory and its subdirectories of static resources. Set the "download" parameter to true if you want the files to be sent as an attachment instead of an inline element.

If no file is given in the url, or if the given file is a directory, the handler will send the "index.html" file if it exists.

func (*Router) Subrouter

func (r *Router) Subrouter(prefix string) *Router

Subrouter create a new sub-router from this router. Use subrouters to create route groups and to apply middleware to multiple routes.