Merge remote-tracking branch 'origin/master' into events

Author: bketelsen

.github/workflows/docs.yml

@@ -0,0 +1,51 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Deploy Jekyll with GitHub Pages dependencies preinstalled
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["master"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Build with Jekyll
+        uses: actions/jekyll-build-pages@v1
+        with:
+          source: ./internal/docs
+          destination: ./_site
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

internal/docs/README.md

@@ -0,0 +1,30 @@
+# Docs
+
+Documentation for the Go Micro framework 
+
+## Overview
+
+Go Micro is a framework for microservices development. 
+It's built on a powerful pluggable architecture using 
+Go interfaces. Go Micro defines the foundations for 
+distributed systems development which includes 
+service discovery, client/server rpc and pubsub. 
+Additionally Go Micro contains other primitives 
+such as auth, caching and storage. All of this 
+is encapsulated in a high level service interface.
+
+## Learn More
+
+To get started follow the getting started guide. 
+Otherwise continue to read the docs for more information 
+about the framework.
+
+## Contents
+
+- [Getting Started](getting-started)
+- [Architecture](architecture)
+- Registry
+- Broker
+- Client/Server
+- Transport
+- Store

internal/docs/_config.yml

@@ -0,0 +1,6 @@
+title: Docs
+description: "A Go microservices framework"
+baseurl: "/docs" # the subpath of your site, e.g. /blog
+url: "" # the base hostname & protocol for your site, e.g. http://example.com
+
+theme: jekyll-theme-primer

internal/docs/architecture.md

@@ -0,0 +1,42 @@
+## Architecture
+
+An overview of the Go Micro architecture
+
+## Overview
+
+Go Micro abstracts away the details of distributed systems. Here are the main features.
+
+- **Authentication** - Auth is built in as a first class citizen. Authentication and authorization enable secure
+  zero trust networking by providing every service an identity and certificates. This additionally includes rule
+  based access control.
+
+- **Dynamic Config** - Load and hot reload dynamic config from anywhere. The config interface provides a way to load application
+  level config from any source such as env vars, file, etcd. You can merge the sources and even define fallbacks.
+
+- **Data Storage** - A simple data store interface to read, write and delete records. It includes support for many storage backends
+in the plugins repo. State and persistence becomes a core requirement beyond prototyping and Micro looks to build that into the framework.
+
+- **Service Discovery** - Automatic service registration and name resolution. Service discovery is at the core of micro service
+  development. When service A needs to speak to service B it needs the location of that service. The default discovery mechanism is
+  multicast DNS (mdns), a zeroconf system.
+
+- **Load Balancing** - Client side load balancing built on service discovery. Once we have the addresses of any number of instances
+  of a service we now need a way to decide which node to route to. We use random hashed load balancing to provide even distribution
+  across the services and retry a different node if there's a problem.
+
+- **Message Encoding** - Dynamic message encoding based on content-type. The client and server will use codecs along with content-type
+  to seamlessly encode and decode Go types for you. Any variety of messages could be encoded and sent from different clients. The client
+  and server handle this by default. This includes protobuf and json by default.
+
+- **RPC Client/Server** - RPC based request/response with support for bidirectional streaming. We provide an abstraction for synchronous
+  communication. A request made to a service will be automatically resolved, load balanced, dialled and streamed.
+
+- **Async Messaging** - PubSub is built in as a first class citizen for asynchronous communication and event driven architectures.
+  Event notifications are a core pattern in micro service development. The default messaging system is a HTTP event message broker.
+
+- **Pluggable Interfaces** - Go Micro makes use of Go interfaces for each distributed system abstraction. Because of this these interfaces
+  are pluggable and allows Go Micro to be runtime agnostic. You can plugin any underlying technology.
+
+## Design
+
+We will share more on architecture soon

internal/docs/getting-started.md

@@ -0,0 +1,226 @@
+# Getting Started
+
+To make use of Go Micro 
+
+```golang
+go get "go-micro.dev/v5"
+```
+
+## Create a service
+
+This is a basic example of how you'd create a service and register a handler in pure Go.
+
+```
+mkdir helloworld
+cd helloworld
+go mod init
+go get go-micro.dev/v5@latest
+```
+
+Write the following into `main.go`
+
+```golang
+package main
+
+import (
+        "go-micro.dev/v5"
+)
+
+type Request struct {
+        Name string `json:"name"`
+}
+
+type Response struct {
+        Message string `json:"message"`
+}
+
+type Say struct{}
+
+func (h *Say) Hello(ctx context.Context, req *Request, rsp *Response) error {
+        rsp.Message = "Hello " + req.Name
+        return nil
+}
+
+func main() {
+        // create the service
+        service := micro.New("helloworld")
+
+        // initialise service
+        service.Init()
+
+        // register handler
+        service.Handle(new(Say))
+
+        // run the service
+        service.Run()
+}
+```
+
+Now run the service
+
+```
+go run main.go
+```
+
+Take a note of the address with the log line
+
+```
+Transport [http] Listening on [::]:35823
+```
+
+Now you can call the service
+
+```
+curl -XPOST \
+     -H 'Content-Type: application/json' \
+     -H 'Micro-Endpoint: Say.Hello' \
+     -d '{"name": "alice"}' \
+      http://localhost:35823
+```
+
+## Set a fixed address
+
+To set a fixed address by specifying it as an option to service, note the change from `New` to `NewService`
+
+```golang
+service := micro.NewService(
+    micro.Name("helloworld"),
+    micro.Address(":8080"),
+)
+```
+
+Alternatively use `MICRO_SERVER_ADDRESS=:8080` as an env var
+
+```
+curl -XPOST \
+     -H 'Content-Type: application/json' \
+     -H 'Micro-Endpoint: Say.Hello' \
+     -d '{"name": "alice"}' \
+      http://localhost:8080
+```
+
+## Protobuf
+
+If you want to define services with protobuf you can use [protoc-gen-micro](https://github.com/micro/micro/tree/master/cmd/protoc-gen-micro)
+
+```
+cd helloworld
+mkdir proto
+```
+
+Edit a file `proto/helloworld.proto`
+
+```
+syntax = "proto3";
+
+package greeter;
+option go_package = "/proto;helloworld";
+
+service Say {
+	rpc Hello(Request) returns (Response) {}
+}
+
+message Request {
+	string name = 1;
+}
+
+message Response {
+	string message = 1;
+}
+```
+
+You can now generate a client/server like so
+
+```
+protoc --proto_path=. --micro_out=. --go_out=. helloworld.proto
+```
+
+In your `main.go` update the code to reference the generated code
+
+```
+package main
+
+import (
+        "go-micro.dev/v5"
+
+        pb "github.com/micro/helloworld/proto"
+)
+
+type Say struct{}
+
+func (h *Say) Hello(ctx context.Context, req *pb.Request, rsp *pb.Response) error {
+        rsp.Message = "Hello " + req.Name
+        return nil
+}
+
+func main() {
+        // create the service
+        service := micro.New("helloworld")
+
+        // initialise service
+        service.Init()
+
+        // register handler
+        proto.RegisterSayHandler(service.Server(), &Say{})
+
+        // run the service
+        service.Run()
+}
+```
+
+Now I can run this again
+
+```
+go run main.go
+```
+
+## Call via a client
+
+The generated code provides us a client
+
+```
+package main
+
+import (
+        "context"
+        "fmt"
+
+        "go-micro.dev/v5"
+        pb "github.com/micro/helloworld/proto"
+)
+
+package main() {
+        service := micro.New("helloworld)
+        service.Init()
+
+        say := pb.NewSayService("helloworld", service.Client())
+
+        rsp, err := say.Hello(context.TODO(), &pb.Request{
+            Name: "John",
+        })
+        if err != nil {
+                fmt.Println(err)
+                return
+        }
+
+        fmt.Println(rsp.Message)
+}
+```
+
+## Command line
+
+If you'd like to use a command line checkout [Micro](https://github.com/micro/micro)
+
+```
+go get github.com/micro/micro/v5@latest
+```
+
+```
+micro call helloworld Say.Hello '{"name": "John"}'
+```
+
+Alternative using the dynamic CLI commands
+
+```
+micro helloworld say hello --name="John"
+```