DEV Community: Christian Melgarejo

Create your Github portfolio in less than 5 minutes

Christian Melgarejo — Sat, 03 Apr 2021 16:39:28 +0000

Want to show the world your awesome portfolio and don't have the cash to get a custom domain and hosting?

GitHub has you covered!

Prerequisites:

A GitHub account
HTML and markdown knowledge or just have in mind you can visit https://www.w3schools.com/html/ and https://www.markdownguide.org/cheat-sheet/

You got two ways to do this:

Create a repository {your-username}.github.io
Create a repository {your-username} and add a README.md file

Creating a markdown README.md file with your username

GitHub allows you to create a special repository with your username and adding a plain README.md markdown formatted file will setup a nice quick readme and frontend resume for your GitHub page such as https://github.com/cmelgarejo

Going with a {your-username}.github.io

Creating a repo {username}.github.io this is a good way to have a static site that it's fully customizable with CSS and javascript, styles and all the fancy animations or images portraying your portfolio

You have to create an index.html file and this will be served statically on the site.

You might be wondering about the CNAME file that's on the repo, so, you can additionally add a custom domain, you can do so within the settings of the repository:

And follow the instructions there, basically you will have to add a CNAME entry at your DNS configuration on the domain provider.

So these are the quickest ways to have a nice about page on the internet without having to spend a dime or make a great effort thanks to the usage of markdown

Cheers!~

Creating an opinionated GraphQL server with Go - Part 4

Christian Melgarejo — Mon, 16 Dec 2019 20:33:59 +0000

This is part of a series, not suited for beginners, but welcome too! You can
check it out from the start and review how to get up to this part, as always all the code is at github for
part 4

Today we'll add Goth and user Auth0 as our authentication provider to connect
users via google and/or facebook - or any Identity provider using OAuth2

Adding Goth into the project

Let's add Goth to our project:

$ go get -u github.com/markbates/goth

We can start referencing goth into our server code, there are a few steps to
integrate Goth completely into the flow of the app.

First, I want to keep the configuration as clean as possible and do it from the
go-gql-server definition in cmd/go-gql-server for this I create a configuration type
in pkg/utils/types.go:

// AuthProvider defines the configuration for the Goth config
type AuthProvider struct {
    Provider  string
    ClientKey string
    Secret    string
    Domain    string // If needed, like with auth0
    Scopes    []string
}

This way we can use configuration properties needed to instantiate a Goth in
the server, also, we can create a way to type in all configurations in a ordered
fashion in utils/types.go:

package utils

// ContextKey defines a type for context keys shared in the app
type ContextKey string

// ServerConfig defines the configuration for the server
type ServerConfig struct {
    Host          string
    Port          string
    URISchema     string
    Version       string
    SessionSecret string
    JWT           JWTConfig
    GraphQL       GQLConfig
    Database      DBConfig
    AuthProviders []AuthProvider
}

//JWTConfig defines the options for JWT tokens
type JWTConfig struct {
    Secret    string
    Algorithm string
}

// GQLConfig defines the configuration for the GQL Server
type GQLConfig struct {
    Path                string
    PlaygroundPath      string
    IsPlaygroundEnabled bool
}

// DBConfig defines the configuration for the DB config
type DBConfig struct {
    Dialect     string
    DSN         string
    SeedDB      bool
    LogMode     bool
    AutoMigrate bool
}

// AuthProvider defines the configuration for the Goth config
type AuthProvider struct {
    Provider  string
    ClientKey string
    Secret    string
    Domain    string // If needed, like with auth0
    Scopes    []string
}

// ListenEndpoint builds the endpoint string (host + port)
func (s *ServerConfig) ListenEndpoint() string {
    if s.Port == "80" {
        return s.Host
    }
    return s.Host + ":" + s.Port
}

// VersionedEndpoint builds the endpoint string (host + port + version)
func (s *ServerConfig) VersionedEndpoint(path string) string {
    return "/" + s.Version + path
}

// SchemaVersionedEndpoint builds the schema endpoint string (schema + host + port + version)
func (s *ServerConfig) SchemaVersionedEndpoint(path string) string {
    if s.Port == "80" {
        return s.URISchema + s.Host + "/" + s.Version + path
    }
    return s.URISchema + s.Host + ":" + s.Port + "/" + s.Version + path
}

You can notice that now we can even versionate the endpoints here, all from the
configuration file .env (there's the .env/example file in the repo too)

So, then we can add into the serverconf variable a list of providers, and all
the different configurations and pass the server configuration down to the
pkg/server/main.go from cmd/go-gql-server/main.go:

var serverconf = &utils.ServerConfig{
        Host:          utils.MustGet("SERVER_HOST"),
        Port:          utils.MustGet("SERVER_PORT"),
        URISchema:     utils.MustGet("SERVER_URI_SCHEMA"),
        Version:       utils.MustGet("SERVER_PATH_VERSION"),
        SessionSecret: utils.MustGet("SESSION_SECRET"),
        JWT: utils.JWTConfig{
            Secret:    utils.MustGet("AUTH_JWT_SECRET"),
            Algorithm: utils.MustGet("AUTH_JWT_SIGNING_ALGORITHM"),
        },
        GraphQL: utils.GQLConfig{
            Path:                utils.MustGet("GQL_SERVER_GRAPHQL_PATH"),
            PlaygroundPath:      utils.MustGet("GQL_SERVER_GRAPHQL_PLAYGROUND_PATH"),
            IsPlaygroundEnabled: utils.MustGetBool("GQL_SERVER_GRAPHQL_PLAYGROUND_ENABLED"),
        },
        Database: utils.DBConfig{
            Dialect:     utils.MustGet("GORM_DIALECT"),
            DSN:         utils.MustGet("GORM_CONNECTION_DSN"),
            SeedDB:      utils.MustGetBool("GORM_SEED_DB"),
            LogMode:     utils.MustGetBool("GORM_LOGMODE"),
            AutoMigrate: utils.MustGetBool("GORM_AUTOMIGRATE"),
        },
        AuthProviders: []utils.AuthProvider{
            utils.AuthProvider{
                Provider:  "google",
                ClientKey: utils.MustGet("PROVIDER_GOOGLE_KEY"),
                Secret:    utils.MustGet("PROVIDER_GOOGLE_SECRET"),
            },
            utils.AuthProvider{
                Provider:  "auth0",
                ClientKey: utils.MustGet("PROVIDER_AUTH0_KEY"),
                Secret:    utils.MustGet("PROVIDER_AUTH0_SECRET"),
                Domain:    utils.MustGet("PROVIDER_AUTH0_DOMAIN"),
                Scopes:    strings.Split(utils.MustGet("PROVIDER_AUTH0_SCOPES"), ","),
            },
        },
    }
    orm, err := orm.Factory(serverconf)
    defer orm.DB.Close()
    if err != nil {
        logger.Panic(err)
    }
    server.Run(serverconf, orm)

Now, getting back into the flow, we have to create handlers for our server that
will manage the authenticated paths, this is done creating the proper middleware
for the auth handling, let's create a route in our server package called auth
pkg/server/routes/auth.go:

package routes

import (
    "github.com/cmelgarejo/go-gql-server/internal/handlers/auth"
    "github.com/cmelgarejo/go-gql-server/internal/orm"
    "github.com/cmelgarejo/go-gql-server/pkg/utils"
    "github.com/gin-gonic/gin"
)

// Auth routes
func Auth(cfg *utils.ServerConfig, r *gin.Engine, orm *orm.ORM) error {
    // OAuth handlers
    g := r.Group(cfg.VersionedEndpoint("/auth"))
    g.GET("/:provider", auth.Begin())
    g.GET("/:provider/callback", auth.Callback(cfg, orm))
    // g.GET(:provider/refresh", auth.Refresh(cfg, orm))
    return nil
}

As you might have noticed, now the routes receive the ServerConfig struct and
that way we can use the VersionedEndpoint method to build the versioned path
for our server, and the /:provider path refers to the provider you want to
authenticate with, as configured now, I just added google and auth0, but since
Goth takes many providers, you can add you own as you like with in the config
array struct of providers

Now, to create the internal/handlers/auth middleware and handler for this
to work: internal/handlers/auth/main.go:

//
package auth

import (
    "context"
    "net/http"

    "github.com/cmelgarejo/go-gql-server/pkg/utils"
    "github.com/gin-gonic/gin"
)

func addProviderToContext(c *gin.Context, value interface{}) *http.Request {
    return c.Request.WithContext(context.WithValue(c.Request.Context(),
        string(utils.ProjectContextKeys.ProviderCtxKey), value))
}

Here we see that we add the provider handler to the current context of the
request, in order for this handle the auth downstream of it, how? well, binding
the auth middleware internal/handlers/auth/middleware/main.go:

package middleware

import (
    "context"
    "errors"
    "net/http"
    "strings"

    "github.com/cmelgarejo/go-gql-server/pkg/utils"
    "github.com/dgrijalva/jwt-go"

    "github.com/gin-gonic/gin"
)

var (
    // TokenHeadName is a string in the header. Default value is "Bearer"
    TokenHeadName = "Bearer"

    // APIKeyLookup is a string in the form of "<source>:<name>" that is used
    // to extract token from the request.
    // Optional. Default value "header:Authorization".
    // Possible values:
    // - "header:<name>"
    // - "query:<name>"
    // - "cookie:<name>"
    APIKeyLookup = "query:api_key,cookie:api_key,header:X-API-KEY"

    // TokenLookup is a string in the form of "<source>:<name>" that is used
    // to extract token from the request.
    // Optional. Default value "header:Authorization".
    // Possible values:
    // - "header:<name>"
    // - "query:<name>"
    // - "cookie:<name>"
    TokenLookup = "query:token,cookie:jwt,header:Authorization"

    // ErrNoClaims when HTTP status 403 is given
    ErrNoClaims = errors.New("invalid token")

    // ErrForbidden when HTTP status 403 is given
    ErrForbidden = errors.New("you don't have permission to access this resource")

    // ErrExpiredToken indicates JWT token has expired. Can't refresh.
    ErrExpiredToken = errors.New("token is expired")

    // ErrEmptyAuthHeader can be thrown if authing with a HTTP header, the Auth header needs to be set
    ErrEmptyAuthHeader = errors.New("auth header is empty")

    // ErrEmptyAPIKeyHeader can be thrown if authing with a HTTP header, the Auth header needs to be set
    ErrEmptyAPIKeyHeader = errors.New("api key header is empty")

    // ErrMissingExpField missing exp field in token
    ErrMissingExpField = errors.New("missing exp field")

    // ErrInvalidAuthHeader indicates auth header is invalid, could for example have the wrong Realm name
    ErrInvalidAuthHeader = errors.New("auth header is invalid")

    // ErrEmptyQueryToken can be thrown if authing with URL Query, the query token variable is empty
    ErrEmptyQueryToken = errors.New("query token is empty")

    // ErrEmptyCookieToken can be thrown if authing with a cookie, the token cokie is empty
    ErrEmptyCookieToken = errors.New("cookie token is empty")

    // ErrEmptyParamToken can be thrown if authing with parameter in path, the parameter in path is empty
    ErrEmptyParamToken = errors.New("parameter token is empty")

    // ErrInvalidSigningAlgorithm indicates signing algorithm is invalid, needs to be HS256, HS384, HS512, RS256, RS384 or RS512
    ErrInvalidSigningAlgorithm = errors.New("invalid signing algorithm")
)

func jwtFromHeader(c *gin.Context, key string) (string, error) {
    authHeader := c.Request.Header.Get(key)

    if authHeader == "" {
        return "", ErrEmptyAuthHeader
    }

    parts := strings.SplitN(authHeader, " ", 2)
    if !(len(parts) == 2 && parts[0] == TokenHeadName) {
        return "", ErrInvalidAuthHeader
    }

    return parts[1], nil
}

func apiKeyFromHeader(c *gin.Context, key string) (string, error) {
    apiKey := c.Request.Header.Get(key)
    if apiKey == "" {
        return "", ErrEmptyAPIKeyHeader
    }
    return apiKey, nil
}

func tokenFromQuery(c *gin.Context, key string) (string, error) {
    token := c.Query(key)
    if token == "" {
        return "", ErrEmptyQueryToken
    }
    return token, nil
}

func tokenFromCookie(c *gin.Context, key string) (string, error) {
    cookie, _ := c.Cookie(key)
    if cookie == "" {
        return "", ErrEmptyCookieToken
    }
    return cookie, nil
}

func tokenFromParam(c *gin.Context, key string) (string, error) {
    token := c.Param(key)
    if token == "" {
        return "", ErrEmptyParamToken
    }
    return token, nil
}

// ParseToken parse jwt token from gin context
func ParseToken(c *gin.Context, cfg *utils.ServerConfig) (t *jwt.Token, err error) {
    var token string
    methods := strings.Split(TokenLookup, ",")
    for _, method := range methods {
        if len(token) > 0 {
            break
        }
        parts := strings.Split(strings.TrimSpace(method), ":")
        k := strings.TrimSpace(parts[0])
        v := strings.TrimSpace(parts[1])
        switch k {
        case "header":
            token, err = jwtFromHeader(c, v)
        case "query":
            token, err = tokenFromQuery(c, v)
        case "cookie":
            token, err = tokenFromCookie(c, v)
        case "param":
            token, err = tokenFromParam(c, v)
        }
    }
    if err != nil {
        return nil, err
    }
    SigningAlgorithm := cfg.JWT.Algorithm
    Key := []byte(cfg.JWT.Secret)
    return jwt.Parse(token, func(t *jwt.Token) (interface{}, error) {
        if jwt.GetSigningMethod(SigningAlgorithm) != t.Method {
            return nil, ErrInvalidSigningAlgorithm
        }
        // save token string if vaild
        // c.Set("AUTH_JWT_TOKEN", token)
        return Key, nil
    })
}

// ParseAPIKey parse api key from gin context
func ParseAPIKey(c *gin.Context, cfg *utils.ServerConfig) (apiKey string, err error) {
    methods := strings.Split(APIKeyLookup, ",")
    for _, method := range methods {
        if len(apiKey) > 0 {
            break
        }
        parts := strings.Split(strings.TrimSpace(method), ":")
        k := strings.TrimSpace(parts[0])
        v := strings.TrimSpace(parts[1])
        switch k {
        case "header":
            apiKey, err = apiKeyFromHeader(c, v)
        case "query":
            apiKey, err = tokenFromQuery(c, v)
        case "cookie":
            apiKey, err = tokenFromCookie(c, v)
        case "param":
            apiKey, err = tokenFromParam(c, v)
        }
    }
    if err != nil {
        return "", err
    }
    return apiKey, nil
}

func addToContext(c *gin.Context, key utils.ContextKey, value interface{}) *http.Request {
    return c.Request.WithContext(context.WithValue(c.Request.Context(), key, value))
}

You might noticed again that here we also want to use API keys to auth requests,
these will be handled on our side, generating secure enough API keys for machine
to machine communications and integrations to our graphql API.

Again, all that this middleware does is trying to get the JWT tokens generated
by our providers and try to autheticate against our users records, that might
come from a cookie, a header or event a querystring param, as needed or
implemented by our client(s)

And the actual auth middleware handling method that will enforce all this is in
internal/handlers/auth/middleware/auth.go:

package middleware

import (
    "net/http"

    "github.com/cmelgarejo/go-gql-server/internal/logger"
    "github.com/cmelgarejo/go-gql-server/internal/orm"
    "github.com/cmelgarejo/go-gql-server/pkg/utils"
    "github.com/dgrijalva/jwt-go"

    "github.com/gin-gonic/gin"
)

func authError(c *gin.Context, err error) {
    errKey := "message"
    errMsgHeader := "[Auth] error: "
    e := gin.H{errKey: errMsgHeader + err.Error()}
    c.AbortWithStatusJSON(http.StatusUnauthorized, e)
}

// Middleware wraps the request with auth middleware
func Middleware(path string, cfg *utils.ServerConfig, orm *orm.ORM) gin.HandlerFunc {
    logger.Info("[Auth.Middleware] Applied to path: ", path)
    return gin.HandlerFunc(func(c *gin.Context) {
        if a, err := ParseAPIKey(c, cfg); err == nil {
            user, err := orm.FindUserByAPIKey(a)
            if err != nil {
                authError(c, ErrForbidden)
            }
            logger.Info("User: ", user)
            c.Next()
        } else {
            if err != ErrEmptyAPIKeyHeader {
                authError(c, err)
            } else {
                t, err := ParseToken(c, cfg)
                if err != nil {
                    authError(c, err)
                } else {
                    if claims, ok := t.Claims.(jwt.MapClaims); ok {
                        if claims["exp"] != nil {
                            issuer := claims["iss"].(string)
                            userid := claims["jti"].(string)
                            email := claims["email"].(string)
                            if user, err := orm.FindUserByJWT(email, issuer, userid); err != nil {
                                authError(c, ErrForbidden)
                            } else {
                                c.Request = addToContext(c, utils.ProjectContextKeys.UserCtxKey, user)
                                c.Next()
                            }
                        } else {
                            authError(c, ErrMissingExpField)
                        }
                    } else {
                        authError(c, err)
                    }
                }
            }
        }
    })
}

Here the real search for the user is made in FindUserByJWT for JWT tokens and
FindUserByAPIKey for the API keys if sent, those functions live in
internal/orm/main.go.

//FindUserByAPIKey finds the user that is related to the API key
func (o *ORM) FindUserByAPIKey(apiKey string) (*models.User, error) {
    db := o.DB.New()
    uak := &models.UserAPIKey{}
    if apiKey == "" {
        return nil, errors.New("API key is empty")
    }
    if err := db.Preload("User").Where("api_key = ?", apiKey).Find(uak).Error; err != nil {
        return nil, err
    }
    return &uak.User, nil
}

// FindUserByJWT finds the user that is related to the APIKey token
func (o *ORM) FindUserByJWT(email string, provider string, userID string) (*models.User, error) {
    db := o.DB.New()
    up := &models.UserProfile{}
    if provider == "" || userID == "" {
        return nil, errors.New("provider or userId empty")
    }
    if err := db.Preload("User").Where("email  = ? AND provider = ? AND external_user_id = ?", email, provider, userID).First(up).Error; err != nil {
        return nil, err
    }
    return &up.User, nil
}

// UpsertUserProfile saves the user if doesn't exists and adds the OAuth profile
func (o *ORM) UpsertUserProfile(input *goth.User) (*models.User, error) {
    db := o.DB.New()
    u := &models.User{}
    up := &models.UserProfile{}
    u, err := transformations.GothUserToDBUser(input, false)
    if err != nil {
        return nil, err
    }
    if tx := db.Where("email = ?", input.Email).First(u); !tx.RecordNotFound() && tx.Error != nil {
        return nil, tx.Error
    }
    if tx := db.Model(u).Save(u); tx.Error != nil {
        return nil, err
    }
    if tx := db.Where("email = ? AND provider = ? AND external_user_id = ?",
        input.Email, input.Provider, input.UserID).First(up); !tx.RecordNotFound() && tx.Error != nil {
        return nil, err
    }
    up, err = transformations.GothUserToDBUserProfile(input, false)
    if err != nil {
        return nil, err
    }
    up.User = *u
    if tx := db.Model(up).Save(up); tx.Error != nil {
        return nil, tx.Error
    }
    logger.Info(u.ID)
    return u, nil
}

There's also the UpsertUserProfile method that saves the profile into our
database so it can be retrieved later as we want at user_profiles

Continuing the auth flow, here's the handlers for the routing of the login/out
with oAuth providers internal/handlers/auth/handlers.go:

package auth

import (
    "net/http"
    "time"

    "github.com/cmelgarejo/go-gql-server/internal/orm"

    "github.com/dgrijalva/jwt-go"

    "github.com/cmelgarejo/go-gql-server/internal/logger"
    "github.com/cmelgarejo/go-gql-server/pkg/utils"
    "github.com/gin-gonic/gin"
    "github.com/markbates/goth/gothic"
)

// Claims JWT claims
type Claims struct {
    Email string `json:"email"`
    jwt.StandardClaims
}

// Begin login with the auth provider
func Begin() gin.HandlerFunc {
    return func(c *gin.Context) {
        // You have to add value context with provider name to get provider name in GetProviderName method
        c.Request = addProviderToContext(c, c.Param("provider"))
        // try to get the user without re-authenticating
        if gothUser, err := gothic.CompleteUserAuth(c.Writer, c.Request); err != nil {
            gothic.BeginAuthHandler(c.Writer, c.Request)
        } else {
            logger.Infof("user: %#v", gothUser)
        }
    }
}

// Callback callback to complete auth provider flow
func Callback(cfg *utils.ServerConfig, orm *orm.ORM) gin.HandlerFunc {
    return func(c *gin.Context) {
        // You have to add value context with provider name to get provider name in GetProviderName method
        c.Request = addProviderToContext(c, c.Param("provider"))
        user, err := gothic.CompleteUserAuth(c.Writer, c.Request)
        if err != nil {
            c.AbortWithError(http.StatusInternalServerError, err)
            return
        }
        u, err := orm.FindUserByJWT(user.Email, user.Provider, user.UserID)
        // logger.Infof("gothUser: %#v", user)
        if err != nil {
            if u, err = orm.UpsertUserProfile(&user); err != nil {
                logger.Errorf("[Auth.CallBack.UserLoggedIn.UpsertUserProfile.Error]: %q", err)
                c.AbortWithError(http.StatusInternalServerError, err)
            }
        }
        // logger.Info("[Auth.CallBack.UserLoggedIn.USER]: ", u)
        logger.Info("[Auth.CallBack.UserLoggedIn]: ", u.ID)
        jwtToken := jwt.NewWithClaims(jwt.GetSigningMethod(cfg.JWT.Algorithm), Claims{
            Email: user.Email,
            StandardClaims: jwt.StandardClaims{
                Id:        user.UserID,
                Issuer:    user.Provider,
                IssuedAt:  time.Now().UTC().Unix(),
                NotBefore: time.Now().UTC().Unix(),
                ExpiresAt: user.ExpiresAt.UTC().Unix(),
            },
        })
        token, err := jwtToken.SignedString([]byte(cfg.JWT.Secret))
        if err != nil {
            logger.Error("[Auth.Callback.JWT] error: ", err)
            c.AbortWithError(http.StatusInternalServerError, err)
            return
        }
        logger.Info("token: ", token)
        json := gin.H{
            "type":          "Bearer",
            "token":         token,
            "refresh_token": user.RefreshToken,
        }
        c.JSON(http.StatusOK, json)
    }
}

// Logout logs out of the auth provider
func Logout() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.Request = addProviderToContext(c, c.Param("provider"))
        gothic.Logout(c.Writer, c.Request)
        c.Writer.Header().Set("Location", "/")
        c.Writer.WriteHeader(http.StatusTemporaryRedirect)
    }
}

This will allow us to go to http://localhost:7777/v1/auth/:provider such as we
have configured google and auth0 and we'll have an user created in our API!

Now, you have to configure an app properly at GCP
and then, fill in the data needed for the provider as indicated in
cmd/go-gql-server/main.go, this will allow you to use the provider and
navigate to http://localhost:7777/v1/auth/google and to test it out:

Sorry for the spanish but it's the usual OAuth2 consent screen for apps from
google :D

Should you have it all correct, this will happen:

And then we have a user Signup/in already doing all the work :D

Now, use the token in the playground http://localhost:7777/v1/graphql/playground

And run a query or mutation on our server

So with this, we've integrated all!

gqlgen
goth
gorm

How about this: Next part it's setting up a RBAC layer, so we can determine
which roles/users can access information in our API :)

Be on the lookup for that! Again, like the former parts, all the code is
available in the repository here!
If you have questions, critiques and comments go ahead and let's learn more
together!

Creating an opinionated GraphQL server with Go - Part 3

Christian Melgarejo — Sun, 28 Jul 2019 05:58:14 +0000

This is part of a series, not suited for beginners, but welcome too! You can
check it out from the start

Part 1

And review how to get up to this part, as always all the code is at github for
part 3

Today we'll add GORM and a database to our project, and the RDBMS of my choice
is PostgreSQL You can use MySQL, SQLite, whatever
you like as long as GORM supports it. And, also you can check out
Part 2 in case you've missed it. I will go even on a faster pace in
this one, check out the comments in the code for more info

Adding GORM into the project

Let's add GORM to our project:

$ go get -u github.com/jinzhu/gorm

So, we need migrations, let's add Gomigrate

$ go get gopkg.in/gormigrate.v1

I don't want the id's to be as easily discoverable as ints [1,2,3] right now
anyone could just send a mutation on deleteUser(userId: 1), this should add
another layer on complexity to reduce the attack surface on our silly API.

Add UUID package from go-frs:

$ go get github.com/gofrs/uuid

And we'll setup the db models to use UUID as primary keys.

Diving into GORM

Now, let's setup GORM into our project, with:

Migrations
Models

First lets create an entry point for everything DB, where we can initialize and
setup database connection, let's put this code at internal/orm/main.go

// Package orm provides `GORM` helpers for the creation, migration and access
// on the project's database
package orm

import (
    log "github.com/cmelgarejo/go-gql-server/internal/logger"

    "github.com/cmelgarejo/go-gql-server/internal/orm/migration"

    "github.com/cmelgarejo/go-gql-server/pkg/utils"
    //Imports the database dialect of choice
    _ "github.com/jinzhu/gorm/dialects/postgres"

    "github.com/jinzhu/gorm"
)

var autoMigrate, logMode, seedDB bool
var dsn, dialect string

// ORM struct to holds the gorm pointer to db
type ORM struct {
    DB *gorm.DB
}

func init() {
    dialect = utils.MustGet("GORM_DIALECT")
    dsn = utils.MustGet("GORM_CONNECTION_DSN")
    seedDB = utils.MustGetBool("GORM_SEED_DB")
    logMode = utils.MustGetBool("GORM_LOGMODE")
    autoMigrate = utils.MustGetBool("GORM_AUTOMIGRATE")
}

// Factory creates a db connection with the selected dialect and connection string
func Factory() (*ORM, error) {
    db, err := gorm.Open(dialect, dsn)
    if err != nil {
        log.Panic("[ORM] err: ", err)
    }
    orm := &ORM{
        DB: db,
    }
    // Log every SQL command on dev, @prod: this should be disabled?
    db.LogMode(logMode)
    // Automigrate tables
    if autoMigrate {
        err = migration.ServiceAutoMigration(orm.DB)
    }
    log.Info("[ORM] Database connection initialized.")
    return orm, err
}

You might've noticed internal/logger log package, we'll dive into that in the
bonus section, for now, you can even use import "log" package :)

Migration

The migration service called in migration.ServiceAutoMigration that we'll
save in internal/ocm/migration/main.go:

package migration

import (
    "fmt"

    log "github.com/cmelgarejo/go-gql-server/internal/logger"

    "github.com/cmelgarejo/go-gql-server/internal/orm/migration/jobs"
    "github.com/cmelgarejo/go-gql-server/internal/orm/models"
    "github.com/jinzhu/gorm"
    "gopkg.in/gormigrate.v1"
)

func updateMigration(db *gorm.DB) error {
    return db.AutoMigrate(
        &models.User{},
    ).Error
}

// ServiceAutoMigration migrates all the tables and modifications to the connected source
func ServiceAutoMigration(db *gorm.DB) error {
    // Keep a list of migrations here
    m := gormigrate.New(db, gormigrate.DefaultOptions, nil)
    m.InitSchema(func(db *gorm.DB) error {
        log.Info("[Migration.InitSchema] Initializing database schema")
        switch db.Dialect().GetName() {
        case "postgres":
            // Let's create the UUID extension, the user has to ahve superuser
            // permission for now
            db.Exec("create extension \"uuid-ossp\";")
        }
        if err := updateMigration(db); err != nil {
            return fmt.Errorf("[Migration.InitSchema]: %v", err)
        }
        // Add more jobs, etc here
        return nil
    })
    m.Migrate()

    if err := updateMigration(db); err != nil {
        return err
    }
    m = gormigrate.New(db, gormigrate.DefaultOptions, []*gormigrate.Migration{
        jobs.SeedUsers,
    })
    return m.Migrate()
}

Now first we see a couple of packages more dependant on migration,
internal/orm/migration/jobs and internal/orm/models

Defining models

Let's start by setting up the models that can be added in the updateMigration
func, so to define user.go but first, I have a special need for all my models,
I want some of them to be soft deletable (not removed from the table itself)
and some can be utterly destroyed, since we are using GORM we can create structs
by using gorm.Model struct, or define our own, we'll do just that, I
need to be changed, theres another thing, the gorm.Model also uses
autoincremented numeric id's, but I like to complicate things so I want to
use UUID's as primary keys :D

Let's create a internal/orm/models/base.go model file with 2 versions of the
base model, one with hard delete and the other soft delete:

package models

import (
  "time"

  "github.com/gofrs/uuid"
  "github.com/jinzhu/gorm"
)

// BaseModel defines the common columns that all db structs should hold, usually
// db structs based on this have no soft delete
type BaseModel struct {
  // ID should use uuid_generate_v4() for the pk's
  ID        uuid.UUID  `gorm:"primary_key;type:uuid;default:uuid_generate_v4()"`
  CreatedAt time.Time  `gorm:"index;not null;default:CURRENT_TIMESTAMP"` // (My|Postgre)SQL
  UpdatedAt *time.Time `gorm:"index"`
}

// BaseModelSoftDelete defines the common columns that all db structs should
// hold, usually. This struct also defines the fields for GORM triggers to
// detect the entity should soft delete
type BaseModelSoftDelete struct {
  BaseModel
  DeletedAt *time.Time `sql:"index"`
}

Now, with these base models we can define any other one we need for our server,
so here is internal/orm/models/user.go:

package models

// User defines a user for the app
type User struct {
  BaseModelSoftDelete         // We don't to actually delete the users, maybe audit if we want to hard delete them? or wait x days to purge from the table, also
  Email               string  `gorm:"not null;unique_index:idx_email"`
  UserID              *string // External user ID
  Name                *string
  NickName            *string
  FirstName           *string
  LastName            *string
  Location            *string `gorm:"size:1048"`
  Description         *string `gorm:"size:1048"`
}

Since we're going to use a external service for the authentication via Goth
and use it for the Authentication flow, no password column for now.

All right, now with this, we just need to seed the table with at least an user,
we'll use Gomigrate pkg, and prepare a
migration job file, let's call it: internal/orm/migrations/jobs/seed_users.go

package jobs

import (
    "github.com/cmelgarejo/go-gql-server/internal/orm/models"
    "github.com/jinzhu/gorm"
    "gopkg.in/gormigrate.v1"
)

var (
    uname                    = "Test User"
    fname                    = "Test"
    lname                    = "User"
    nname                    = "Foo Bar"
    description              = "This is the first user ever!"
    location                 = "His house, maybe? Wouldn't know"
    firstUser   *models.User = &models.User{
        Email:       "test@test.com",
        Name:        &uname,
        FirstName:   &fname,
        LastName:    &lname,
        NickName:    &nname,
        Description: &description,
        Location:    &location,
    }
)

// SeedUsers inserts the first users
var SeedUsers *gormigrate.Migration = &gormigrate.Migration{
    ID: "SEED_USERS",
    Migrate: func(db *gorm.DB) error {
        return db.Create(&firstUser).Error
    },
    Rollback: func(db *gorm.DB) error {
        return db.Delete(&firstUser).Error
    },
}

Now that we have everything set-up we can modify out cmd/gql-server/main.go

package main

import (
  log "github.com/cmelgarejo/go-gql-server/internal/logger"

  "github.com/cmelgarejo/go-gql-server/internal/orm"
  "github.com/cmelgarejo/go-gql-server/pkg/server"
)

func main() {
  // Create a new ORM instance to send it to our
  orm, err := orm.Factory()
  if err != nil {
    log.Panic(err)
  }
  // Send: ORM instance
  server.Run(orm)
}

Also pkg/server/main.go:

package server

import (
  log "github.com/cmelgarejo/go-gql-server/internal/logger"

  "github.com/cmelgarejo/go-gql-server/internal/orm"

  "github.com/cmelgarejo/go-gql-server/internal/handlers"
  "github.com/cmelgarejo/go-gql-server/pkg/utils"
  "github.com/gin-gonic/gin"
)

var host, port, gqlPath, gqlPgPath string
var isPgEnabled bool

func init() {
  host = utils.MustGet("GQL_SERVER_HOST")
  port = utils.MustGet("GQL_SERVER_PORT")
  gqlPath = utils.MustGet("GQL_SERVER_GRAPHQL_PATH")
  gqlPgPath = utils.MustGet("GQL_SERVER_GRAPHQL_PLAYGROUND_PATH")
  isPgEnabled = utils.MustGetBool("GQL_SERVER_GRAPHQL_PLAYGROUND_ENABLED")
}

// Run spins up the server
func Run(orm *orm.ORM) {
  log.Info("GORM_CONNECTION_DSN: ", utils.MustGet("GORM_CONNECTION_DSN"))

  endpoint := "http://" + host + ":" + port

  r := gin.Default()
  // Handlers
  // Simple keep-alive/ping handler
  r.GET("/ping", handlers.Ping())

  // GraphQL handlers
  // Playground handler
  if isPgEnabled {
    r.GET(gqlPgPath, handlers.PlaygroundHandler(gqlPath))
    log.Info("GraphQL Playground @ " + endpoint + gqlPgPath)
  }
  // Pass in the ORM instance to the GraphqlHandler
  r.POST(gqlPath, handlers.GraphqlHandler(orm))
  log.Info("GraphQL @ " + endpoint + gqlPath)

  // Run the server
  // Inform the user where the server is listening
  log.Info("Running @ " + endpoint)
  // Print out and exit(1) to the OS if the server cannot run
  log.Fatal(r.Run(host + ":" + port))
}

And the GraphQL Handler should also receive the ORM instance, so we can use the
database connection in the resolvers internal/handlers/gql.go:

package handlers

import (
  "github.com/99designs/gqlgen/handler"
  "github.com/cmelgarejo/go-gql-server/internal/gql"
  "github.com/cmelgarejo/go-gql-server/internal/gql/resolvers"
  "github.com/cmelgarejo/go-gql-server/internal/orm"
  "github.com/gin-gonic/gin"
)

// GraphqlHandler defines the GQLGen GraphQL server handler
func GraphqlHandler(orm *orm.ORM) gin.HandlerFunc {
  // NewExecutableSchema and Config are in the generated.go file
  c := gql.Config{
    Resolvers: &resolvers.Resolver{
      ORM: orm, // pass in the ORM instance in the resolvers to be used
    },
  }

  h := handler.GraphQL(gql.NewExecutableSchema(c))

  return func(c *gin.Context) {
    h.ServeHTTP(c.Writer, c.Request)
  }
}

// PlaygroundHandler defines a handler to expose the Playground
func PlaygroundHandler(path string) gin.HandlerFunc {
  h := handler.Playground("Go GraphQL Server", path)
  return func(c *gin.Context) {
    h.ServeHTTP(c.Writer, c.Request)
  }
}

And by this point lets modify the internal/gql/resolvers/main.go for the
Resolver struct to use the ORM instance:

package resolvers

import (
  "github.com/cmelgarejo/go-gql-server/internal/gql"
  "github.com/cmelgarejo/go-gql-server/internal/orm"
)

// Resolver is a modifiable struct that can be used to pass on properties used
// in the resolvers, such as DB access
type Resolver struct {
  ORM *orm.ORM
}

// Mutation exposes mutation methods
func (r *Resolver) Mutation() gql.MutationResolver {
  return &mutationResolver{r}
}

// Query exposes query methods
func (r *Resolver) Query() gql.QueryResolver {
  return &queryResolver{r}
}

type mutationResolver struct{ *Resolver }

type queryResolver struct{ *Resolver }

Oh right! Lets modify our internal/schemas.graphql to reflect the database
model:

scalar Time
# Types
type User {
  id: ID!
  email: String!
  userId: String
  name: String
  firstName: String
  lastName: String
  nickName: String
  description: String
  location: String
  createdAt: Time!
  updatedAt: Time
}

# Input Types
input UserInput {
  email: String
  userId: String
  displayName: String
  name: String
  firstName: String
  lastName: String
  nickName: String
  description: String
  location: String
}

# List Types
type Users {
  count: Int # You want to return count for a grid for example
  list: [User!]! # that is why we need to specify the users object this way
}

# Define mutations here
type Mutation {
  createUser(input: UserInput!): User!
  updateUser(id: ID!, input: UserInput!): User!
  deleteUser(id: ID!): Boolean!
}

# Define queries here
type Query {
  users(id: ID): Users!
}

You've might noticed the way that I'm returning the users query. That's
because we might need to return the count of records to a grid for example,
and I want to filter and search in the future, and that's where list comes in

And, there's no single user query, why is that? I want to KISS always (not you,
stop looking at me like that!) that's why we'll use the same query to retrieve
a single specific record or a bunch of them.

Now, let's modify out scripts/gqlgen.sh with an option to regenerate the
resolver functions at internal/gql/resolvers/generated/resolver.go so you can
copy any new query or mutation resolver into a file of its own

#!/bin/bash
printf "\nRegenerating gqlgen files\n"
# Optional, delete the resolver to regenerate, only if there are new queries
# or mutations, if you are just changing the input or type definition and
# doesn't impact the resolvers definitions, no need to do it
while [[ "$#" -gt 0 ]]; do case $1 in
  -r|--resolvers)
    rm -f internal/gql/resolvers/generated/resolver.go
  ;;
  *) echo "Unknown parameter passed: $1"; exit 1;;
esac; shift; done

time go run -v github.com/99designs/gqlgen
printf "\nDone.\n\n"

Take from internal/gql/resolvers/generated/resolver.go the parts needed, the
func's that have a "not implemented" panic on them, and delete everything
except the package resolvers line, or else you will have impacting func
definitions.

So at last we can create the specific resolver for the users, so a new file with
all the internal/gql/resolvers/users.go:

package resolvers

import (
  "context"

  log "github.com/cmelgarejo/go-gql-server/internal/logger"

  "github.com/cmelgarejo/go-gql-server/internal/gql/models"
  tf "github.com/cmelgarejo/go-gql-server/internal/gql/resolvers/transformations"
  dbm "github.com/cmelgarejo/go-gql-server/internal/orm/models"
)

// CreateUser creates a record
func (r *mutationResolver) CreateUser(ctx context.Context, input models.UserInput) (*models.User, error) {
  return userCreateUpdate(r, input, false)
}

// UpdateUser updates a record
func (r *mutationResolver) UpdateUser(ctx context.Context, id string, input models.UserInput) (*models.User, error) {
  return userCreateUpdate(r, input, true, id)
}

// DeleteUser deletes a record
func (r *mutationResolver) DeleteUser(ctx context.Context, id string) (bool, error) {
  return userDelete(r, id)
}

// Users lists records
func (r *queryResolver) Users(ctx context.Context, id *string) (*models.Users, error) {
  return userList(r, id)
}

// ## Helper functions

func userCreateUpdate(r *mutationResolver, input models.UserInput, update bool, ids ...string) (*models.User, error) {
  dbo, err := tf.GQLInputUserToDBUser(&input, update, ids...)
  if err != nil {
    return nil, err
  }
  // Create scoped clean db interface
  db := r.ORM.DB.New().Begin()
  if !update {
    db = db.Create(dbo).First(dbo) // Create the user
  } else {
    db = db.Model(&dbo).Update(dbo).First(dbo) // Or update it
  }
  gql, err := tf.DBUserToGQLUser(dbo)
  if err != nil {
    db.RollbackUnlessCommitted()
    return nil, err
  }
  db = db.Commit()
  return gql, db.Error
}

func userDelete(r *mutationResolver, id string) (bool, error) {
  return false, nil
}

func userList(r *queryResolver, id *string) (*models.Users, error) {
  entity := "users"
  whereID := "id = ?"
  record := &models.Users{}
  dbRecords := []*dbm.User{}
  db := r.ORM.DB.New()
  if id != nil {
    db = db.Where(whereID, *id)
  }
  db = db.Find(&dbRecords).Count(&record.Count)
  for _, dbRec := range dbRecords {
    if rec, err := tf.DBUserToGQLUser(dbRec); err != nil {
      log.Errorfn(entity, err)
    } else {
      record.List = append(record.List, rec)
    }
  }
  return record, db.Error
}

You sure will have wondered what tf package is: Remember the trasformations
file and folders I mentioned in Part 2? Ok, here is where we need to
transform from the GQL Input to the database user struct to be easily saved
in the database and convert back from the database to the GQL return struct of
the resolver:

package transformations

import (
  "errors"

  gql "github.com/cmelgarejo/go-gql-server/internal/gql/models"
  dbm "github.com/cmelgarejo/go-gql-server/internal/orm/models"
  "github.com/gofrs/uuid"
)

// DBUserToGQLUser transforms [user] db input to gql type
func DBUserToGQLUser(i *dbm.User) (o *gql.User, err error) {
  o = &gql.User{
    ID:          i.ID.String(),
    Email:       i.Email,
    UserID:      i.UserID,
    Name:        i.Name,
    FirstName:   i.FirstName,
    LastName:    i.LastName,
    NickName:    i.NickName,
    Description: i.Description,
    Location:    i.Location,
    CreatedAt:   i.CreatedAt,
    UpdatedAt:   i.UpdatedAt,
  }
  return o, err
}

// GQLInputUserToDBUser transforms [user] gql input to db model
func GQLInputUserToDBUser(i *gql.UserInput, update bool, ids ...string) (o *dbm.User, err error) {
  o = &dbm.User{
    UserID:      i.UserID,
    Name:        i.Name,
    FirstName:   i.FirstName,
    LastName:    i.LastName,
    NickName:    i.NickName,
    Description: i.Description,
    Location:    i.Location,
  }
  if i.Email == nil && !update {
    return nil, errors.New("Field [email] is required")
  }
  if i.Email != nil {
    o.Email = *i.Email
  }
  if len(ids) > 0 {
    updID, err := uuid.FromString(ids[0])
    if err != nil {
      return nil, err
    }
    o.ID = updID
  }
  return o, err
}

Getting back to the users.go resolver, I've separated the helper func's from
the resolver to have them the smallest and more readable way to do this, passing
the resolver to the helper functions will make more sense than just passing the
ORM in the next Part 4 when we'll need to plug-in authentication and
permissions to the resolvers.

Hey, now we can query and mutate our users from the database!

And a specific user from the database:

We can always create a new one:

And update it:

Okay, and as promised let's enhance our little project a bit more by adding a
couple of packages next.

Extra: Bonus section

Logger package

The included "log" package could always be enough for us, but I found this
well structured package called Logrus and
created a wrapper for it to be used through out the project, create the file
internal/logger/main.go:

package logger

import (
  "github.com/sirupsen/logrus"
)

var logger *StandardLogger

func init() {
  logger = NewLogger()
}

// Event stores messages to log later, from our standard interface
type Event struct {
  id      int
  message string
}

// StandardLogger enforces specific log message formats
type StandardLogger struct {
  *logrus.Logger
}

// NewLogger initializes the standard logger
func NewLogger() *StandardLogger {
  var baseLogger = logrus.New()

  var standardLogger = &StandardLogger{baseLogger}

  standardLogger.Formatter = &logrus.TextFormatter{
    FullTimestamp: true,
  }
  // We could transform the errors into a JSON format, for external log SaaS tools such as splunk or logstash
  // standardLogger.Formatter = &logrus.JSONFormatter{
  //   PrettyPrint: true,
  // }

  return standardLogger
}

// Declare variables to store log messages as new Events
var (
  invalidArgMessage      = Event{1, "Invalid arg: %s"}
  invalidArgValueMessage = Event{2, "Invalid value for argument: %s: %v"}
  missingArgMessage      = Event{3, "Missing arg: %s"}
)

// Errorfn Log errors with format
func Errorfn(fn string, err error) {
  logger.Errorf("[%s]: %v", fn, err)
}

// InvalidArg is a standard error message
func InvalidArg(argumentName string) {
  logger.Errorf(invalidArgMessage.message, argumentName)
}

// InvalidArgValue is a standard error message
func InvalidArgValue(argumentName string, argumentValue string) {
  logger.Errorf(invalidArgValueMessage.message, argumentName, argumentValue)
}

// MissingArg is a standard error message
func MissingArg(argumentName string) {
  logger.Errorf(missingArgMessage.message, argumentName)
}

// Info Log
func Info(args ...interface{}) {
  logger.Infoln(args...)
}

// Infof Log
func Infof(format string, args ...interface{}) {
  logger.Infof(format, args...)
}

// Warn Log
func Warn(args ...interface{}) {
  logger.Warnln(args...)
}

// Warnf Log
func Warnf(format string, args ...interface{}) {
  logger.Warnf(format, args...)
}

// Panic Log
func Panic(args ...interface{}) {
  logger.Panicln(args...)
}

// Panicf Log
func Panicf(format string, args ...interface{}) {
  logger.Panicf(format, args...)
}

// Error Log
func Error(args ...interface{}) {
  logger.Errorln(args...)
}

// Errorf Log
func Errorf(format string, args ...interface{}) {
  logger.Errorf(format, args...)
}

// Fatal Log
func Fatal(args ...interface{}) {
  logger.Fatalln(args...)
}

// Fatalf Log
func Fatalf(format string, args ...interface{}) {
  logger.Fatalf(format, args...)
}

Now we have a extendable logger package with nice features

Adding server reloading on change with Realize

If you are annoyed on how every change you make you have to restart you server,
coming from developing quite a while in node.js, I really missed nodemon,
luckily we have something even better in Go:

$ go get github.com/tockins/realize

After this you'll have realize executable in $GOPATH/bin/realize up for use,
so, create a .realize.yml file (or run $GOPATH/bin/realize init in the root
of our project, to create it interactively, here's my yml file:

settings:
  files:
    outputs:
      status: false
      path: ''
      name: .r.outputs.log
    logs:
      status: false
      path: ''
      name: .r.logs.log
    errors:
      status: false
      path: ''
      name: .r.errors.log
  legacy:
    force: false
    interval: 0s
schema:
  - name: gql-server
    path: cmd/gql-server
    commands:
      install:
        status: false
      run:
        status: true
    watcher:
      extensions:
        - go
      paths:
        - ../../
      ignore:
        paths:
          - .git
          - .realize
          - .vscode
          - vendor

This should be enough for running in a script we're making next, copy the
scripts/run.sh to scripts/dev-run.sh and modify it like so:

#!/bin/sh
app="gql-server"
src="$srcPath/$app/$pkgFile"

printf "\nStart running: $app\n"
# Set all ENV vars for the server to run
export $(grep -v '^#' .env | xargs)
time /$GOPATH/bin/realize start run
# This should unset all the ENV vars, just in case.
unset $(grep -v '^#' .env | sed -E 's/(.*)=.*/\1/' | xargs)
printf "\nStopped running: $app\n\n"

And also, change run.shto:

#!/bin/sh
buildPath="build"
app="gql-server"
program="$buildPath/$app"

printf "\nStart app: $app\n"
# Set all ENV vars for the program to run
export $(grep -v '^#' .env | xargs)
time ./$program
# This should unset all the ENV vars, just in case.
unset $(grep -v '^#' .env | sed -E 's/(.*)=.*/\1/' | xargs)
printf "\nStopped app: $app\n\n"

Well, now you can run our project with .scripts/dev-run.sh and have it reload
every time you make a change in your go files! Neat, right?

Again, like the former parts, all the code is available in the
repository here! If you have questions, critiques and comments go ahead and let's learn more together!

And...

Sorry for the long and unwind post, here's a gopher potato:

Creating an opinionated GraphQL server with Go - Part 2

Christian Melgarejo — Tue, 16 Jul 2019 13:32:48 +0000

We'll be now add GQLGen's generated server into our project and start gqling
away! And, we are going to move much faster than the Part 1

Adding GQLGen into the project

Now, we can use GQLGen to initialize our server's GQLGen generated files
go run github.com/99designs/gqlgen init

This will initialize the gqlgen server, we have to make modification to fit our
project layout though, move a couple of files and edit gqlgen.yml file

generated.go(file that holds the gql gen's generated graphql server code)
resolver.go (holds the resolvers for the queries and mutations)
schema.graphql (example schema that gqlgen generates, we'll modify this)
server/server.go (stub server that we'll dump but use the handlers)
models_gen.go (file with the generated models based on the schema.graphql)

Right now we are going to to something maybe counter intuitive, let's delete all
these new files! Except gqlgen.yml; trust me, we'll get them back and in a
proper place.

For more on config for gqlgen: go here

Next, what we need to do first is modify the gqlgen.yml file like so:

# go-gql-server gqlgen.yml file
# Refer to https://gqlgen.com/config/
# for detailed .gqlgen.yml documentation.

schema:
  - internal/gql/schemas/schema.graphql
# Let gqlgen know where to put the generated server
exec:
  filename: internal/gql/generated.go
  package: gql
# Let gqlgen know where to put the generated models (if any)
model:
  filename: internal/gql/models/generated.go
  package: models
# Let gqlgen know where to put the generated resolvers
resolver:
  filename: internal/gql/resolvers/generated.go
  type: Resolver
  package: resolvers
autobind: []

So, I want to automate the generation of the gqlgen files, let's create a script
named:

scripts/gqlgen.sh (remember to chmod +x this one too)

#!/bin/bash
printf "\nRegenerating gqlgen files\n"
rm -f internal/gql/generated.go \
    internal/gql/models/generated.go \
    internal/gql/resolvers/generated.go
time go run -v github.com/99designs/gqlgen $1
printf "\nDone.\n\n"

Why am I deleting also the resolvers file? to regenerate it of course, if we are
to change anything on the schema most likely we'll be updating the resolvers too
and, when the project is small is good you have it all in one file, but we'll be
going to sort the resolvers in their own files, and have this file
internal/gql/resolvers/generated.go as a temporary file between gqlgen
generations. It's a little tedious but it will payoff later on.

Alright, now we need to define a gql schema file, so that we can use our script
to regenerate the gqlgen files in their rightful place.

$ mkdir -p internal/gql/schemas

Then you can edit a schema.graphql file

$ vi internal/gql/schemas/schema.graphql

and paste the following on it:

# Types
type User {
  id: ID
  email: String
  userId: String
}

# Input Types
input UserInput {
  email: String
  userId: String
}

# Define mutations here
type Mutation {
  createUser(input: UserInput!): User!
  updateUser(input: UserInput!): User!
  deleteUser(userId: ID!): Boolean!
}

# Define queries here
type Query {
  users(userId: ID): [User]
}

Don't worry about the gql specifics, we are going to enhance this schema a lot
more in the next parts, using OpenID specifications.

For now, lets grab internal/gql/resolvers/generated.go and edit it a little to
return a mocked user:

package resolvers

import (
    "context"

    "github.com/cmelgarejo/go-gql-server/internal/gql"
    "github.com/cmelgarejo/go-gql-server/internal/gql/models"
)

// THIS CODE IS A STARTING POINT ONLY. IT WILL NOT BE UPDATED WITH SCHEMA CHANGES.

type Resolver struct{}

func (r *Resolver) Mutation() gql.MutationResolver {
    return &mutationResolver{r}
}
func (r *Resolver) Query() gql.QueryResolver {
    return &queryResolver{r}
}

type mutationResolver struct{ *Resolver }

func (r *mutationResolver) CreateUser(ctx context.Context, input models.UserInput) (*models.User, error) {
    panic("not implemented")
}
func (r *mutationResolver) UpdateUser(ctx context.Context, input models.UserInput) (*models.User, error) {
    panic("not implemented")
}
func (r *mutationResolver) DeleteUser(ctx context.Context, userID string) (bool, error) {
    panic("not implemented")
}

type queryResolver struct{ *Resolver }

func (r *queryResolver) Users(ctx context.Context, userID *string) ([]*models.User, error) {
    records := []*models.User{
        &models.User{
            ID:     "ec17af15-e354-440c-a09f-69715fc8b595",
            Email:  "your@email.com",
            UserID: "UserID-1",
        },
    }
    return records, nil
}

Now let's bind the Graphql Server middleware to our server! Create a file in
internal/handlers/gql.go an paste this in:

package handlers

import (
    "github.com/99designs/gqlgen/handler"
    "github.com/cmelgarejo/go-gql-server/internal/gql"
    "github.com/cmelgarejo/go-gql-server/internal/gql/resolvers"
    "github.com/gin-gonic/gin"
)

// GraphqlHandler defines the GQLGen GraphQL server handler
func GraphqlHandler() gin.HandlerFunc {
    // NewExecutableSchema and Config are in the generated.go file
    c := gql.Config{
        Resolvers: &resolvers.Resolver{},
    }

    h := handler.GraphQL(gql.NewExecutableSchema(c))

    return func(c *gin.Context) {
        h.ServeHTTP(c.Writer, c.Request)
    }
}

// PlaygroundHandler Defines the Playground handler to expose our playground
func PlaygroundHandler(path string) gin.HandlerFunc {
    h := handler.Playground("Go GraphQL Server", path)
    return func(c *gin.Context) {
        h.ServeHTTP(c.Writer, c.Request)
    }
}

Now we can modify the pkg/server/main.go like this:

package server

import (
    "log"

    "github.com/cmelgarejo/go-gql-server/internal/handlers"
    "github.com/cmelgarejo/go-gql-server/pkg/utils"
    "github.com/gin-gonic/gin"
)

var host, port, gqlPath, gqlPgPath string
var isPgEnabled bool

func init() {
    host = utils.MustGet("GQL_SERVER_HOST")
    port = utils.MustGet("GQL_SERVER_PORT")
    gqlPath = utils.MustGet("GQL_SERVER_GRAPHQL_PATH")
    gqlPgPath = utils.MustGet("GQL_SERVER_GRAPHQL_PLAYGROUND_PATH")
    isPgEnabled = utils.MustGetBool("GQL_SERVER_GRAPHQL_PLAYGROUND_ENABLED")
}

// Run spins up the server
func Run() {
    endpoint := "http://" + host + ":" + port

    r := gin.Default()

    // Handlers
    // Simple keep-alive/ping handler
    r.GET("/ping", handlers.Ping())

    // GraphQL handlers
    // Playground handler
    if isPgEnabled {
        r.GET(gqlPgPath, handlers.PlaygroundHandler(gqlPath))
        log.Println("GraphQL Playground @ " + endpoint + gqlPgPath)
    }
    r.POST(gqlPath, handlers.GraphqlHandler())
    log.Println("GraphQL @ " + endpoint + gqlPath)

    // Run the server
    // Inform the user where the server is listening
    log.Println("Running @ " + endpoint)
    // Print out and exit(1) to the OS if the server cannot run
    log.Fatalln(r.Run(host + ":" + port))
}

So with the new modifications, we set new ENV variables:

```bash .env

Web framework config

GIN_MODE=debug
GQL_SERVER_HOST=localhost
GQL_SERVER_PORT=7777

GQLGen config

GQL_SERVER_GRAPHQL_PATH=/graphql
GQL_SERVER_GRAPHQL_PLAYGROUND_ENABLED=true
GQL_SERVER_GRAPHQL_PLAYGROUND_PATH=/




that dictate where will our server listen with the graphql handler and serve
queries and mutations we already defined, and let's try and run the program now:

> `$ ./scripts/run/sh`



```bash
$ ./scripts/run.sh

Start running: gql-server
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /ping                     --> github.com/cmelgarejo/go-gql-server/internal/handlers.Ping.func1 (3 handlers)
[GIN-debug] GET    /                         --> github.com/cmelgarejo/go-gql-server/internal/handlers.PlaygroundHandler.func1 (3 handlers)
2019/07/13 23:28:38 GraphQL Playground @ http://localhost:7777/
[GIN-debug] POST   /graphql                  --> github.com/cmelgarejo/go-gql-server/internal/handlers.GraphqlHandler.func1 (3 handlers)
2019/07/13 23:28:38 GraphQL @ http://localhost:7777/graphql
2019/07/13 23:28:38 Running @ http://localhost:7777
[GIN-debug] Listening and serving HTTP on localhost:7777
[GIN] 2019/07/13 - 23:28:39 | 200 |     486.646µs |       127.0.0.1 | GET      /
[GIN] 2019/07/13 - 23:28:40 | 200 |    1.353992ms |       127.0.0.1 | POST     /graphql

We can see now GraphQL requests being redirected to its handler! Nice!

Let's navigate to: http://localhost:7777

Now we got ourselves a functioning GQL server, let's try and query...

Now we see that everything is working as intended, let's move on to better
things now, and refactor the code to be a little more ordered.

Refactoring code (a.k.a my own personal filename hell)

Like I noted before, I have a contrived, yet effective way to organize
the code for GQLgen, it will help to keep code organized in small files:

{entity_plural}.go where the resolves that are generated with our gqlgen.sh script will have to be copied individually for each entity (users, posts, comments, you name it)
transformations/{entity_plural}.go now, this one is interesting, once we add GORM into our project and with that database structs, we'll have to transform these GQL Input types into database representation to be stored in the db and vice-versa to return queries from db to GQL for example.
Then I move whatever was generated from internal/gql/resolvers/generated/generated.go to internal/gql/resolvers/main.go and trim it from the entity methods we might have and just leave it like this:

package resolvers

import (
    "github.com/cmelgarejo/go-gql-server/internal/gql"
)

// Resolver is a modifiable struct that can be used to pass on properties used
// in the resolvers, such as DB access
type Resolver struct{}

// Mutation exposes mutation methods
func (r *Resolver) Mutation() gql.MutationResolver {
    return &mutationResolver{r}
}

// Query exposes query methods
func (r *Resolver) Query() gql.QueryResolver {
    return &queryResolver{r}
}

type mutationResolver struct{ *Resolver }

type queryResolver struct{ *Resolver }

This file won't have any more generated changes from now on, we'll change a
couple of things yes, but that will be done in Part 3! (WIP)

I haven't find a way to organize the folder structure into folders without
having to do recursive imports, so the prefixes will help to organize the
filenames for the entities in the resolvers folder. My TOC forces me to do
this 😅

If you have a nicer way to arrange this mess, feel free to open an Issue/PR!

As the last part, all the code is available in the repository here!

Creating an opinionated GraphQL server with Go - Part 1

Christian Melgarejo — Tue, 16 Jul 2019 13:32:21 +0000

Let's make an opinionated GraphQL server using:

Gin-gonic web framework
Goth for OAuth2 connections
GORM as DB ORM
- Gomigrate
GQLGen for building GraphQL servers without any fuss

This assumes you have:

At least, basic Go knowledge, and have go 1.12+ installed.
VSCode (preferred) or similar IDE

Project Setup

We'll follow the Go standard project layout, for this service, take a look at
the specification, it is opinionated, but serves as a good base, and we might
strand from it a little bit from it's guidelines.

Start by creating a directory anywhere we want to:

$ mkdir go-gql-server
$ cd go-gql-server
/go-gql-server $

Let's create the whole project layout with:

$ mkdir -p {build,cmd/gql-server,internal/gql-server,pkg,scripts}
# directories are created

internal/gql-server will hold all the related files for the gql server
cmd/gql-server will house the main.go file for the server, the entrypoint that will glue all together.

Since we're using go 1.12+ that will allow to use any directory you want outside
the $GOPATH/src path, we want to use go modules to initialize our project
with it we have to run:

$ go mod init github.com/cmelgarejo/go-gql-server # Replace w/your user handle
go: creating new go.mod: module github.com/cmelgarejo/go-gql-server

Coding our web server

1. Web framework: Gin

So, now we can start adding packages to our project! Let's start by getting our
web framework: gin-gonic

From gin-gonic.com:

What is Gin? Gin is a web framework written in Golang. It features a
martini-like API with much better performance, up to 40 times faster. If you
need performance and good productivity, you will love Gin.

$ go get -u github.com/gin-gonic/gin
go: creating new go.mod: module cmd/gql-server/main.go

2. Code the web server

So lets start creating the web server, to keep going, create a main.go file
in cmd/gql-server

$ vi cmd/gql-server/main.go
# vi ensues, I hope you know how to exit

And paste this placeholder code:

package main

import (
    "log"
    "net/http"

    "github.com/gin-gonic/gin"
)

func main() {
    host := "localhost"
    port := "7777"
    pathGQL := "/graphql"
    r := gin.Default()
    // Setup a route
    r.GET("/ping", func(c *gin.Context) {
        c.JSON(http.StatusOK, "OK")
    })
    // Inform the user where the server is listening
    log.Println("Running @ http://" + host + ":" + port + pathGQL)
    // Print out and exit(1) to the OS if the server cannot run
    log.Fatalln(r.Run(host + ":" + port))
}

If you go run cmd/gql-server/main.go this code, it will bring up a GIN server
listening to locahost:7777 and get an OK printed
out in the browser. It works! Now, lets refactor this code using our already
present directory structure, script, internal and pkg folders

internal/handlers/ping.go

package handlers

import (
    "net/http"

    "github.com/gin-gonic/gin"
)

// Ping is simple keep-alive/ping handler
func Ping() gin.HandlerFunc {
    return func(c *gin.Context) {
        c.String(http.StatusOK, "OK")
    }
}

pkg/server/main.go

package server

import (
    "log"

    "github.com/gin-gonic/gin"
    "github.com/cmelgarejo/go-gql-server/internal/handlers"
)

var HOST, PORT string

func init() {
    HOST = "localhost"
    PORT = "7777"
}

// Run web server
func Run() {
    r := gin.Default()
    // Setup routes
    r.GET("/ping", handlers.Ping())
    log.Println("Running @ http://" + HOST + ":" + PORT )
    log.Fatalln(r.Run(HOST + ":" + PORT))
}

cmd/gql-server/main.go file can be changed to just this:

package main

import (
    "github.com/cmelgarejo/go-gql-server/pkg/server"
)

func main() {
    server.Run()
}

How about it? One line and we have our server running out of the pkg folder

Now we can build up the server with a script:

scripts/build.sh (/bin/sh because it is more obiquitus)

#!/bin/sh
srcPath="cmd"
pkgFile="main.go"
outputPath="build"
app="gql-server"
output="$outputPath/$app"
src="$srcPath/$app/$pkgFile"

printf "\nBuilding: $app\n"
time go build -o $output $src
printf "\nBuilt: $app size:"
ls -lah $output | awk '{print $5}'
printf "\nDone building: $app\n\n"

And before running, make sure you chmod +x it

$ chmod +x scripts/build.sh
# sets execution permission on file

Now we can start building our server, like so:

$ .scripts/build.sh

Building: gql-server

real    0m0.317s
user    0m0.531s
sys     0m0.529s

Built: gql-server size:16M

Done building: gql-server

16M standalone server, not bad I think, and this could be the size of it's
docker image! Ok, now onto trying out what has been built:

$ ./build/gql-server
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /ping                     --> github.com/cmelgarejo/go-gql-server/internal/handlers.Ping.func1 (3 handlers)
2019/07/13 00:00:00 Running @ http://localhost:7777/gql
[GIN-debug] Listening and serving HTTP on :7777
[GIN] 2019/07/13 - 00:00:00 | 200 |      38.936µs |             ::1 | GET      /ping

That's some serious speed, 39 µ(micro) seconds.

And we can further improve our server code, and make configurations load from a
.env file, let's create some utils for our server:

pkg/utils/env.go

package utils

import (
    "log"
    "os"
    "strconv"
)

// MustGet will return the env or panic if it is not present
func MustGet(k string) string {
    v := os.Getenv(k)
    if v == "" {
        log.Panicln("ENV missing, key: " + k)
    }
    return v
}

// MustGetBool will return the env as boolean or panic if it is not present
func MustGetBool(k string) bool {
    v := os.Getenv(k)
    if v == "" {
        log.Panicln("ENV missing, key: " + k)
    }
    b, err := strconv.ParseBool(v)
    if err != nil {
        log.Panicln("ENV err: [" + k + "]\n" + err.Error())
    }
    return b
}

The code is pretty much self-explainatory, if a ENV var does not exists, the
program will panic, we need these to run. Now, changing:

pkg/server/main.go to this:

package server

import (
    "log"

    "github.com/gin-gonic/gin"
    "github.com/cmelgarejo/go-gql-server/internal/handlers"
    "github.com/cmelgarejo/go-gql-server/pkg/utils"
)

var host, port string

func init() {
    host = utils.MustGet("GQL_SERVER_HOST")
    port = utils.MustGet("GQL_SERVER_PORT")
}

// Run spins up the server
func Run() {
    r := gin.Default()
    // Simple keep-alive/ping handler
    r.GET("/ping", handlers.Ping())
    // Inform the user where the server is listening
    log.Println("Running @ http://" + host + ":" + port)
    // Print out and exit(1) to the OS if the server cannot run
    log.Fatalln(r.Run(host + ":" + port))

}

And we see how's it is starting to take form as a well laid out project!

We can still make a couple of things, like running server locally by using this
script:

scripts/run.sh (don't forget to chmod +x this one too)

#!/bin/sh
srcPath="cmd"
pkgFile="main.go"
app="gql-server"
src="$srcPath/$app/$pkgFile"

printf "\nStart running: $app\n"
# Set all ENV vars for the server to run
export $(grep -v '^#' .env | xargs) && time go run $src
# This should unset all the ENV vars, just in case.
unset $(grep -v '^#' .env | sed -E 's/(.*)=.*/\1/' | xargs)
printf "\nStopped running: $app\n\n"

This will set up ENV vars, and go run the server.

You can also add a .gitignore file, run git init set up the origin to your
own repository and git push it :)

This will continue in Part 2 where we'll add the GQLGen portion of
the server!

All the code is available here