appy

package module

v0.1.2 Latest Latest Go to latest Published: Oct 11, 2020 License: MIT Imports: 8 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/appist/appy

Links

Open Source Insights

README ¶

appy

An opinionated productive web framework that helps scaling business easier, i.e. focus on monolith first, only move to microservices with GRPC later on when your team is ready.

Click to see an application called "appist" made with "appy" in action

Debug Mode Release Mode

Additional Notes

appy is made as a package for your application to import without the need to install any additional binary
appy glues the great packages to provide best productivity in developing Go web application
appy comes with 2 build types:
- debug - when the code is NOT running within the binary
- release - when the code is running within the binary
appy follows 12factor via APPY_ENV environment variable:
- by default, it is development
- when APPY_ENV=staging is set, the config file is configs/.env.staging
- utilise configs/.env.<APPY_ENV> to support multiple environments deployment

Overview

architecture

Features

package `cmd`

Powerful built-in commands

Click to see details

My first awesome web application in Go.

Usage:
  myapp [command]

Available Commands:
  build             Compile the static assets into go files and build the release build binary (only available in debug build)
  config:dec        Decrypt a config value using the secret in `configs/<APPY_ENV>.key` or `APPY_MASTER_KEY` (only available in debug build)
  config:enc        Encrypt a config value using the secret in `configs/<APPY_ENV>.key` or `APPY_MASTER_KEY` (only available in debug build)
  db:create         Create all databases for the current environment
  db:drop           Drop all databases for the current environment
  db:migrate        Migrate the database(default: all, use --database to specify the target database) for the current environment
  db:migrate:status List all the database migration status(default: all, use --database to specify the target database) for the current environment
  db:rollback       Rollback the database(default: primary, use --database to specify the target database) to previous version for the current environment
  db:schema:dump    Dump all the databases schema for the current environment (only available in debug build)
  db:schema:load    Load all the databases schema for the current environment
  db:seed           Seed all databases for the current environment
  dc:down           Tear down the docker compose cluster
  dc:restart        Restart services that are defined in `docker-compose.yml`
  dc:up             Create and start containers that are defined in `docker-compose.yml`
  gen:migration     Generate database migration file(default: primary, use --database to specify the target database) for the current environment (only available in debug build)
  help              Help about any command
  middleware        List all the global middleware
  routes            List all the server-side routes
  secret            Generate a cryptographically secure secret key for encrypting cookie, CSRF token and config
  secret:rotate     Rotate the secret that is used to encrypt/decrypt the configs (only available in debug build)
  serve             Run the HTTP/HTTPS web server without `webpack-dev-server`
  setup             Run dc:up/db:create/db:schema:load/db:seed to setup the datastore with seed data
  ssl:setup         Generate and install the locally trusted SSL certs using `mkcert`
  ssl:teardown      Uninstall the locally trusted SSL certs using `mkcert`
  start             Run the HTTP/HTTPS web server with `webpack-dev-server` in development watch mode (only available in debug build)
  teardown          Tear down the docker compose cluster
  work              Run the worker to process background jobs

Flags:
  -h, --help      help for myapp
  -v, --version   version for myapp

Use "myapp [command] --help" for more information about a command.

Flexible custom commands building

package `mailer`

Ready-to-use SMTP email sending
I18n support
HTML templates binary embed support
Developer friendly email preview UI

Click to see details

package `pack`

Powerful built-in HTTP middleware
Click to see details
- API Only
  Remove Set-Cookie response header if the X-API-ONLY: 1 request header is sent.
- CSRF
  Protect cookies from Cross-Site Request Forgery by including/validating a token in the cookie across requests.
- GZIP Compress
  Compress the responses before returning it to the clients.
- Health Check
  Provide the HTTP GET endpoint for health check purpose.
- I18n
  Provide I18n support which the translations are stored in <PROJECT_NAME>/pkg/locales/*.yml.
- Logger
  Provide logger support.
- Mailer
  Provide mailer support which the views templates are stored in <PROJECT_NAME>/pkg/views/mailers/**/*.{html,txt}.
- Prerender
  Prerender and return the SPA page rendered by Chrome if the HTTP request is coming from the search engines.
- Real IP
  Retrieves the client's real IP address via X-FORWARDED-FOR or X-REAL-IP HTTP request header.
- Recovery
  Recover the HTTP request from panic and return 500 error page.
- Request ID
  Generate UUID v4 string for every HTTP request.
- Request Logger
  Log the HTTP request information.
- Secure
  Provide the standard HTTP security guards.
- Session
  Provide session management using cookie/redis.
- SPA
  Provide SPA hosting with specific path.
- View Engine
  Provide server-side HTML template rendering.
Fully integrated with gqlgen with watch mode
Ready-to-use test context builder for unit test

package `record`

Powerful database management commands

Click to see details

db:create         Create all databases for the current environment
db:drop           Drop all databases for the current environment
db:migrate        Migrate the database(default: all, use --database to specify the target database) for the current environment
db:migrate:status List all the database migration status(default: all, use --database to specify the target database) for the current environment
db:rollback       Rollback the database(default: primary, use --database to specify the target database) to previous version for the current environment
db:schema:dump    Dump all the databases schema for the current environment (only available in debug build)
db:schema:load    Load all the databases schema for the current environment
db:seed           Seed all databases for the current environment

Extended sql.DB with sqlx
Fully featured ORM
Click to see details
- Multiple databases support
- Master/Replica switch
- Soft delete
- Associations (Not Yet Supported)
  - Has One
  - Has Many
  - Belongs To
  - Many To Many
  - Polymorphism
  - Preload
  - Eager Load
- Callbacks
  - BeforeValidate/AfterValidate
  - BeforeCreate/AfterCreate
  - BeforeDelete/AfterDelete
  - BeforeUpdate/AfterUpdate
  - BeforeCommit/AfterCreateCommit/AfterDeleteCommit/AfterUpdateCommit
  - BeforeRollback/AfterRollback
- Composite primary keys
- Execution with context
- SQL query builder/logger/inspector
- Transactions
- Validations with I18n support

Performant ORM

Click to see details

go test -run=NONE -bench . -benchmem -benchtime 10s -failfast ./record
goos: darwin
goarch: amd64
pkg: github.com/appist/appy/record
BenchmarkInsertRaw-4                1239          10103533 ns/op              88 B/op          5 allocs/op
BenchmarkInsertDB-4                  898          11351591 ns/op            1548 B/op         19 allocs/op
BenchmarkInsertORM-4                 826          13826999 ns/op           15338 B/op        283 allocs/op
BenchmarkInsertMultiRaw-4            529          21830643 ns/op          107896 B/op        415 allocs/op
BenchmarkInsertMultiDB-4             481          20931749 ns/op          166302 B/op        441 allocs/op
BenchmarkInsertMultiORM-4            471          23261618 ns/op          791677 B/op       3872 allocs/op
BenchmarkUpdateRaw-4                 903          13807008 ns/op            1064 B/op         21 allocs/op
BenchmarkUpdateDB-4                 1008          13577352 ns/op            3677 B/op         52 allocs/op
BenchmarkUpdateORM-4                 788          13923442 ns/op            8920 B/op        233 allocs/op
BenchmarkReadRaw-4                  2162           4723198 ns/op            1810 B/op         47 allocs/op
BenchmarkReadDB-4                   2263           5300805 ns/op            3257 B/op         69 allocs/op
BenchmarkReadORM-4                  2259           5184327 ns/op            6911 B/op        230 allocs/op
BenchmarkReadSliceRaw-4             2210           5871991 ns/op           23088 B/op       1331 allocs/op
BenchmarkReadSliceDB-4              2197           5752959 ns/op           25070 B/op       1353 allocs/op
BenchmarkReadSliceORM-4             1864           6249231 ns/op          246630 B/op       1526 allocs/op
PASS
ok      github.com/appist/appy/record   344.692s

Ready-to-use DB/ORM mocks for unit test

package `view`

Performant and fully featured template engine
I18n support
HTML templates binary embed support

package `worker`

Fully featured background job processing backed by Redis
Click to see details
- Cron jobs (Work In Progress)
- Expiring jobs
- Unique jobs
- Scheduled jobs
- Error handling
- Middleware
- Responsive Web UI + Authorization + Search (Work In Progress)
- Strict/Weighted priority queues
Ready-to-use handler mock for unit test

Getting Started

Prerequisites

Quick Start

Step 1: Create the project folder with go module and git initialised.

$ mkdir <PROJECT_NAME> && cd $_ && go mod init $_ && git init

Note: The <PROJECT_NAME> must be an alphanumeric string.

Step 2: Create `main.go` with the snippet below.

package main

import (
  "github.com/appist/appy/cmd"
)

func main() {
  err := cmd.Scaffold()

  if err != nil {
    panic(err)
  }
}

Step 3: Initialize the project layout.

$ go run .

Step 4: Setup the databases using Docker Compose.

$ go run . setup

Step 5: Start developing your application locally.

$ go run . start

Acknowledgement

asynq - For processing background jobs
cobra - For building CLI
gin - For building HTTP router
gqlgen - For building GraphQL API
sqlx - For interacting with MySQL/PostgreSQL
testify - For writing unit tests
zap - For blazing fast, structured and leveled logging

Contribution

Please make sure to read the Contributing Guide before making a pull request.

Thank you to all the people who already contributed to appy!

License

MIT

Documentation ¶

Index ¶

type App
- func NewApp(assetFS http.FileSystem, appRoot string, viewFuncs map[string]interface{}) *App

Constants ¶

This section is empty.

Variables ¶

This section is empty.

Functions ¶

This section is empty.

Types ¶

type App ¶

type App struct {
	// contains filtered or unexported fields
}

App is the framework core that drives the application.

func NewApp ¶

func NewApp(assetFS http.FileSystem, appRoot string, viewFuncs map[string]interface{}) *App

NewApp initializes an app instance.

func (*App) Command ¶

func (a *App) Command() *cmd.Command

Command returns the app instance's root command.

func (*App) Config ¶

func (a *App) Config() *support.Config

Config returns the app instance's config.

func (*App) DB ¶

func (a *App) DB(name string) record.DBer

DB returns the app instance's specific DB.

func (*App) DBManager ¶

func (a *App) DBManager() *record.Engine

DBManager returns the app instance's DB manager.

func (*App) I18n ¶

func (a *App) I18n() *support.I18n

I18n returns the app instance's i18n manager.

func (*App) Logger ¶

func (a *App) Logger() *support.Logger

Logger returns the app instance's logger.

func (*App) Mailer ¶

func (a *App) Mailer() *mailer.Engine

Mailer returns the app instance's mailer.

func (*App) Model ¶

func (a *App) Model(m interface{}, opts ...record.ModelOption) record.Modeler

Model returns the layer that represents business data and logic.

func (*App) Run ¶

func (a *App) Run() error

Run starts running the app instance.

func (*App) Server ¶

func (a *App) Server() *pack.Server

Server returns the app instance's server.

func (*App) Worker ¶

func (a *App) Worker() *worker.Engine

Worker returns the app instance's worker.

Source Files ¶

View all Source files

app.go

Directories ¶

Path	Synopsis
cmd
mailer
mock
pack
internal/sessionstore
record
support
test
view
worker

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

README ¶

appy

Additional Notes

Table Of Contents

Overview

Features

package cmd

package mailer

package pack

package record

package view

package worker

Getting Started

Prerequisites

Quick Start

Step 1: Create the project folder with go module and git initialised.

Step 2: Create main.go with the snippet below.

Step 3: Initialize the project layout.

Step 4: Setup the databases using Docker Compose.

Step 5: Start developing your application locally.

Acknowledgement

Contribution

License

Documentation ¶

Index ¶

Constants ¶

Variables ¶

Functions ¶

Types ¶

type App ¶

func NewApp ¶

func (*App) Command ¶

func (*App) Config ¶

func (*App) DB ¶

func (*App) DBManager ¶

func (*App) I18n ¶

func (*App) Logger ¶

func (*App) Mailer ¶

func (*App) Model ¶

func (*App) Run ¶

func (*App) Server ¶

func (*App) Worker ¶

Source Files ¶

Directories ¶

package `cmd`

package `mailer`

package `pack`

package `record`

package `view`

package `worker`

Step 2: Create `main.go` with the snippet below.