README
¶
Catena
The links that associate us.
Database Migrations
The schema of the database is managed through migration files that can be applied or rolled back to ensure the database version matches the expected version of the server.
NOTE: Currently only PostgreSQL is tested with this method.
To create a migration, create a new SQL file in the migrations folder with the format XXXX_my_migration.sql where the XXXX should be the next migration number in sequence and the text describes the migration. You can use the catena command to do this as long as you're in the project root:
$ go run ./cmd/catena --new my revision name
In the SQL file you should have the following two comments:
-- migrate: up
-- insert up migration sql here
-- migrate: down
-- insert down migration sql here
All of the SQL under -- migrate: up will be run when the migration is applied and all of the SQL under -- migrate: down will be run if the migration is rolled back. Ensure that you separate multiple SQL commands with ; because they will be executed all at once and with newlines removed.
Next generate the migration by running go generate in the project root:
$ go generate ./...
This will generate the migrations code from the SQL files and allow you to apply it with the catena migrate command.
Server Mux
The goal of catena is to do as much as possible from scratch in order to demonstrate an extremely lightweight web api server and concepts such as database migration, context handling, logging, tracing, etc. This is primarily for the purposes of my deeper exploration of Go rather than to develop a production-grade API.
When it comes to route multiplexing however, the http.ServeMux is an excellent example of static routing but does not scale well to the dynamic routing required by a REST API. In the past I've attempted to implement a prefix trie for this routing, but in order to focus on other efforts in this code, I've selected httprouter based on its lightweight tree structure and benchmarks. Potentially in the future I will attempt to write my own radix tree structure and benchmark it specifically to this API - but for now it provides the smallest abstraction set and allows me to focus on middleware and the API itself.
Documentation
¶
Overview ¶
Package catena implements a simple social graph API.
Index ¶
Constants ¶
const Version = "v0.1"
Version of the Catena server and package.
Variables ¶
var ( NotFound = &ErrorHandler{status: http.StatusNotFound, message: http.StatusText(http.StatusNotFound)} MethodNotAllowed = &ErrorHandler{status: http.StatusMethodNotAllowed, message: http.StatusText(http.StatusMethodNotAllowed)} )
Default ErrorHandlers for standard http request errors
Functions ¶
func PanicHandler ¶
func PanicHandler(w http.ResponseWriter, r *http.Request, ctx interface{})
PanicHandler allows the application to recover from panics and
func Routes ¶
func Routes() *httprouter.Router
Routes creates and configures the server multiplexer with the API endpoints and methods, it does not add any additional middleware and primarily serves as documentation for how the API is configured.
Types ¶
type Catena ¶
Catena is an API server.
type ErrorHandler ¶
type ErrorHandler struct {
// contains filtered or unexported fields
}
ErrorHandler implements http.Handler for writing JSON API errors to the client and also implements error so that it can be used as an error to return from handler methods and written to http responses in middleware.
func (*ErrorHandler) ServeHTTP ¶
func (e *ErrorHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP replies to a request by writing the error message as json with the code and the message, writting the http status code. It does not otherwise end the request the caller should ensure no further writes are done to w.
Source Files
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
makemigrations
Use with go generate to create database migrations in the migrations folder.
|
Use with go generate to create database migrations in the migrations folder. |
|
Package config implements the catena server configuration.
|
Package config implements the catena server configuration. |
|
Package logs implements simple hierarchical logging functionality for debugging and logging.
|
Package logs implements simple hierarchical logging functionality for debugging and logging. |
|
Package migrations manages the state of the Catena database.
|
Package migrations manages the state of the Catena database. |