Documentation ¶
Overview ¶
Microbo is a micro framework to create micro API webservers in go. A webserver that use Microbo require a very minimal configuration (just create a .env file) and support a DB connection, CORS, authentication with JWT and HTTP2 out of the box.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Conf ¶
type Conf struct { // Pointer to gorm ORM database. // See https://pkg.go.dev/gorm.io/gorm#DB DB *gorm.DB // Set a custom user model. The custom user model must implement the interface UserModel. Here and example: // type FullUser struct { // UID uint `gorm:"auto_increment;primary_key"` // Mail string // EncPassword string // Username string // Role bool // } // // func (u FullUser) GetID() uint { // return u.UID // } // // func (u FullUser) GetEmail() string { // return u.Mail // } // // func (u FullUser) GetPassword() string { // return u.EncPassword // } // // func (FullUser) TableName() string { // return "user" // } // // func (FullUser) EmailColumnName() string { // return "mail" // } // // func (user *FullUser) ID(id uint) { // user.UID = id // } // // // Used for copier (see https://github.com/jinzhu/copier) // func (user *FullUser) Email(email string) { // user.Mail = email // } // // // Used for copier (see https://github.com/jinzhu/copier) // func (user *FullUser) Password(password string) { // user.EncPassword = password // } // // func (u FullUser) MarshalJSON() ([]byte, error) { // return json.Marshal(struct { // ID uint `json:"id"` // Mail string `json:"mail"` // Username string `json:"username"` // RandToken string `json:"rand_token"` // }{ // ID: u.UID, // Mail: u.Mail, // Username: u.Username, // RandToken: "RAND TOKEN", // }) // } // // conf := microbo.Conf{UserModel: &FullUser{}} // server := microbo.NewServerWithOpts(&conf) // server.Run() // The /auth/login endpoint will return the user json defined by // FullUser#MarshalJSON. UserModel UserModel // The Log middleware // See https://godoc.org/github.com/gorilla/mux#Router.Use LogMiddleware mux.MiddlewareFunc // The Timeout middleware. The default use http.TimeoutHandler with dt // parameters set to 2 seconds. // See https://godoc.org/net/http#TimeoutHandler // See https://godoc.org/github.com/gorilla/mux#Router.Use // An example to change the timeout: // conf := microbo.Conf{ // TimeoutMiddleware: func(next http.Handler) http.Handler { // return http.TimeoutHandler(next, 60*time.Second, "Timeout") // }, // } TimeoutMiddleware mux.MiddlewareFunc // ReadTimeout is the maximum duration for reading the entire request, // including the body. // See https://godoc.org/net/http#Server ReadTimeout *time.Duration // WriteTimeout is the maximum duration before timing out writes of the // response. // See https://godoc.org/net/http#Server WriteTimeout *time.Duration }
type DefaultUser ¶
type DefaultUser struct { ID uint `json:"id"` Email string `json:"email"` Password string `json:"-"` }
The default user struct used to manage users. However, you can always use your own user model (see below).
func (DefaultUser) EmailColumnName ¶
func (DefaultUser) EmailColumnName() string
Return the user email column name in your DB. Default "email".
func (DefaultUser) GetEmail ¶
func (u DefaultUser) GetEmail() string
Return the email of user record as string.
func (DefaultUser) GetPassword ¶
func (u DefaultUser) GetPassword() string
Return the encrypted password of user record as string.
func (DefaultUser) TableName ¶
func (DefaultUser) TableName() string
Return the user table name in your DB. Default "users".
type Server ¶
type Server struct { // http.Server variable. See https://godoc.org/net/http#Server http.Server // Router registers routes to be matched and dispatches a handler. See // https://godoc.org/github.com/gorilla/mux#Router Router *mux.Router // Pointer to gorm ORM database. See // https://pkg.go.dev/gorm.io/gorm#DB DB *gorm.DB // The path of the public folder. Files inside will be serverd as static // files. RootPath string // contains filtered or unexported fields }
The base server struct. It contains the Router and the DB access.
func NewServer ¶
Create a new Microbo server.
Microbo uses config enviroment variables that can be store in a handy .env file. The available env variables are:
- CERT_FILE: path to the certificate file (.pem). For dev purpose you can use mkcert (https://github.com/FiloSottile/mkcert).
- CERT_KEY: path to the certificate key file (.pem).
- DB_CONNECTION: a Gorm database connection string (es: "root@tcp(127.0.0.1:3306)/testdb?charset=utf8mb4&parseTime=True").
- ROOT_PATH: path of the public root path. Files inside will be served as static files.
- ROOT_PATH_ENDPOINT: URL path to access public files (es: /public/).
- SERVER_ADDR: the server address with port (es: 127.0.0.1:3000).
- JWT_KEY: the JWT key used to sign tokens.
func NewServerWithOpts ¶
Create a new Microbo server with configuration options.
func (*Server) HandleFunc ¶
HandleFunc registers the handler function for the given pattern in the mux Router. The documentation for ServeMux explains how patterns are matched. See https://godoc.org/net/http#HandleFunc
func (*Server) HandleFuncWithAuth ¶
func (server *Server) HandleFuncWithAuth(method, path string, f func(http.ResponseWriter, *http.Request))
Handles registered with HandleFuncWithAuth must be requested with a valid JWT bearer token. Inside the handler you can retrieve the authenticated userId with
userId := r.Context().Value("user_id").(uint)
Built in authentication endpoints are:
// Register a new user curl --location --request POST 'https://localhost:3000/auth/register' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "epilotto@gmx.com", "password": "qwerty" }'
Return 200 if user has successfully registered, or other http error codes if not. No body will be returned in the response.
// Get a new JWT token curl --location --request POST 'https://localhost:3000/auth/login' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "epilotto@gmx.com", "password": "qwerty" }'
Return 200 and the json with user data if user has successfully autheticated. The token will be present in the header under the X-Token key.
// Refresh a JWT token curl --location --request POST 'https://localhost:3000/auth/refresh' \ --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJVc2VySWQiOjExLCJleHAiOjE1ODc2NzIzOTl9.vEoYBueacCA_JQkPmDCwpfIutsC5jQmYfL692q0Nrrk' \ --header 'Content-Type: application/json'
Return 200 if the token has successfully refreshed. The new token will be present in the header under the X-Token key. No body will be returned in the response.
Also, these endpoints and the authentication with JWT token are enabled only if exists the env variable JWT_KEY and a database table named "users" with the columns "id", "email" and "password". Password will be stored as a bcrypt hash.