README
¶
Alien Bunny
Alien Bunny is a content management framework, written in Go.
Getting started
Quick install (without server side JavaScript support):
go get -d -u github.com/alien-bunny/ab
cd $GOPATH/src/github.com/alien-bunny/ab/cmd/abt
go install
To install the frontend:
npm install --save abjs
Alternatively, if you want to work on the development version, use npm link:
cd $GOPATH/github.com/alien-bunny/ab/js
npm link
cd $YOUR_PROJECT
npm link abjs
See examples and more information at the project website.
Requirements
- Go 1.11
- PostgreSQL 10 or newer.
- Frontend components and the scaffolded application base require NPM 3+.
Database requirements:
The uuid extension must be installed on the database.
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
The abt command
The abt command is a helper tool for the development. Subcommands:
watch: starts a proxy that builds and reruns your application when you save a file.gensecret: generates a secret key. Useful for generating cookie secrets.decrypt: decrypts a string with the util package
Testing
An evironment variable called AB_TEST_DB must be defined with the connection string to the PostgreSQL database.
Contributing
Feel free to open an issue / pull request for discussion, feature request or bug report. If you plan to make a bigger pull request, open an issue before you start implementing it.
Development
Release criteria
- No critical issues
- High test coverage: 90% is a good target, but the point is to cover all non-trivial code paths
- Clean go vet
- All exported functions/types have documentation
- No IDEA/Goland inspection problems
- No TODOs
Major releases only:
- No major issues
- Migration guide
Breaking changes
What is a breaking change:
- Public Go API
- Configuration format
What isn't a breaking change:
- Go, PostgreSQL, NPM minimum version
- Dependency versions
- TLS-related requirements (curves, ciphers etc)
- Default crypto hash algorithm (e.g. password hash)
- Default HMAC algorithm (e.g. session signature)
- Default encryption algorithm (e.g. authentication data)
- Internal list additions (e.g. list of decoders, list of disabled account names)
Documentation
¶
Overview ¶
Package ab is the main package of the Alien Bunny web development kit.
This package contains the server and the middlewares of the framework. If you want to get started, you probably want to take a look at Hop and PetBunny.
The lowest level component is the Server component. It is a wrapper on the top of httprouter that adds middlewares along with a few useful features. On the server you can configure Services. Services are logical units of endpoints that share a piece of schema. On the top of the services, there are resources. Resources are CRUD endpoints. There are delegates and event handlers that help augmenting the functionality of the ResourceController.
Entities are a pointer to a struct that can be stored in a database. EntityController automatically does CRUD on entities, and the operations can be customized with delegates and event handlers.
EntityResource combines the EntityController and the ResourceController to easily expose an entity through API endpoints.
Quick and dirty usage:
func main() {
ab.Hop(func(cfg *viper.Viper, s *ab.Server) error {
ec := ab.NewEntityController(s.GetDBConnection())
ec.Add(&Content{}, contentEntityDelegate{})
res := ab.EntityResource(ec, &Content{}, ab.EntityResourceConfig{
DisableList: true,
DisablePost: true,
DisablePut: true,
DisableDelete: true,
})
s.RegisterService(res)
return nil
}, nil)
}
Index ¶
- Constants
- func Fail(code int, ferr error)
- func GetDB(r *http.Request) db.DB
- func GetParams(r *http.Request) httprouter.Params
- func GetPluralTranslate(r *http.Request) func(count int, singular, plural string, params map[string]string) string
- func GetSession(r *http.Request) session.Session
- func GetTranslate(r *http.Request) func(message string, params map[string]string) string
- func Hop(...) chan error
- func LogDebug(r *http.Request, component, category interface{}) log.Logger
- func LogError(r *http.Request, component, category interface{}) log.Logger
- func LogInfo(r *http.Request, component, category interface{}) log.Logger
- func LogWarn(r *http.Request, component, category interface{}) log.Logger
- func MaybeFail(code int, ferr error, excludedErrors ...error)
- func MustDecode(r *http.Request, v interface{})
- func Pager(r *http.Request, limit int) int
- func Pet(conf *config.Store, serverNamespace string, logger log.Logger, ...) (*server.Server, error)
- func RedirectHTTPSServer(logger log.Logger, addr string) error
- func RegisterSiteProvider(name string, provider SiteProvider)
- func Render(r *http.Request) *render.Renderer
- func WrapHandler(h http.Handler, extradeps ...string) http.Handler
- func WrapHandlerFunc(f func(http.ResponseWriter, *http.Request), extradeps ...string) http.Handler
- type CacheClearEvent
- type Config
- type DefaultDependencies
- type InstallEvent
- type MaintenanceEvent
- type Site
- type SiteProvider
Constants ¶
const ( // VERSION is the version of the framework. VERSION = "dev" EventCacheClear = "cache-clear" EventInstall = "install" EventMaintenance = "maintenance" )
Variables ¶
This section is empty.
Functions ¶
func GetParams ¶
func GetParams(r *http.Request) httprouter.Params
GetParams returns the path parameter values from the request.
func GetPluralTranslate ¶
func GetSession ¶
GetSession returns the current session for the request.
func GetTranslate ¶
func Hop ¶
func Hop(configure func(conf *config.Store, dispatcher *event.Dispatcher, s *server.Server) error, logger log.Logger, basedir string) chan error
Hop sets up a server with the recommended settings.
The configure function runs after the server is set up with middlewares. This is the place where endpoints and services should be registered.
The logger parameter is optional. If nil is passed, then a dev logger will be created, logging to os.Stdout.
The basedir parameter is in which directory the server config is. An empty value will default to ".".
The returned channel with either return an error very soon, or it will wait until SIGKILL/SIGTERM is received. The channel is not read-only, so it can be closed. Sending something to the channel, or closing it will stop the server. The idiomatic way to stop the server is to close the channel.
func MustDecode ¶
MustDecode decodes the the request body into v.
func Pager ¶
Pager is a function that implements pagination for listing endpoints.
It extracts the "page" query from the url, and returns the offset to that given page. The parameter limit specifies the number of elements on a given page.
func RedirectHTTPSServer ¶
RedirectHTTPSServer sets up and starts a http server that redirects all requests to https.
func RegisterSiteProvider ¶
func RegisterSiteProvider(name string, provider SiteProvider)
func WrapHandler ¶
WrapHandler adds all middlewares from PetBunny as a dependency to the given handler.
func WrapHandlerFunc ¶
WrapHandlerFunc wraps a handler func with WrapHandler.
Types ¶
type CacheClearEvent ¶
type CacheClearEvent struct{}
CacheClearEvent fires when some cache should be cleared.
func (*CacheClearEvent) ErrorStrategy ¶
func (e *CacheClearEvent) ErrorStrategy() event.ErrorStrategy
ErrorStrategy of the event. Always returns event.ErrorStrategyAggregate.
func (*CacheClearEvent) Name ¶
func (e *CacheClearEvent) Name() string
Name of the event. Always returns EventCacheClear.
type Config ¶
type Config struct {
AdminKey string
Config struct {
Provider string
Config map[string]string
ReadOnly bool
}
Cookie struct {
Prefix string
ExpiresAfter string
}
DB struct {
MaxIdleConn int
MaxOpenConn int
ConnectionMaxLifetime int64
}
Directories struct {
Assets string
}
Log struct {
Access bool
DisplayErrors bool
}
Root bool
Gzip bool
DisableMaster bool
CryptSecret string
Host string
Port string
NamespaceNegotiation struct {
HostMap map[string]string
SkipPort bool
}
HTTPS struct {
LetsEncrypt bool
Autocert string
Site bool
}
Timeout int
Language struct {
Default string
Supported string
}
}
type DefaultDependencies ¶
type DefaultDependencies struct{}
func (DefaultDependencies) Dependencies ¶
func (d DefaultDependencies) Dependencies() []string
type InstallEvent ¶
type InstallEvent struct {
// contains filtered or unexported fields
}
InstallEvent fires after the site is installed.
func NewInstallEvent ¶
func NewInstallEvent(r *http.Request) *InstallEvent
NewInstallEvent constructs an InstallEvent.
func (*InstallEvent) ErrorStrategy ¶
func (e *InstallEvent) ErrorStrategy() event.ErrorStrategy
ErrorStrategy of the event. Always returns event.ErrorStrategyStop.
func (*InstallEvent) Name ¶
func (e *InstallEvent) Name() string
Name of the event. Always returns EventInstall.
func (*InstallEvent) Request ¶
func (e *InstallEvent) Request() *http.Request
Request returns the current request.
type MaintenanceEvent ¶
type MaintenanceEvent struct {
// contains filtered or unexported fields
}
MaintenanceEvent fires when the server is free to do maintenance.
This includes removing old data, rebuild/warm caches, rebuild materialized views etc.
func NewMaintenanceEvent ¶
func NewMaintenanceEvent(r *http.Request) *MaintenanceEvent
NewMaintenanceEvent constructs a MaintenanceEvent.
func (*MaintenanceEvent) ErrorStrategy ¶
func (e *MaintenanceEvent) ErrorStrategy() event.ErrorStrategy
ErrorStrategy of the event. Always returns event.ErrorStrategyAggregate.
func (*MaintenanceEvent) Name ¶
func (e *MaintenanceEvent) Name() string
Name of the event. Always returns EventMaintenance.
func (*MaintenanceEvent) Request ¶
func (e *MaintenanceEvent) Request() *http.Request
Request returns the current request.
type SiteProvider ¶
type SiteProvider func(conf map[string]string, readOnly bool) config.CollectionLoader
func GetSiteProvider ¶
func GetSiteProvider(name string) SiteProvider
Source Files
Directories