Go framework for API and Web development.
The HFW is a collection of libraries that helps into building Web and API applications that rely on some common services, and existing libraries:
Documentation for the Web example
In examples/web_example there is an exaple of how to set a
basic email authentication flow
Docmentation for the observability example
Mostly a personal preference, but also because it has native support to UUIDs, and we can use ULIDs as IDs, that can be directly converted to UUID, and that provides the benefits of an UUID with being incremental so have better behaviour when indexing them, or to use them as a pagination cursor.
Mostly because can do whatever a Memcached service provides, but also provides other interesting data structures that allow for efficient ratelimits, and can provide Pub/Sub channels to distribute workload among different instantces.
Mostly because is widely adopted and easy to use. Not benchmarking nor comparisons have been made.
Just a wrapper over existing OK log's ULIDs library with extra functions for formatting it as an UUID, or a Shuffled version to not make so obvious that are sequential IDs. It also implements a Scan function for database reading.
The bundler package provides functions to collect assets that will be placed in a single place in order to be deployed. Also, can collect and run migrations.
The "app updater" of the bundler keeps track of modifications made to source files and resource files, in order to create a new binary to run when something has changed and to update the directory of resources.
The config package reads the configuration, to prepare the required dependencies
for the app.
By default it will try to load the configuration from a file named
config.yaml under the config dir, but if the CONFVARIANT is set,
it will try to load instead the config.[CONFVARIANT].yaml file.
If no config found under that config dir, the bundle/config will be tried.
config.BuildExternalServices, reads the configuration and selects the
implementation for the maile, the SQLDB and the notification services, and
a function to obtain an Insighter instance to log and record metrics.
With a call to ExtServices(), a structure with the same info that external
services is created but with a clone of the insighter.
For some functionality, like session handling, a redis server is required.
db.redis.master.hostdb.redis.master.port
db.sql.master.namedb.sql.master.hostdb.sql.master.portdb.sql.master.userdb.sql.master.pass
prometheus.enabledprometheus.portprometheus.pathprometheus.prefixsentry.enabledsentry.dsngraylog.enabledgraylog.portgraylog.hostgraylog.prefix
By using the mailer.preferred configuration setting the mailer to
be used can be selected.
Valid values are:
- sendgrid
- mailtrap
- roundcube
- console
- nop
The required config to use sendgris is:
sendgrid.key
The required config to use mailtrap are:
mailtrap.usermailtrap.password
Will select the directory where the templates can be found.
An interface definition to send simple emails.
There are different implementations:
- Mailgun: to use mailgun mailer
- Mailtrap: an smpt implementation to send mails to the mailtrap service (to check how emails are displayed and make visual tests).
- Console: to output the email to stadout (useful for development environments)
- Mock: useful for testing, as it stores all mails "sent" in memory.
- Nop: useful for testing when we don't care about. emails, but some code needs to send some email
It also contains a mailer wrapper: LoggerMailer,
that logs errors occured in another mailer instance.
Package to hold functions related to i18n and localization.
It contains the definitions for languages entities.
Usually you might want to use only these two:
-
LangCodesAndNames: with the names of the language and its variation, along with the ISO codes for the language and its variation.
-
LangCodes: contains only the ISO codes for the a given language and its variation.
But you can also get a structure with all the language definitions
using the GetLangs function that will return an array of Lang,
and its children LangVariant.
A package to store templates to send email notifications. This package is "work in progress". The idea would be to extend it with more ways to send notifications (like websockets). Currently there is only an email sender, and a "filesystem composer" that can read Go templates from files.
These packages provide some basic functionality that is usually needed in a lot of applications, like use manages, api tokens..
This package implements the usual email registration workflow. For emails,
it works using the pkg/notifier package, using templates for:
- Requests Registration (template
users_requestregistration) - Request Password Reset (template
users_requestpasswordreset)
Under the pkg/ginfw/auth package, there is the key to store a an
authenticated user ID.
For managing web user sessions there is the pkg/ginfw/web/session/session.go
A simple entity definition for letting users create their own API keys, and use them to perform actions using an exposed API.
A basic definition of a an error that will be a string. (Might disappear later on)
Public pages
The web API is meant to be used by the frontend code. As such, it works by using a CSRF token, cnd CORS restrictions to get requests only from the same domain.
These wep apis are served under https://maindomain/wapp/ path
These are the stable APIs for mobile apps or third party integrations.
- Errors are logged at the usecase layer whenever is possible.
- Errors coming from other libraries that aren't know
These are much more elaborated frameworks, production ready that you might want to have a look at: