ami/tl-vikunja
1
0
Fork 0
Code Activity

chore(web): move web handler package to Vikunja

Browse Source 
(cherry picked from commit 2063da9eecf8d0980a62106a627d7f00da172138)
This commit is contained in:
kolaente
2024-08-29 16:15:28 +02:00
parent cfa58ae599
commit 4c73c74587
111 changed files with 1016 additions and 136 deletions
Download Patch File Download Diff File Expand all files Collapse all files

57
pkg/web/handler/config.go Normal file
View File

@ -0,0 +1,57 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package handler
import (
"code.vikunja.io/api/pkg/web"
"github.com/op/go-logging"
"xorm.io/xorm"
)
// Config contains the config for the web handler
type Config struct {
AuthProvider *web.Auths
LoggingProvider *logging.Logger
MaxItemsPerPage int
SessionFactory func() *xorm.Session
}
var config *Config
func init() {
config = &Config{}
}
// SetAuthProvider sets the auth provider in config
func SetAuthProvider(provider *web.Auths) {
config.AuthProvider = provider
}
// SetLoggingProvider sets the logging provider in the config
func SetLoggingProvider(logger *logging.Logger) {
config.LoggingProvider = logger
}
// SetMaxItemsPerPage sets the max number of items per page in the config
func SetMaxItemsPerPage(maxItemsPerPage int) {
config.MaxItemsPerPage = maxItemsPerPage
}
// SetSessionFactory sets the session factory
func SetSessionFactory(sessionFactory func() *xorm.Session) {
config.SessionFactory = sessionFactory
}

89
pkg/web/handler/create.go Normal file
View File

@ -0,0 +1,89 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package handler
import (
"fmt"
"net/http"
"github.com/labstack/echo/v4"
)
// CreateWeb is the handler to create an object
func (c *WebHandler) CreateWeb(ctx echo.Context) error {
// Get our model
currentStruct := c.EmptyStruct()
// Get the object & bind params to struct
if err := ctx.Bind(currentStruct); err != nil {
config.LoggingProvider.Debugf("Invalid model error. Internal error was: %s", err.Error())
if he, is := err.(*echo.HTTPError); is {
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided. Error was: %s", he.Message))
}
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided."))
}
// Validate the struct
if err := ctx.Validate(currentStruct); err != nil {
return echo.NewHTTPError(http.StatusBadRequest, err)
}
// Get the user to pass for later checks
currentAuth, err := config.AuthProvider.AuthObject(ctx)
if err != nil {
return echo.NewHTTPError(http.StatusInternalServerError, "Could not determine the current user.")
}
// Create the db session
s := config.SessionFactory()
defer func() {
err = s.Close()
if err != nil {
config.LoggingProvider.Errorf("Could not close session: %s", err)
}
}()
// Check rights
canCreate, err := currentStruct.CanCreate(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
if !canCreate {
_ = s.Rollback()
config.LoggingProvider.Noticef("Tried to create while not having the rights for it (User: %v)", currentAuth)
return echo.NewHTTPError(http.StatusForbidden)
}
// Create
err = currentStruct.Create(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
err = s.Commit()
if err != nil {
return HandleHTTPError(err, ctx)
}
err = ctx.JSON(http.StatusCreated, currentStruct)
if err != nil {
return HandleHTTPError(err, ctx)
}
return err
}

87
pkg/web/handler/delete.go Normal file
View File

@ -0,0 +1,87 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package handler
import (
"fmt"
"net/http"
"github.com/labstack/echo/v4"
)
type message struct {
Message string `json:"message"`
}
// DeleteWeb is the web handler to delete something
func (c *WebHandler) DeleteWeb(ctx echo.Context) error {
// Get our model
currentStruct := c.EmptyStruct()
// Bind params to struct
if err := ctx.Bind(currentStruct); err != nil {
config.LoggingProvider.Debugf("Invalid model error. Internal error was: %s", err.Error())
if he, is := err.(*echo.HTTPError); is {
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided. Error was: %s", he.Message))
}
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided."))
}
// Check if the user has the right to delete
currentAuth, err := config.AuthProvider.AuthObject(ctx)
if err != nil {
return echo.NewHTTPError(http.StatusInternalServerError)
}
// Create the db session
s := config.SessionFactory()
defer func() {
err = s.Close()
if err != nil {
config.LoggingProvider.Errorf("Could not close session: %s", err)
}
}()
canDelete, err := currentStruct.CanDelete(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
if !canDelete {
_ = s.Rollback()
config.LoggingProvider.Noticef("Tried to delete while not having the rights for it (User: %v)", currentAuth)
return echo.NewHTTPError(http.StatusForbidden)
}
err = currentStruct.Delete(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
err = s.Commit()
if err != nil {
return HandleHTTPError(err, ctx)
}
err = ctx.JSON(http.StatusOK, message{"Successfully deleted."})
if err != nil {
return HandleHTTPError(err, ctx)
}
return err
}

46
pkg/web/handler/helper.go Normal file
View File

@ -0,0 +1,46 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package handler
import (
"net/http"
"code.vikunja.io/api/pkg/web"
"github.com/labstack/echo/v4"
)
// WebHandler defines the webhandler object
// This does web stuff, aka returns json etc. Uses CRUDable Methods to get the data
type WebHandler struct {
EmptyStruct func() CObject
}
// CObject is the definition of our object, holds the structs
type CObject interface {
web.CRUDable
web.Rights
}
// HandleHTTPError does what it says
func HandleHTTPError(err error, ctx echo.Context) *echo.HTTPError {
config.LoggingProvider.Error(err.Error())
if a, has := err.(web.HTTPErrorProcessor); has {
errDetails := a.HTTPError()
return echo.NewHTTPError(errDetails.HTTPCode, errDetails)
}
return echo.NewHTTPError(http.StatusInternalServerError)
}

129
pkg/web/handler/read_all.go Normal file
View File

@ -0,0 +1,129 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package handler
import (
"fmt"
"math"
"net/http"
"strconv"
"github.com/labstack/echo/v4"
)
// ReadAllWeb is the webhandler to get all objects of a type
func (c *WebHandler) ReadAllWeb(ctx echo.Context) error {
// Get our model
currentStruct := c.EmptyStruct()
currentAuth, err := config.AuthProvider.AuthObject(ctx)
if err != nil {
return echo.NewHTTPError(http.StatusInternalServerError, "Could not determine the current user.")
}
// Get the object & bind params to struct
if err := ctx.Bind(currentStruct); err != nil {
config.LoggingProvider.Debugf("Invalid model error. Internal error was: %s", err.Error())
if he, is := err.(*echo.HTTPError); is {
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided. Error was: %s", he.Message))
}
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided."))
}
// Pagination
page := ctx.QueryParam("page")
if page == "" {
page = "1"
}
pageNumber, err := strconv.Atoi(page)
if err != nil {
config.LoggingProvider.Error(err.Error())
return echo.NewHTTPError(http.StatusBadRequest, "Bad page requested.")
}
if pageNumber < 0 {
return echo.NewHTTPError(http.StatusBadRequest, "Page number cannot be negative.")
}
// Items per page
var perPageNumber int
perPage := ctx.QueryParam("per_page")
// If we dont have an "items per page" parameter, we want to use the default.
// To prevent Atoi from failing, we check this here.
if perPage != "" {
perPageNumber, err = strconv.Atoi(perPage)
if err != nil {
config.LoggingProvider.Error(err.Error())
return echo.NewHTTPError(http.StatusBadRequest, "Bad per page amount requested.")
}
}
// Set default page count
if perPageNumber == 0 {
perPageNumber = config.MaxItemsPerPage
}
if perPageNumber < 1 {
return echo.NewHTTPError(http.StatusBadRequest, "Per page amount cannot be negative.")
}
if perPageNumber > config.MaxItemsPerPage {
perPageNumber = config.MaxItemsPerPage
}
// Create the db session
s := config.SessionFactory()
defer func() {
err = s.Close()
if err != nil {
config.LoggingProvider.Errorf("Could not close session: %s", err)
}
}()
// Search
search := ctx.QueryParam("s")
result, resultCount, numberOfItems, err := currentStruct.ReadAll(s, currentAuth, search, pageNumber, perPageNumber)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
// Calculate the number of pages from the number of items
// We always round up, because if we don't have a number of items which is exactly dividable by the number of items per page,
// we would get a result that is one page off.
var numberOfPages = math.Ceil(float64(numberOfItems) / float64(perPageNumber))
// If we return all results, we only have one page
if pageNumber < 0 {
numberOfPages = 1
}
// If we don't have results, we don't have a page
if resultCount == 0 {
numberOfPages = 0
}
ctx.Response().Header().Set("x-pagination-total-pages", strconv.FormatFloat(numberOfPages, 'f', 0, 64))
ctx.Response().Header().Set("x-pagination-result-count", strconv.FormatInt(int64(resultCount), 10))
ctx.Response().Header().Set("Access-Control-Expose-Headers", "x-pagination-total-pages, x-pagination-result-count")
err = s.Commit()
if err != nil {
return HandleHTTPError(err, ctx)
}
err = ctx.JSON(http.StatusOK, result)
if err != nil {
return HandleHTTPError(err, ctx)
}
return err
}

90
pkg/web/handler/read_one.go Normal file
View File

@ -0,0 +1,90 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package handler
import (
"fmt"
"net/http"
"strconv"
"github.com/labstack/echo/v4"
)
// ReadOneWeb is the webhandler to get one object
func (c *WebHandler) ReadOneWeb(ctx echo.Context) error {
// Get our model
currentStruct := c.EmptyStruct()
// Get the object & bind params to struct
if err := ctx.Bind(currentStruct); err != nil {
config.LoggingProvider.Debugf("Invalid model error. Internal error was: %s", err.Error())
if he, is := err.(*echo.HTTPError); is {
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided. Error was: %s", he.Message))
}
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided."))
}
// Check rights
currentAuth, err := config.AuthProvider.AuthObject(ctx)
if err != nil {
return echo.NewHTTPError(http.StatusInternalServerError, "Could not determine the current user.")
}
// Create the db session
s := config.SessionFactory()
defer func() {
err = s.Close()
if err != nil {
config.LoggingProvider.Errorf("Could not close session: %s", err)
}
}()
canRead, maxRight, err := currentStruct.CanRead(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
if !canRead {
_ = s.Rollback()
config.LoggingProvider.Noticef("Tried to read while not having the rights for it (User: %v)", currentAuth)
return echo.NewHTTPError(http.StatusForbidden, "You don't have the right to see this")
}
// Get our object
err = currentStruct.ReadOne(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
// Set the headers
if canRead {
ctx.Response().Header().Set("x-max-right", strconv.FormatInt(int64(maxRight), 10))
ctx.Response().Header().Set("Access-Control-Expose-Headers", "x-max-right")
}
err = s.Commit()
if err != nil {
return HandleHTTPError(err, ctx)
}
err = ctx.JSON(http.StatusOK, currentStruct)
if err != nil {
return HandleHTTPError(err, ctx)
}
return err
}

89
pkg/web/handler/update.go Normal file
View File

@ -0,0 +1,89 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package handler
import (
"fmt"
"net/http"
"github.com/labstack/echo/v4"
)
// UpdateWeb is the webhandler to update an object
func (c *WebHandler) UpdateWeb(ctx echo.Context) error {
// Get our model
currentStruct := c.EmptyStruct()
// Get the object & bind params to struct
if err := ctx.Bind(currentStruct); err != nil {
config.LoggingProvider.Debugf("Invalid model error. Internal error was: %s", err.Error())
if he, is := err.(*echo.HTTPError); is {
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided. Error was: %s", he.Message))
}
return echo.NewHTTPError(http.StatusBadRequest, fmt.Sprintf("Invalid model provided."))
}
// Validate the struct
if err := ctx.Validate(currentStruct); err != nil {
return echo.NewHTTPError(http.StatusBadRequest, err)
}
// Check if the user has the right to do that
currentAuth, err := config.AuthProvider.AuthObject(ctx)
if err != nil {
return echo.NewHTTPError(http.StatusInternalServerError, "Could not determine the current user.")
}
// Create the db session
s := config.SessionFactory()
defer func() {
err = s.Close()
if err != nil {
config.LoggingProvider.Errorf("Could not close session: %s", err)
}
}()
canUpdate, err := currentStruct.CanUpdate(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
if !canUpdate {
_ = s.Rollback()
config.LoggingProvider.Noticef("Tried to update while not having the rights for it (User: %v)", currentAuth)
return echo.NewHTTPError(http.StatusForbidden)
}
// Do the update
err = currentStruct.Update(s, currentAuth)
if err != nil {
_ = s.Rollback()
return HandleHTTPError(err, ctx)
}
err = s.Commit()
if err != nil {
return HandleHTTPError(err, ctx)
}
err = ctx.JSON(http.StatusOK, currentStruct)
if err != nil {
return HandleHTTPError(err, ctx)
}
return err
}

253
pkg/web/readme.md Normal file
View File

@ -0,0 +1,253 @@
# Vikunja Web Handler
[![License: LGPL v3](https://img.shields.io/badge/License-LGPL%20v3-blue.svg)](LICENSE)
[![Go Report Card](https://goreportcard.com/badge/code.vikunja.io/web)](https://goreportcard.com/report/code.vikunja.io/web)
> When I started Vikunja, I started like everyone else, by writing a bunch of functions to do the logic and then a bunch of
handler functions to parse the request data and call the implemented functions to do the logic and eventually return a dataset.
After I implemented some functions, I've decided to save me a lot of hassle and put most of that "parse the request and call a
processing function"-logic to a general interface to facilitate development and not having to have a lot of similar code all over the place.
This webhandler was built to be used in a REST-API, it takes and returns JSON, but can also be used in combination with own
other handler implementations, enabling a lot of flexibility while develeoping.
## Features
* Easy to use
* Built for REST-APIs
* Beautiful error handling built in
* Manages rights
* Pluggable authentication mechanisms
## Table of contents
* [Installation](#installation)
* [Todos](#todos)
* [DB Sessions](#db-sessions)
* [CRUDable](#crudable)
* [Rights](#rights)
* [Handler Config](#handler-config)
* [Auth](#auth)
* [Logging](#logging)
* [Full Example](#full-example)
* [Preprocessing](#preprocessing)
* [Pagination](#pagination)
* [Search](#search)
* [Standard web handler](#defining-routes-using-the-standard-web-handler)
* [Errors](#errors)
* [URL param binder](#how-the-url-param-binder-works)
### TODOs
* [x] Improve docs/Merge with the ones of Vikunja
* [x] Description of web.HTTPError
* [x] Rights methods should return errors (I know, this will break a lot of existing stuff)
* [ ] optional Before- and after-{load|update|create} methods which do some preprocessing/after processing like making human-readable names from automatically up counting consts
* [ ] "Magic": Check if a passed struct implements Crudable methods and use a general (user defined) function if not
## Installation
Using the web handler in your application is pretty straight forward, simply run `go get -u code.vikunja.io/web` and start using it.
In order to use the common web handler, the struct must implement the `web.CRUDable` and `web.Rights` interface.
To learn how to use the handler, take a look at the [handler config](#handler-config) [defining routes](#defining-routes-using-the-standard-web-handler)
## DB Sessions
Each request runs in its own db session.
This ensures each operation is one atomic entity without any side effects for concurrent requests happening at the same time.
The session is started at the beginning of the request, rolled back in case of any errors and comitted if no errors occur.
The rights methods get the same session (for the same request) as the actual crud methods.
See [`SessionFactory`](#sessionfactory) for docs about how to configure it.
## CRUDable
This interface defines methods to Create/Read/ReadAll/Update/Delete something. It is defined as followed:
```go
type CRUDable interface {
Create(*xorm.Session, Auth) error
ReadOne(*xorm.Session, Auth) error
ReadAll(s *xorm.Session, auth Auth, search string, page int, perPage int) (result interface{}, resultCount int, numberOfTotalItems int64, err error)
Update(*xorm.Session, Auth) error
Delete(*xorm.Session, Auth) error
}
```
Each of these methods gets called on an instance of a struct like so:
```go
func (l *List) ReadOne() (err error) {
*l, err = GetListByID(l.ID)
return
}
```
In that case, it takes the `ID` saved in the struct instance, gets the full list object and fills the original object with it.
(See [parambinder](#how-the-url-param-binder-works) to understand where that `ID` is coming from in that specific case).
All functions should behave like this, if they create or update something, the struct instance they are called on should
contain the created/updated struct instance. The only exception is `ReadAll()` which returns an interface.
Usually this method returns a slice of results because you cannot make an array of a set type (If you know a
way to do this, don't hesitate to [drop me a message](https://vikunja.io/en/contact/)).
## Rights
This interface defines methods to check for rights on structs. They accept an `Auth`-element as parameter and return a `bool` and `error`.
The `error` is handled [as usual](#errors).
The interface is defined as followed:
```go
type Rights interface {
CanRead(*xorm.Session, Auth) (bool, int, error) // The int is the max right the user has for this entity.
CanDelete(*xorm.Session, Auth) (bool, error)
CanUpdate(*xorm.Session, Auth) (bool, error)
CanCreate(*xorm.Session, Auth) (bool, error)
}
```
When using the standard web handler, all methods are called before their `CRUD` counterparts.
Use pointers for methods like `CanRead()` to get the base data of the model first, then check the right and then add addintional data.
The `CanRead` method should also return the max right a user has on this entity.
This number will be returned in the`x-max-right` header to enable user interfaces to show/hide ui elements based on the right the user has.
## Handler Config
The handler has some options which you can (and need to) configure.
#### Auth
`Auth` is an interface with some methods to decouple the action of getting the current user from the web handler.
The function defined via `Auths` should return a struct which implements the `Auth` interface.
To define the thing which gets the appropriate auth object, you need to call a middleware like so (After all auth middlewares were called):
#### Logging
You can provide your own instance of `logger.Logger` (using [go-logging](https://github.com/op/go-logging)) to the handler.
It will use this instance to log errors which are not better specified or things like users trying to do something they're
not allowed to do and so on.
#### MaxItemsPerPage
Contains the maximum number of items per page.
If the client requests more items than this, the number of items requested is set to this value.
See [pagination](#pagination) for more.
#### SessionFactory
To create a new session for each request, you need to call the `SetSessionFactory` method before any web request.
It has the following signature:
```go
func SetSessionFactory(sessionFactory func() *xorm.Session)
```
The closure will be called for every request.
#### Full Example
```go
handler.SetAuthProvider(&web.Auths{
AuthObject: func(echo.Context) (web.Auth, error) {
return models.GetCurrentUser(c) // Your functions
},
})
handler.SetLoggingProvider(&log.Log)
handler.SetSessionFactory(x.NewSession)
```
## Preprocessing
### Pagination
The `ReadAll`-method has a number of parameters:
```go
ReadAll(auth Auth, search string, page int, perPage int) (result interface{}, resultCount int, numberOfItems int64, err error)
```
The third parameter contains the requested page, the fourth parameter contains the number of items per page.
You should calculate the limits accordingly.
If the number of items per page are not set by the client, the web handler will pass the maximum number of items per page instead.
This makes items per page optional for clients.
Take a look at [the config section](#handler-config) for information on how to set that value.
You need to return a number of things:
* The result itself, usually a slice
* The number of items you return in `result`. Most of the time, this is just `len(result)`. You need to return this value to make the clients aware if they requested a number of items > max items per page.
* The total number of items available. We use the total number of items here and not the number pages so the implementations don't have to deal with calculating the number of pages from that. The total number of clients is then calculated and returned to the client, ite can then be used by the clients to build client-side pagination or similar.
* An error.
The number of items and the total number of pages available will be returned in the `x-pagination-total-pages` and `x-pagination-result-count` response headers.
_You should put this in your api documentation._
### Search
When using the `ReadAll`-method, the first parameter is a search term which should be used to search items of your struct.
You define the critera inside of that function.
Users can then pass the `?s=something` parameter to the url to search, _thats something you should put in your api documentation_.
As the logic for "give me everything" and "give me everything where the name contains 'something'" is mostly the same, we made
the decision to design the function like this, in order to keep the places with mostly the same logic as few as possible.
Also just adding `?s=query` to the url one already knows and uses is a lot more convenient.
## Defining routes using the standard web handler
You can define routes for the standard web handler like so:
`models.List` needs to implement `web.CRUDable` and `web.Rights`.
```go
listHandler := &crud.WebHandler{
EmptyStruct: func() crud.CObject {
return &models.List{}
},
}
a.GET("/lists", listHandler.ReadAllWeb)
a.GET("/lists/:list", listHandler.ReadOneWeb)
a.POST("/lists/:list", listHandler.UpdateWeb)
a.DELETE("/lists/:list", listHandler.DeleteWeb)
a.PUT("/namespaces/:namespace/lists", listHandler.CreateWeb)
```
The handler will take care of everything like parsing the request, checking rights, pretty-print errors and return appropriate responses.
## Errors
Error types with their messages and http-codes should be implemented by you somewhere in your application and then returned by
the appropriate function when an error occures. If the error type implements `HTTPError`, the server returns a user-friendly
error message when this error occours. This means it returns a good HTTP status code, a message, and an error code. The error
code should be unique across all error codes and can be used on the client to show a localized error message or do other stuff
based on the exact error the server returns. That way the client won't have to "guess" that the error message remains the same
over multiple versions of your application.
An `HTTPError` is defined as follows:
```go
type HTTPError struct {
HTTPCode int `json:"-"` // Can be any valid HTTP status code, I'd reccomend to use the constants of the http package.
Code int `json:"code"` // Must be a uniqe int identifier for this specific error. I'd reccomend defining a constant for this.
Message string `json:"message"` // A user-readable message what went wrong.
}
```
You can learn more about how exactly custom error types are created in the [vikunja docs](https://vikunja.io/docs/custom-errors/).
## How the url param binder works
The binder binds all values inside the url to their respective fields in a struct. Those fields need to have a tag
`param` with the name of the url placeholder which must be the same as in routes.
Whenever one of the standard CRUD methods is invoked, this binder is called, which enables one handler method
to handle all kinds of different urls with different parameters.

67
pkg/web/web.go Normal file
View File

@ -0,0 +1,67 @@
// Vikunja is a to-do list application to facilitate your life.
// Copyright 2018-present Vikunja and contributors. All rights reserved.
//
// This program is free software: you can redistribute it and/or modify
// it under the terms of the GNU Affero General Public Licensee as published by
// the Free Software Foundation, either version 3 of the License, or
// (at your option) any later version.
//
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
// GNU Affero General Public Licensee for more details.
//
// You should have received a copy of the GNU Affero General Public Licensee
// along with this program. If not, see <https://www.gnu.org/licenses/>.
package web
import (
"github.com/labstack/echo/v4"
"xorm.io/xorm"
)
// Rights defines rights methods
type Rights interface {
CanRead(*xorm.Session, Auth) (bool, int, error)
CanDelete(*xorm.Session, Auth) (bool, error)
CanUpdate(*xorm.Session, Auth) (bool, error)
CanCreate(*xorm.Session, Auth) (bool, error)
}
// CRUDable defines the crud methods
type CRUDable interface {
Create(*xorm.Session, Auth) error
ReadOne(*xorm.Session, Auth) error
ReadAll(s *xorm.Session, auth Auth, search string, page int, perPage int) (result interface{}, resultCount int, numberOfTotalItems int64, err error)
Update(*xorm.Session, Auth) error
Delete(*xorm.Session, Auth) error
}
// HTTPErrorProcessor is executed when the defined error is thrown, it will make sure the user sees an appropriate error message and http status code
type HTTPErrorProcessor interface {
HTTPError() HTTPError
}
// HTTPError holds informations about an http error
type HTTPError struct {
HTTPCode int `json:"-"`
Code int `json:"code"`
Message string `json:"message"`
}
// Auth defines the authentication interface used to get some auth thing
type Auth interface {
// Most of the time, we need an ID from the auth object only. Having this method saves the need to cast it.
GetID() int64
}
// Authprovider is a holder for the implementation of an authprovider by the application
type Authprovider interface {
GetAuthObject(echo.Context) (Auth, error)
}
// Auths holds the authobject
type Auths struct {
AuthObject func(echo.Context) (Auth, error)
}