charasheet-go

This is now archived. It was only intended as an experiment and has served its purpose.

README

This codebase has been generated by Autostrada.

Getting started

Make sure that you're in the root of the project directory, fetch the dependencies with go mod tidy, then run the application using go run ./cmd/web:

$ go mod tidy
$ go run ./cmd/web

Then visit http://localhost:4444 in your browser.

You can also start the application with live reload support by using the run task in the Makefile:

$ make run

Project structure

Everything in the codebase is designed to be editable. Feel free to change and adapt it to meet your needs.

assets	Contains the non-code assets for the application.
↳ assets/emails/	Contains email templates.
↳ assets/migrations/	Contains SQL migrations.
↳ assets/static/	Contains static UI files (images, CSS etc).
↳ assets/templates/	Contains HTML templates.
↳ assets/efs.go	Declares an embedded filesystem containing all the assets.

cmd/web	Your application-specific code (handlers, routing, middleware, helpers) for dealing with HTTP requests and responses.
↳ cmd/web/context.go	Contains helpers for working with request context.
↳ cmd/web/errors.go	Contains helpers for managing and responding to error conditions.
↳ cmd/web/handlers.go	Contains your application HTTP handlers.
↳ cmd/web/main.go	The entry point for the application. Responsible for parsing configuration settings initializing dependencies and running the server. Start here when you're looking through the code.
↳ cmd/web/middleware.go	Contains your application middleware.
↳ cmd/web/routes.go	Contains your application route mappings.
↳ cmd/web/templates.go	Contains helpers for working with HTML templates.
↳ cmd/web/server.go	Contains a helper functions for starting and gracefully shutting down the server.

internal	Contains various helper packages used by the application.
↳ internal/cookies	Contains helper functions for reading/writing signed and encrypted cookies.
↳ internal/database/	Contains your database-related code (setup, connection and queries).
↳ internal/funcs/	Contains custom template functions.
↳ internal/password/	Contains helper functions for hashing and verifying passwords.
↳ internal/request/	Contains helper functions for decoding HTML forms, JSON requests, and URL query strings.
↳ internal/response/	Contains helper functions for rendering HTML templates and sending JSON responses.
↳ internal/smtp/	Contains a SMTP sender implementation.
↳ internal/token/	Contains functions for generating and hashing cryptographically secure random tokens.
↳ internal/validator/	Contains validation helpers.
↳ internal/version/	Contains the application version number definition.

Configuration settings

Configuration settings are managed via command-line flags in main.go.

You can try this out by using the --http-port flag to configure the network port that the server is listening on:

$ go run ./cmd/web --http-port=9999

Feel free to adapt the run() function to parse additional command-line flags and store their values in the config struct. For example, to add a configuration setting to enable a 'debug mode' in your application you could do this:

type config struct {
    httpPort  int
    debug     bool
}

...

func run() {
    var cfg config

    flag.IntVar(&cfg.httpPort, "http-port", 4444, "port to listen on for HTTP requests")
    flag.BoolVar(&cfg.debug, "debug", false, "enable debug mode")

    flag.Parse()

    ...
}

Creating new handlers

Handlers are defined as http.HandlerFunc methods on the application struct. They take the pattern:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    // Your handler logic...
}

Handlers are defined in the cmd/web/handlers.go file. For small applications, it's fine for all handlers to live in this file. For larger applications (10+ handlers) you may wish to break them out into separate files.

Handler dependencies

Any dependencies that your handlers have should be initialized in the run() function cmd/web/main.go and added to the application struct. All of your handlers, helpers and middleware that are defined as methods on application will then have access to them.

You can see an example of this in the cmd/web/main.go file where we initialize a new logger instance and add it to the application struct.

Creating new routes

HttpRouter is used for routing. Routes are defined in the routes() method in the cmd/web/routes.go file. For example:

func (app *application) routes() http.Handler {
    mux := httprouter.New()

    mux.HandlerFunc("GET", "/your/path", app.yourHandler)

    return mux
}

For more information about HttpRouter and example usage, please see the official documentation.

Adding middleware

Middleware is defined as methods on the application struct in the cmd/web/middleware.go file. Feel free to add your own. They take the pattern:

func (app *application) yourMiddleware(next http.Handler) http.Handler {
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        // Your middleware logic...
        next.ServeHTTP(w, r)
    })
}

The justinas/alice package is imported in the cmd/web/routes.go file to make it easy to create and manage middleware 'chains'.

Rendering HTML templates

HTML templates are stored in the assets/templates directory and use the standard library html/template package. The structure looks like this:

assets/templates/base.tmpl	The 'base' template containing the shared HTML markup for all your web pages.
assets/templates/pages/	Directory containing files with the page-specific content for your web pages. See assets/templates/pages/home.tmpl for an example.
assets/templates/partials/	Directory containing files with 'partials' to embed in your web pages or base template. See assets/templates/partials/footer.tmpl for an example.

The HTML for web pages can be sent using the response.Page() function. For convenience, an app.newTemplateData() method is provided which returns a map[string]any map. You can add data to this map and pass it on to your templates.

For example, to render the HTML in a assets/templates/pages/example.tmpl file:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    data := app.newTemplateData()
    data["hello"] = "world"

    err := response.Page(w, http.StatusOK, data, "pages/example.tmpl")
    if err != nil {
        app.serverError(w, r, err)
    }
}

Specific HTTP headers can optionally be sent with the response too:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    data := app.newTemplateData()
    data["hello"] = "world"

    headers := make(http.Header)
    headers.Set("X-Server", "Go")

    err := response.PageWithHeaders(w, http.StatusOK, data, headers, "pages/example.tmpl")
    if err != nil {
        app.serverError(w, r, err)
    }
}

Note: All the files in the assets/templates directory are embedded into your application binary and can be accessed via the EmbeddedFiles variable in assets/efs.go.

Adding default template data

If you have data that you want to display or use on multiple web pages, you can adapt the newTemplateData() helper in the templates.go file to include this by default. For example, if you wanted to include the current year value you could adapt it like this:

func (app *application) newTemplateData() map[string]any {
    data := map[string]any{
        "CurrentYear": time.Now().Year(),
    }

    return data
}

Custom template functions

Custom template functions are defined in internal/funcs/funcs.go and are automatically made available to your

HTML templates when you use response.Page() and email templates when you use app.mailer.Send() .

The following custom template functions are already included by default:

now	Returns the current time.
timeSince arg1	Returns the time elapsed since arg1.
timeUntil arg2	Returns the time until arg1.
formatTime arg1 arg2	Returns the time arg2 as formatted using the pattern arg1.
approxDuration arg1	Returns the approximate duration of arg1 in a 'human-friendly' format ("3 seconds", "2 months", "5 years") etc.
uppercase arg1	Returns arg1 converted to uppercase.
lowercase arg1	Returns arg1 converted to lowercase.
pluralize arg1 arg2 arg3	If arg1 equals 1 then return arg2, otherwise return arg3.
slugify arg1	Returns the lowercase of arg1 with all non-ASCII characters and punctuation removed (expect underscores and hyphens). Whitespaces are also replaced with a hyphen.
safeHTML arg1	Output the verbatim value of arg1 without escaping the content. This should only be used when arg1 is from a trusted source.
join arg1 arg2	Returns the values in slice arg1 joined using the separator arg2.
incr arg1	Increments arg1 by 1.
decr arg1	Decrements arg1 by 1.
formatInt arg1	Returns arg1 formatted with commas as the thousands separator.
formatFloat arg1 arg2	Returns arg1 rounded to arg2 decimal places and formatted with commas as the thousands separator.
yesno arg1	Returns "Yes" if arg1 is true, or "No" if arg1 is false.
urlSetParam arg1 arg2 arg3	Returns the URL arg1 with the key arg2 and value arg3 added to the query string parameters.
urlDelParam arg1 arg2	Returns the URL arg1 with the key arg2 (and corresponding value) removed from the query string parameters.

To add another custom template function, define the function in internal/funcs/funcs.go and add it to the TemplateFuncs map. For example:

var TemplateFuncs = template.FuncMap{
    ...
    "yourFunction": yourFunction,
}

func yourFunction(s string) (string, error) {
    // Do something...
}

Static files

By default, the files in the assets/static directory are served using Go's http.Fileserver whenever the application receives a GET request with a path beginning /static/. So, for example, if the application receives a GET /static/css/main.css request it will respond with the contents of the assets/static/css/main.css file.

If you want to change or remove this behavior you can by editing the routes.go file.

Note: The files in assets/static directory are embedded into your application binary and can be accessed via the EmbeddedFiles variable in assets/efs.go.

Working with forms

The codebase includes a request.DecodePostForm() function for automatically decoding HTML form data from a POST request into a struct, and request.DecodeQueryString() for decoding URL query strings into a struct. You can also use the request.DecodeForm() function to decode both form data from a POST request and query string data at the same time. Behind the scenes decoding is managed using the go-playground/form package.

As an example, let's say you have a page with the following HTML form for creating a 'person' record and routing rule:

<form action="/person/create" method="POST">
    <div>
        <label>Your name:</label>
        <input type="text" name="Name" value="{{.Form.Name}}">
    </div>
    <div>
        <label>Your age:</label>
        <input type="number" name="Age" value="{{.Form.Age}}">
    </div>
    <button>Submit</button>
</form>

func (app *application) routes() http.Handler {
    mux := flow.New()

    mux.HandleFunc("/person/create", app.createPerson, "GET", "POST")

    return mux
}

Then you can display and parse this form with a createPerson handler like this:

package main

import (
    "net/http"

    "github.com/Crocmagnon/charasheet-go/internal/request"
    "github.com/Crocmagnon/charasheet-go/internal/response"
)

func (app *application) createPerson(w http.ResponseWriter, r *http.Request) {
    type createPersonForm struct {
        Name string `form:"Name"`
        Age  int    `form:"Age"`
    }

    switch r.Method {
    case http.MethodGet:
        data := app.newTemplateData()

        // Add any default values to the form.
        data["Form"] = createPersonForm{
            Age: 21,
        }

        err := response.Page(w, http.StatusOK, data, "/path/to/page.tmpl")
        if err != nil {
            app.serverError(w, r, err)
        }

    case http.MethodPost:
        var form createPersonForm

        err := request.DecodePostForm(r, &form)
        if err != nil {
            app.badRequest(w, r, err)
            return
        }

        // Do something with the data in the form variable...
    }
}

Validating forms

The internal/validator package includes a simple (but powerful) validator.Validator type that you can use to carry out validation checks.

Extending the example above:

package main

import (
    "net/http"

    "github.com/Crocmagnon/charasheet-go/internal/request"
    "github.com/Crocmagnon/charasheet-go/internal/response"
    "github.com/Crocmagnon/charasheet-go/internal/validator"
)

func (app *application) createPerson(w http.ResponseWriter, r *http.Request) {
    type createPersonForm struct {
        Name      string              `form:"Name"`
        Age       int                 `form:"Age"`
        Validator validator.Validator `form:"-"`
    }

    switch r.Method {
    case http.MethodGet:
        data := app.newTemplateData()

        // Add any default values to the form.
        data["Form"] = createPersonForm{
            Age: 21,
        }

        err := response.Page(w, http.StatusOK, data, "/path/to/page.tmpl")
        if err != nil {
            app.serverError(w, r, err)
        }

    case http.MethodPost:
        var form createPersonForm

        err := request.DecodePostForm(r, &form)
        if err != nil {
            app.badRequest(w, r, err)
            return
        }

        form.Validator.CheckField(form.Name != "", "Name", "Name is required")
        form.Validator.CheckField(form.Age != 0, "Age", "Age is required")
        form.Validator.CheckField(form.Age >= 21, "Age", "Age must be 21 or over")

        if form.Validator.HasErrors() {
            data := app.newTemplateData()
            data["Form"] = form

            err := response.Page(w, http.StatusUnprocessableEntity, data, "/path/to/page.tmpl")
            if err != nil {
                app.serverError(w, r, err)
            }
            return
        }

        // Do something with the form information, like adding it to a database...
    }
}

And you can display the error messages in your HTML form like this:

<form action="/person/create" method="POST">
    {{if .Form.Validator.HasErrors}}
        <p>Something was wrong. Please correct the errors below and try again.</p>
    {{end}}
    <div>
        <label>Your name:</label>
        {{with .Form.Validator.FieldErrors.Name}}
            <span class='error'>{{.}}</span>
        {{end}}
        <input type="text" name="Name" value="{{.Form.Name}}">
    </div>
    <div>
        <label>Your age:</label>
        {{with .Form.Validator.FieldErrors.Age}}
            <span class='error'>{{.}}</span>
        {{end}}
        <input type="number" name="Age" value="{{.Form.Age}}">
    </div>
    <button>Submit</button>
</form>

In the example above we use the CheckField() method to carry out validation checks for specific fields. You can also use the Check() method to carry out a validation check that is not related to a specific field. For example:

input.Validator.Check(input.Password == input.ConfirmPassword, "Passwords do not match")

The validator.AddError() and validator.AddFieldError() methods also let you add validation errors directly:

input.Validator.AddFieldError("Email", "This email address is already taken")
input.Validator.AddError("Passwords do not match")

The internal/validator/helpers.go file also contains some helper functions to simplify validations that are not simple comparison operations.

NotBlank(value string)	Check that the value contains at least one non-whitespace character.
MinRunes(value string, n int)	Check that the value contains at least n runes.
MaxRunes(value string, n int)	Check that the value contains no more than n runes.
Between(value, min, max T)	Check that the value is between the min and max values inclusive.
Matches(value string, rx *regexp.Regexp)	Check that the value matches a specific regular expression.
In(value T, safelist ...T)	Check that a value is in a 'safelist' of specific values.
AllIn(values []T, safelist ...T)	Check that all values in a slice are in a 'safelist' of specific values.
NotIn(value T, blocklist ...T)	Check that the value is not in a 'blocklist' of specific values.
NoDuplicates(values []T)	Check that a slice does not contain any duplicate (repeated) values.
IsEmail(value string)	Check that the value has the formatting of a valid email address.
IsURL(value string)	Check that the value has the formatting of a valid URL.

For example, to use the Between check your code would look similar to this:

input.Validator.CheckField(validator.Between(input.Age, 18, 30), "Age", "Age must between 18 and 30")

Feel free to add your own helper functions to the internal/validator/helpers.go file as necessary for your application.

Sending JSON responses

JSON responses and a specific HTTP status code can be sent using the response.JSON() function. The data parameter can be any JSON-marshalable type.

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    data := map[string]string{"hello":  "world"}

    err := response.JSON(w, http.StatusOK, data)
    if err != nil {
        app.serverError(w, r, err)
    }
}

Specific HTTP headers can optionally be sent with the response too:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    data := map[string]string{"hello":  "world"}

    headers := make(http.Header)
    headers.Set("X-Server", "Go")

    err := response.JSONWithHeaders(w, http.StatusOK, data, headers)
    if err != nil {
        app.serverError(w, r, err)
    }
}

Parsing JSON requests

HTTP requests containing a JSON body can be decoded using the request.DecodeJSON() function. For example, to decode JSON into an input struct:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    var input struct {
        Name string `json:"Name"`
        Age  int    `json:"Age"`
    }

    err := request.DecodeJSON(w, r, &input)
    if err != nil {
        app.badRequest(w, r, err)
        return
    }

    ...
}

Note: The target decode destination passed to request.DecodeJSON() (which in the example above is &input) must be a non-nil pointer.

The request.DecodeJSON() function returns friendly, well-formed, error messages that are suitable to be sent directly to the client using the app.badRequest() helper.

There is also a request.DecodeJSONStrict() function, which works in the same way as request.DecodeJSON() except it will return an error if the request contains any JSON fields that do not match a name in the the target decode destination.

Validating JSON requests

The internal/validator package includes a simple (but powerful) validator.Validator type that you can use to carry out validation checks.

Extending the example above:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    var input struct {
        Name      string              `json:"Name"`
        Age       int                 `json:"Age"`
        Validator validator.Validator `json:"-"`
    }

    err := request.DecodeJSON(w, r, &input)
    if err != nil {
        app.badRequest(w, r, err)
        return
    }

    input.Validator.CheckField(input.Name != "", "Name", "Name is required")
    input.Validator.CheckField(input.Age != 0, "Age", "Age is required")
    input.Validator.CheckField(input.Age >= 21, "Age", "Age must be 21 or over")

    if input.Validator.HasErrors() {
        app.failedValidation(w, r, input.Validator)
        return
    }

    ...
}

The app.failedValidation() helper will send a 422 status code along with any validation error messages. For the example above, the JSON response will look like this:

{
    "FieldErrors": {
        "Age": "Age must be 21 or over",
        "Name": "Name is required"
    }
}

Working with the database

This codebase is set up to use SQLite3 with the mattn/go-sqlite3 driver. The data is stored in a db.sqlite file in the project root, but you can change this by setting a different DSN (datasource name) in the --db-dsn command-line flag , or by adapting the default value in run().

The codebase is also configured to use jmoiron/sqlx, so you have access to the whole range of sqlx extensions as well as the standard library Exec(), Query() and QueryRow() methods .

The database is available to your handlers, middleware and helpers via the application struct. If you want, you can access the database and carry out queries directly. For example:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    ...

    _, err := app.db.Exec("INSERT INTO people (name, age) VALUES ($1, $2)", "Alice", 28)
    if err != nil {
        app.serverError(w, r, err)
        return
    }

    ...
}

Generally though, it's recommended to isolate your database logic in the internal/database package and extend the DB type to include your own methods. For example, you could create a internal/database/people.go file containing code like:

type Person struct {
    ID    int    `db:"id"`
    Name  string `db:"name"`
    Age   int    `db:"age"`
}

func (db *DB) NewPerson(name string, age int) error {
    _, err := db.Exec("INSERT INTO people (name, age) VALUES ($1, $2)", name, age)
    return err
}

func (db *DB) GetPerson(id int) (Person, error) {
    var person Person
    err := db.Get(&person, "SELECT * FROM people WHERE id = $1", id)
    return person, err
}

And then call this from your handlers:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    ...

    err := app.db.NewPerson("Alice", 28)
    if err != nil {
        app.serverError(w, r, err)
        return
    }

    ...
}

Managing SQL migrations

The Makefile in the project root contains commands to easily create and work with database migrations:

$ make migrations/new name=add_example_table	Create a new database migration in the assets/migrations folder.
$ make migrations/up	Apply all up migrations.
$ make migrations/down	Apply all down migrations.
$ make migrations/goto version=N	Migrate up or down to a specific migration (where N is the migration version number).
$ make migrations/force version=N	Force the database to be specific version without running any migrations.
$ make migrations/version	Display the currently in-use migration version.

Hint: You can run $ make help at any time for a reminder of these commands.

These Makefile tasks are simply wrappers around calls to the github.com/golang-migrate/migrate/v4/cmd/migrate tool. For more information, please see the official documentation.

By default all 'up' migrations are automatically run on application startup using embeded files from the assets/migrations directory. You can disable this by setting the --db-automigrate command-line flag to false.

Important: If you change your database location from the default db.sqlite file then you will need to also update the Makefile tasks to reference the new location.

Logging

Leveled logging is supported using the slog and tint packages.

By default, a logger is initialized in the main() function. This logger writes all log messages above Debug level to os.Stdout.

logger := slog.New(tint.NewHandler(os.Stdout, &tint.Options{Level: slog.LevelDebug}))

Feel free to customize this further as necessary.

Also note: Any messages that are automatically logged by the Go http.Server are output at the Warn level.

Cookies

The internal/cookies package provides helper functions for reading and writing cookies.

The Write() function base64-encodes the cookie value and checks the cookie length is no more than 4096 bytes before writing the cookie. You can use it like this:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    // Initialize a Go cookie as normal.
    cookie := http.Cookie{
        Name:     "exampleCookie",
        Value:    "Hello Zoë!",
        Path:     "/",
        MaxAge:   3600,
        HttpOnly: true,
        Secure:   true,
        SameSite: http.SameSiteLaxMode,
    }

    // Write the cookie.
    err := cookies.Write(w, cookie)
    if err != nil {
        app.serverError(w, r, err)
        return
    }

    ...
}

The Read() function reads a named cookie and base64-decodes the value before returning it.

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    // Read the cookie value and handle any errors as necessary for your application.
    value, err := cookies.Read(r, "exampleCookie")
    if err != nil {
        switch {
        case errors.Is(err, http.ErrNoCookie):
            app.badRequest(w, r, err)
        case errors.Is(err, cookies.ErrInvalidValue):
            app.badRequest(w, r, err)
        default:
            app.serverError(w, r, err)
        }
        return
    }

    ...
}

The internal/cookies package also provides WriteSigned() and ReadSigned() functions for writing/reading signed cookies, and WriteEncrypted() and ReadEncrypted() functions encrypted cookies. Signed cookies are authenticated using HMAC-256, meaning that you can trust that the contents of the cookie has not been tampered with. Encrypted cookies are encrpyted using AES-GCM, which both authenticates and encrypts the cookie data, meaning that you can trust that the contents of the cookie has not been tampered with and the contents of the cookie cannot be read by the client.

When using these helper functions, you must set your own (secret) key for signing and encryption. This key should be a random 32-character string generated using a CSRNG which you pass to the application using the --cookie-secret-key command-line flag. For example:

$ go run ./cmd/web --cookie-secret-key=heoCDWSgJ430OvzyoLNE9mVV9UJFpOWx

To write a new signed or encrypted cookie:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    // Initialize a Go cookie as normal.
    cookie := http.Cookie{
        Name:     "exampleCookie",
        Value:    "Hello Zoë!",
        Path:     "/",
        MaxAge:   3600,
        HttpOnly: true,
        Secure:   true,
        SameSite: http.SameSiteLaxMode,
    }

    // Write a signed cookie using WriteSigned() and passing in the secret key
    // as the final argument. Use WriteEncrypted() if you want an encrpyted
    // cookie instead.
    err := cookies.WriteSigned(w, cookie, app.config.cookie.secretKey)
    if err != nil {
        app.serverError(w, r, err)
        return
    }

    ...
}

To read a signed or encrypted cookie:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    // Read the cookie value using ReadSigned() and passing in the secret key
    // as the final argument. Use ReadEncrypted() if you want to read an
    // encrpyted cookie instead.
    value, err := cookies.ReadSigned(r, "exampleCookie", app.config.cookie.secretKey)
    if err != nil {
        switch {
        case errors.Is(err, http.ErrNoCookie):
            app.badRequest(w, r, err)
        case errors.Is(err, cookies.ErrInvalidValue):
            app.badRequest(w, r, err)
        default:
            app.serverError(w, r, err)
        }
        return
    }

    ...
}

Using sessions

The codebase is set up so that cookie-based sessions (using the gorilla/sessions package) work out-of-the-box.

You can use them in your handlers like this:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    ...

    session, err := app.sessionStore.Get(r, "sessions")
    if err != nil {
        app.serverError(w, r, err)
        return
    }

    session.Values["foo"] = "bar"

    err = session.Save(r, w)
    if err != nil {
        app.serverError(w, r, err)
        return
    }

    ...
}

By default sessions are set to expire after 1 week. You can configure this along with other session cookie settings in the cmd/web/main.go file by changing the sessions.Options struct values:

sessionStore.Options = &sessions.Options{
    HttpOnly: true,
    MaxAge:   86400 * 7, // 1 week in seconds
    Path:     "/",
    SameSite: http.SameSiteLaxMode,
}

When running the application in production you should use your own secret key for authenticating sessions. This key should be a random 32-character string generated using a CSRNG which you pass to the application using the --session-secret-key command-line flag.

$ go run ./cmd/web --session-secret-key=npsqT5At8USavGtyRpr4tc8j9hWK2Yol

Key rotation is supported. If you want to switch to a new key run the application using the --session-secret-key command-line flag for the new key and the --session-old-secret-key command-line flagfor the old key, until all sessions using the old key have expired.

$ go run ./cmd/web --session-secret-key=SfvzdTUOHeHkavOzRP6p1uUVpueX11mW --session-old-secret-key=npsqT5At8USavGtyRpr4tc8j9hWK2Yol

For more information please see the documentation for the gorilla/sessions package.

Sending emails

The application is configured to support sending of emails via SMTP.

Email templates should be defined as files in the assets/emails folder. Each file should contain named templates for the email subject, plaintext body and — optionally — HTML body.

{{define "subject"}}Example subject{{end}}

{{define "plainBody"}}
This is an example body
{{end}}

{{define "htmlBody"}}
<!doctype html>
<html>
    <head>
        <meta name="viewport" content="width=device-width" />
        <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    </head>
    <body>
        <p>This is an example body</p>
    </body>
</html>
{{end}}

A further example can be found in the assets/emails/example.tmpl file. Note that your email templates automatically have access to the custom template functions defined in the internal/funcs package.

Emails can be sent from your handlers using app.mailer.Send(). For example, to send an email to [email protected] containing the contents of the assets/emails/example.tmpl file:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    ...

    data := map[string]any{"Name": "Alice"}

    err := app.mailer.Send("[email protected]", data, "example.tmpl")
    if err != nil {
        app.serverError(w, r, err)
        return
    }

   ...
}

Note: The second parameter to Send() should be a map or struct containing any dynamic data that you want to render in the email template.

The SMTP host, port, username, password and sender details can be configured using the --smtp-host command-line flag, --smtp-port command-line flag, --smtp-username command-line flag, --smtp-password command-line flag, and --smtp-from command-line flag or by adapting the default values in cmd/web/main.go.

You may wish to use Mailtrap or a similar tool for development purposes.

Error notifications

The application supports sending alerts for runtime errors to an admin email address. You can enable this by setting the --notifications-email command-line flag to a valid email address.

If you don't set a value for this, then no notifications will be sent (but the errors will still be logged).

Notifications will only be sent for any errors that are encountered as part of a request-response cycle (i.e. whenever a user sees an '500 Internal Server Error' response). Notifications are not sent for any errors that occur when starting or shutting down the application, so it's important to still use an uptime monitoring service in production.

The code for this functionality is in the sendErrorNotification() method (in the cmd/web/errors.go file) and the email template for the notification is located at assets/emails/error-notification.tmpl.

You'll need to make sure that the application is configured using valid SMTP credentials in order to send the email.

User accounts

The application is configured to support user accounts with fully-functional signup, login, logout and password-reset workflows.

A User struct describing the data for a user is defined in internal/database/users.go.

type User struct {
    ID             int       `db:"id"`
    Created        time.Time `db:"created"`
    Email          string    `db:"email"`
    HashedPassword string    `db:"hashed_password"`
}

Feel free to add additional fields to this struct (don't forget to also update the SQL queries, migrations, and handler code as necessary!).

By default login is done using the user's email address and password. When a login is successful the user's ID is stored in the session cookie. When this cookie is sent back with subsequent requests to the application, the authenticate middleware is used to look up the user's information from the database. The user's information is then stored in the current request context.

By default the session cookie lifetime is 1 week (meaning that a user will remain logged in for up to one week). You can change this value in cmd/web/main.go (see the using sessions section for more information).

You can control access to specific handlers based on whether a user is logged-in or not using the requireAuthenticatedUser and requireAnonymousUser middleware. An example of using these can be seen in the cmd/web/routes.go file.

Important: You should only call the requireAuthenticatedUser and requireAnonymousUser middleware after the authenticate middleware.

You can retrieve the details of the current user in your application handlers by calling the contextGetAuthenticatedUser() helper. This will return nil if the request is not being made by an authenticated (logged-in) user.

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    ...

    authenticatedUser := contextGetAuthenticatedUser(r)

    ...
}

For authenticated (logged-in) users, their information is also automatically available to your HTML templates via {{.AuthenticatedUser}}. Again, this will be nil if the current user is anonymous (not logged in), meaning that you can check if a user is logged in with {{if .AuthenticatedUser}}...{{end}} in your HTML templates. An example of this can be seen in assets/templates/partials/nav.tmpl.

The password reset functionality sends an email to the user. The email template for this is located at assets/emails/forgotten-password.tmpl. Please make sure that you have configured a SMTP host, port, username, password and sender details (see the sending emails section above for more information).

When using user accounts, all non-safe requests to the application require protection from CSRF attacks. Make sure to include a hidden input containing a CSRF token in any of your HTML forms that make a POST request:

<input type='hidden' name='csrf_token' value='{{.CSRFToken}}'>

Admin tasks

The Makefile in the project root contains commands to easily run common admin tasks:

$ make tidy	Format all code using go fmt and tidy the go.mod file.
$ make audit	Run go vet, staticheck, govulncheck, execute all tests and verify required modules.
$ make test	Run all tests.
$ make test/cover	Run all tests and outputs a coverage report in HTML format.
$ make build	Build a binary for the cmd/web application and store it in the /tmp/bin folder.
$ make run	Build and then run a binary for the cmd/web application.
$ make run/live	Build and then run a binary for the cmd/web application (uses live reloading).

Live reload

When you use make run/live to run the application, the application will automatically be rebuilt and restarted whenever you make changes to any files with the following extensions:

.go
.tpl, .tmpl, .html
.css, .js, .sql
.jpeg, .jpg, .gif, .png, .bmp, .svg, .webp, .ico

Behind the scenes the live reload functionality uses the cosmtrek/air tool. You can configure how it works (including which file extensions and folders are watched for changes) by editing the Makefile file.

Running background tasks

A backgroundTask() helper is included in the cmd/web/helpers.go file. You can call this in your handlers, helpers and middleware to run any logic in a separate background goroutine. This useful for things like sending emails, or completing slow-running jobs.

You can call it like so:

func (app *application) yourHandler(w http.ResponseWriter, r *http.Request) {
    ...

    app.backgroundTask(r, func() error {
        // The logic you want to execute in a background task goes here.
        // It should return an error, or nil.
        err := doSomething()
        if err != nil {
            return err
        }

        return nil
    })

    ...
}

Using the backgroundTask() helper will automatically recover any panics in the background task logic, and when performing a graceful shutdown the application will wait for any background tasks to finish running before it exits.

Application version

The application version number is generated automatically based on your latest version control system revision number. If you are using Git, this will be your latest Git commit hash. It can be retrieved by calling the version.Get() function from the internal/version package.

Important: The version control system revision number will only be available when the application is built using go build. If you run the application using go run then version.Get() will return the string "unavailable".

Changing the module path

The module path is currently set to github.com/Crocmagnon/charasheet-go. If you want to change this please find and replace all instances of github.com/Crocmagnon/charasheet-go in the codebase with your own module path.