docs: more information about rust and go usage

Author: joelgallant

docs/.vuepress/config.js

@@ -40,11 +40,7 @@ module.exports = {
       {
         title: 'Webpack',
         path: '/guide/webpack/',
-        children: [
-          '/guide/webpack/',
-          '/guide/webpack/inject',
-          '/guide/webpack/example',
-        ],
+        children: ['/guide/webpack/', '/guide/webpack/inject', '/guide/webpack/example'],
       },
       {
         title: 'React Native',
@@ -59,16 +55,12 @@ module.exports = {
       {
         title: 'Specification',
         path: '/spec/',
-        children: ['/spec/'],
+        children: ['/spec/', '/spec/golang', '/spec/rust'],
       },
       {
         title: 'Releases',
         path: '/release-notes',
-        children: [
-          ['/release-notes', 'Release Notes'],
-          '/v2-announcement',
-          '/v2-migration',
-        ],
+        children: [['/release-notes', 'Release Notes'], '/v2-announcement', '/v2-migration'],
       },
     ],
 
@@ -79,12 +71,25 @@ module.exports = {
 
   plugins: [
     ['vuepress-plugin-mermaidjs', { theme: 'base' }],
-    ['vuepress-plugin-seo', {
-      description: () => 'App Config is an Easy Configuration Loader with Strict Validation',
-      author: () => 'Launchcode',
-      image: () => 'https://app-config.dev/hero.png',
-      tags: () => ['configuration', 'config', 'conf', 'app-config', 'launchcode', 'lcdev', 'node.js', 'javascript', 'typescript'],
-    }],
+    [
+      'vuepress-plugin-seo',
+      {
+        description: () => 'App Config is an Easy Configuration Loader with Strict Validation',
+        author: () => 'Launchcode',
+        image: () => 'https://app-config.dev/hero.png',
+        tags: () => [
+          'configuration',
+          'config',
+          'conf',
+          'app-config',
+          'launchcode',
+          'lcdev',
+          'node.js',
+          'javascript',
+          'typescript',
+        ],
+      },
+    ],
   ],
 
   host: '0.0.0.0',

docs/spec/README.md

@@ -2,12 +2,15 @@
 title: Specification
 ---
 
+## Specification
+
 This document defines the exact instructions required to be "App Config Compliant".
+
 What does that mean? App Config intends to be more than a library confined to the Node.js ecosystem.
-So in that spirit, we're providing instructions for language bindings to follow in order to interoperate.
+So in that spirit, we're providing instructions for **other programming languages** to follow in order to interoperate.
 
 Does that mean we want N+1 ports of the App Config package? No, not really.
-This spec defines **minimal required support**, and App Config itself will be free to provide more features.
+This spec defines **minimal required support**, and App Config itself will be free to provide more features that are beyond that scope.
 
 ## High Level Overview
 
@@ -22,15 +25,15 @@ So to be clear, **this spec will not define #1 or #4**. These are non-trivial
 parts of App Config, and would be a lot to replicate truthfully in every language.
 
 Instead, we'll try to outline #2 and #3. These may not describe _every_ feature
-that the App Config library supports, but App Config should faithfully fulfil the requirements.
+that the App Config library supports, but App Config should faithfully fulfill the requirements.
 
 ## Loading App Config through an environment variable
 
 App Config is defined as an environment variable. This variable is named `APP_CONFIG`.
 Libraries can support different names, but all should use `APP_CONFIG` by default.
 
 This environment variable should be a string, containing text that can be parsed as JSON.
-This JSON value should an object. Libraries should reject invalid JSON strings or non-objects, if possible.
+This JSON value should an object. Libraries should reject invalid JSON strings or non-objects.
 
 ## JSON Schema Validation
 
@@ -67,19 +70,18 @@ The App Config library intends to officially support as many of these libraries
 Primarily, we believe that we can leverage our existing tooling to "jump start" these efforts.
 
 In many languages, it should be possible to dynamically **generate an App Config Compliant library for you**.
-This is especially easy in strongly typed languages, like golang, Rust or Java.
+This is especially easy in strongly typed languages, like Go, Rust or Java.
 
-We're currently experimenting with:
+We're currently have built-in support for generating: **[Go](./golang.md)** and **[Rust](./rust.md)**.
 
-- golang (using xeipuuv/gojsonschema)
-- rust (using valico)
+File a GitHub [issue](https://github.com/launchcodedev/app-config/issues/new) if you want support in your language of choice.
 
 ## Interoperation
 
 We've defined a really small subset in this document. The last thing we want
 is to encourage not using the features of App Config. Instead, we want App Config
 to provide the tools you need for development. Features like `$extends` and `$env`
-are useful for developers, and be "erased" by the time your app goes to production.
+are useful for developers, and can be "erased" by the time your app goes to production.
 By not needing these features, language support can be simple.
 
 The intention here, is for development to look like:

docs/spec/golang.md

@@ -0,0 +1,171 @@
+---
+title: Go Support
+---
+
+## App Config in Go
+
+The Node.js `@lcdev/app-config` library has built-in support for generating go code.
+
+1. Install it:
+
+   ```sh
+   npm i --save-dev @lcdev/app-config@2
+   ```
+
+2. Add codegen instructions to the `.app-config.meta.yml` file:
+
+   ```yaml
+   generate:
+     - file: ./pkg/app-config.go
+   ```
+
+3. Run the code generation:
+
+   ```sh
+   npx @lcdev/app-config gen
+   ```
+
+4. Use the config module!
+
+    ```go
+    port := GetConfig().Server.Port
+    ```
+
+This will result in a type-safe struct that represents your config faithfully.
+It also validates the config against the App Config schema.
+
+Typically, users will wrap usage of their app in the `@lcdev/app-config` CLI.
+For example:
+
+```sh
+npx @lcdev/app-config -s -- go run .
+```
+
+<br />
+
+---
+
+<br />
+
+The generated code will look something like this:
+
+```go
+// @generated by app-config
+
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/xeipuuv/gojsonschema"
+)
+
+var config Config
+
+func init() {
+	loadedConfig, err := LoadConfig()
+
+	if err != nil {
+		log.Panic(err.Error())
+	}
+
+	config = loadedConfig
+}
+
+func GetConfig() Config {
+	return config
+}
+
+func LoadConfig() (Config, error) {
+	var loadedConfig Config
+	var loadedSchema map[string]interface{}
+	var err error
+
+	configText := os.Getenv("APP_CONFIG")
+	schemaText := os.Getenv("APP_CONFIG_SCHEMA")
+
+	if configText == "" {
+		return loadedConfig, errors.New("The APP_CONFIG environment variable was not set")
+	}
+
+	if schemaText == "" {
+		return loadedConfig, errors.New("The APP_CONFIG_SCHEMA environment variable was not set")
+	}
+
+	err = json.Unmarshal([]byte(schemaText), &loadedSchema)
+
+	if err != nil {
+		return loadedConfig, fmt.Errorf("Could not parse APP_CONFIG_SCHEMA environment variable: %s", err.Error())
+	}
+
+	err = json.Unmarshal([]byte(configText), &loadedConfig)
+
+	if err != nil {
+		return loadedConfig, fmt.Errorf("Could not parse APP_CONFIG environment variable: %s", err.Error())
+	}
+
+	schemaLoader := gojsonschema.NewGoLoader(loadedSchema)
+	documentLoader := gojsonschema.NewGoLoader(loadedConfig)
+
+	result, err := gojsonschema.Validate(schemaLoader, documentLoader)
+
+	if err != nil {
+		return loadedConfig, fmt.Errorf("Could not validate App Config: %s", err.Error())
+	}
+
+	if !result.Valid() {
+		errors := ""
+
+		for _, desc := range result.Errors() {
+			if errors == "" {
+				errors = fmt.Sprintf("%v", desc)
+			} else {
+				errors = fmt.Sprintf("%s, %v", errors, desc)
+			}
+		}
+
+		return loadedConfig, fmt.Errorf("The App Config value invalid: %s", errors)
+	}
+
+	return loadedConfig, nil
+}
+
+func UnmarshalConfig(data []byte) (Config, error) {
+	var r Config
+	err := json.Unmarshal(data, &r)
+	return r, err
+}
+
+func (r *Config) Marshal() ([]byte, error) {
+	return json.Marshal(r)
+}
+
+type Config struct {
+	Jwt    Jwt    `json:"jwt"`
+	Server Server `json:"server"`
+}
+
+type Jwt struct {
+	Secret string `json:"secret"`
+}
+
+type Server struct {
+	Port int64 `json:"port"`
+}
+```
+
+You can specify the "no-singleton" option to avoid automatic (`init` function) config loading:
+
+```yaml
+generate:
+ - file: ./pkg/app-config.go
+   rendererOptions:
+     no-singleton: 'true'
+```
+
+Note that code generation is not guaranteed to be deterministic between versions of app config.
+We'll do our best to be stable though, and output code that `gofmt` is happy with.