Add SAM Global support

[bryceitoc9]

BREAKING CHANGE: Improved implementation of Globals (in SAM tempates)

This PR introduces a new implementation for both defining SAM templates with Global values, as well as parsing templates containing them.

Note: Globals only apply to SAM templates - if you are using regular CloudFormation templates this breaking change should not impact you. The only impact you might see is if you are creating cloudFormation.Template structs manually rather than using the cloudformation.NewTemplate() constructor. As part of this change, a new field (Globals) was added to the Template{} struct. If you are not using the constructor, your compiler will probably complain that this field is missing from the struct instantiation in your code.

For more information about what Globals are in SAM templates, see this link:
https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/sam-specification-template-anatomy-globals.html

In previous versions of Goformation (before v5), goformation was able to parse SAM templates that contained a Globals section, however the implementation just overwrote the resource properties in the template, with the global values at parse time.

This meant that:

• It was not possible to compose a template in Go that had a Globals section.
• The JSON Schema generated by this repo, had no concept of Globals.

This new implementation DOES NOT does not overwrite the values in the template, like the previous implementation did. It replaces the old implementation completely, and exposes Globals as a series of structs that are marshalled/unmarshalled to/from JSON/YAML.

This allows you to compose a template:

template := cloudformation.NewTemplate()

template.Globals["Function"] = &global.Function{
    Timeout: 1800,
}

As well as parse a JSON/YAML template, and inspect the global properties:

template, err := goformation.Open("../some-template-with-globals.yml")
if err != nil {
    fmt.Printf("failed to open template: %s\n", err)
    os.Exit(1)
} 

fmt.Printf(template.Globals["Function"])

// You can view the global as above, however it's type is downcast to a basic interface helper
// If you want to inspect properties specific to the global type (e.g. the timeout for a Lambda function)
// then use the following helper methods to get the various global types from the template:

globalAPI, _:= template.GetServerlessGlobalApi()
globalFunction, _ := template.GetServerlessGlobalFunction()
globalHttpApi, _ := template.GetServerlessGlobalHttpApi()
globalSimpleTable, _ := template.GetServerlessGlobalSimpleTable()

fmt.Printf("Global Function Timeout: %d\n", globalFunction.Timeout)

Issue #, if available: Fixes issues #199 and #305

By submitting this pull request, I confirm that you can use, modify, copy, and redistribute this contribution, under the terms of your choice.

[PaulMaddox]

This is a really impressive PR, more so considering it's your first time with Go (and this library). It took me a little while to grok the way you've implemented the Globals functionality, however after reading through I understand why you needed to create a new separate Globals resource type etc. Great work.

As per some of the review comments I've left, I think this needs a (relatively small) bit of work on the Go resource generation/parsing before we can merge it.

[PaulMaddox]

This fails:

• t.Globals undefined (type *Template has no field or method Globals)
• It should also probably be t.Globals, not *t.Globals

I think for this PR to be merged, we need to be able to parse a CloudFormation template with globals into Go objects. I know that's not your primary motivation for this PR, but it's what people will expect.

Given the below template:

AWSTemplateFormatVersion: "2010-09-09"
Description: Testing Globals

Globals:
  Function:
    Runtime: nodejs12.x
    Timeout: 180
    Handler: index.handler
    Environment:
      Variables:
        TABLE_NAME: data-table

Resources:
  HelloWorldFunction:
    Type: AWS::Serverless::Function
    Properties:
      Environment:
        Variables:
          MESSAGE: "Hello From SAM"

I would expect to be able to parse it with goformation.Open(filename), and inspect the global elements like so:

package main

import (
	"log"

	"github.com/awslabs/goformation/v4"
	"github.com/davecgh/go-spew/spew"
)

func main() {

	template, err := goformation.Open("test/globals.yml")
	if err != nil {
		log.Fatalf("There was an error processing the template: %s\n", err)
	}

	gf, err := template.GetServerlessGlobalFunction()
	if err != nil {
		log.Fatalf("No global function set")
	}

	spew.Dump(gf)

}

I've been trying to this how best to implement this. If we add a Globals field to the Template struct, it needs to be able to support any of (and only) the Global resource types, but Go has no sum types. So we'd need to create an interface.

In cloudformation/template.go:

type Template struct {
	AWSTemplateFormatVersion string                 `json:"AWSTemplateFormatVersion,omitempty"`
	Transform                *Transform             `json:"Transform,omitempty"`
	Description              string                 `json:"Description,omitempty"`
	Metadata                 map[string]interface{} `json:"Metadata,omitempty"`
	Parameters               Parameters             `json:"Parameters,omitempty"`
	Mappings                 map[string]interface{} `json:"Mappings,omitempty"`
	Conditions               map[string]interface{} `json:"Conditions,omitempty"`
	Resources                Resources              `json:"Resources,omitempty"`
	Outputs                  Outputs                `json:"Outputs,omitempty"`
	Globals                  Globals                `json:"Globals,omitempty"`
}

type Resource interface {
	AWSCloudFormationType() string
}

type Global interface {
	AWSCloudFormationIsGlobal() bool
}

type Resources map[string]Resource
type Globals map[string]Global

In generate/templates/global.template you'd just need to add the following method at the bottom of all generated Global types, to satisfy the interface:

// AWSCloudFormationIsGlobal is used to compile an interface (cloudformation.Global) for all global resources
func (r *{{.StructName}}) AWSCloudFormationIsGlobal() bool {
    return true
}

note: the method above, like AWSCloudFormationType is prefixed with AWSCloudFormation to prevent conflicts if a CFN property ever has a matching name.

When it comes to unmarshalling the JSON/YAML into the cloudformation/global/* structs, it will a small bit of logic to detect which struct to unmarshal it into. This should be easy enough though, as the Logical ID is a fixed list (Function|Api|HttpApi|SimpleTable).

[bryceitoc9]

Committed my changes to template.go. Check to see if that fits the bill? Definitely open to moving stuff around after that.

[PaulMaddox]

Is this test actually running? I can't see it failing in the PR, but template.Globals field doesn't exist in your PR (I don't see any modifications to cloudformation/template.go).

[bryceitoc9]

Ack, I did edit this file but I thought it was a codegenned file and I didn't commit it. Will take a second look through my local diff...

[bryceitoc9]

Looks like there are a couple tests failing since I removed https://github.com/awslabs/goformation/pull/376/files#diff-02e367f7b1ddbe988fc7723f77af36e76a7d0e449c87320aa0b3eada854091d5R91-R92 . Do you think there's still sense in keeping this around? My understanding is that this can parse a template with globals (not write one) and basically just overlay global values into matching resources (instead of letting SAM do the work).

[PaulMaddox]

There's actually more test failures, as cloudformation/global/* was not committed to the repo, so all the tests in globals_test.go were failing to run.

I'm working through the test failures now and will add some more commits to this PR to resolve them.

[PaulMaddox]

• Fixed the tests in globals_test.go that never ran due to errors, and added a few to cover JSON->Go and vice-versa.
• Removed previous globals implementation.

Still to do (but I've run out of time today):

• Update all import paths to github.com/goformation/v5.
• Prepare release with a notice of the breaking change(s). I'll need to update the description of this PR, as the CHANGELOG/semantic versioning is generated based on the final squashed commit message and PR description.

[github-actions]

🎉 This PR is included in version 5.0.0 🎉

The release is available on GitHub release

Your semantic-release bot 📦🚀