new copilot generated documentation

internal/website/docs/broker.md

@@ -13,11 +13,14 @@ The broker provides pub/sub messaging for Go Micro services.
 
 ## Implementations
 Supported brokers include:
-- Memory (default)
-- NATS
-- RabbitMQ
+- HTTP (default)
+- NATS (`go-micro.dev/v5/broker/nats`)
+- RabbitMQ (`go-micro.dev/v5/broker/rabbitmq`)
+- Memory (`go-micro.dev/v5/broker/memory`)
 
-Configure the broker when creating your service as needed.
+Plugins are scoped under `go-micro.dev/v5/broker/<plugin>`.
+
+Configure the broker in code or via environment variables.
 
 ## Example Usage
 
@@ -56,3 +59,51 @@ func main() {
     }
 }
 ```
+
+## Configure a specific broker in code
+
+NATS:
+```go
+import (
+    "go-micro.dev/v5"
+    bnats "go-micro.dev/v5/broker/nats"
+)
+
+func main() {
+    b := bnats.NewNatsBroker()
+    svc := micro.NewService(micro.Broker(b))
+    svc.Init()
+    svc.Run()
+}
+```
+
+RabbitMQ:
+```go
+import (
+    "go-micro.dev/v5"
+    "go-micro.dev/v5/broker/rabbitmq"
+)
+
+func main() {
+    b := rabbitmq.NewBroker()
+    svc := micro.NewService(micro.Broker(b))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Configure via environment
+
+Using the built-in configuration flags/env vars (no code changes):
+
+```
+MICRO_BROKER=nats MICRO_BROKER_ADDRESS=nats://127.0.0.1:4222 micro server
+```
+
+Common variables:
+- `MICRO_BROKER`: selects the broker implementation (`http`, `nats`, `rabbitmq`, `memory`).
+- `MICRO_BROKER_ADDRESS`: comma-separated list of broker addresses.
+
+Notes:
+- NATS addresses should be prefixed with `nats://`.
+- RabbitMQ addresses typically use `amqp://user:pass@host:5672`.

internal/website/docs/examples/hello-service.md

@@ -0,0 +1,61 @@
+---
+layout: default
+---
+
+# Hello Service
+
+A minimal HTTP service using Go Micro, with a single endpoint.
+
+## Service
+
+```go
+package main
+
+import (
+    "context"
+    "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() {
+    svc := micro.New("helloworld")
+    svc.Init()
+    svc.Handle(new(Say))
+    svc.Run()
+}
+```
+
+Run it:
+
+```bash
+go run main.go
+```
+
+Call it:
+
+```bash
+curl -XPOST \
+  -H 'Content-Type: application/json' \
+  -H 'Micro-Endpoint: Say.Hello' \
+  -d '{"name": "Alice"}' \
+  http://127.0.0.1:8080
+```
+
+Set a fixed address:
+
+```go
+svc := micro.NewService(
+    micro.Name("helloworld"),
+    micro.Address(":8080"),
+)
+```

internal/website/docs/examples/index.md

@@ -0,0 +1,14 @@
+---
+layout: default
+---
+
+# Learn by Example
+
+A collection of small, focused examples demonstrating common patterns with Go Micro.
+
+- [Hello Service](hello-service.md)
+- [RPC Client](rpc-client.md)
+- [Pub/Sub with NATS Broker](pubsub-nats.md)
+- [Service Discovery with Consul](registry-consul.md)
+- [State with Postgres Store](store-postgres.md)
+- [NATS Transport](transport-nats.md)

internal/website/docs/examples/pubsub-nats.md

@@ -0,0 +1,45 @@
+---
+layout: default
+---
+
+# Pub/Sub with NATS Broker
+
+Use the NATS broker for pub/sub.
+
+## In code
+
+```go
+package main
+
+import (
+    "log"
+    "go-micro.dev/v5"
+    "go-micro.dev/v5/broker"
+    bnats "go-micro.dev/v5/broker/nats"
+)
+
+func main() {
+    b := bnats.NewNatsBroker()
+    svc := micro.NewService(micro.Broker(b))
+    svc.Init()
+
+    // subscribe
+    _, _ = broker.Subscribe("events", func(e broker.Event) error {
+        log.Printf("received: %s", string(e.Message().Body))
+        return nil
+    })
+
+    // publish
+    _ = broker.Publish("events", &broker.Message{Body: []byte("hello")})
+
+    svc.Run()
+}
+```
+
+## Via environment
+
+Run your service with env vars set:
+
+```bash
+MICRO_BROKER=nats MICRO_BROKER_ADDRESS=nats://127.0.0.1:4222 go run main.go
+```

internal/website/docs/examples/registry-consul.md

@@ -0,0 +1,33 @@
+---
+layout: default
+---
+
+# Service Discovery with Consul
+
+Use Consul as the service registry.
+
+## In code
+
+```go
+package main
+
+import (
+    "go-micro.dev/v5"
+    "go-micro.dev/v5/registry/consul"
+)
+
+func main() {
+    reg := consul.NewConsulRegistry()
+    svc := micro.NewService(micro.Registry(reg))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Via environment
+
+Run your service with env vars set:
+
+```bash
+MICRO_REGISTRY=consul MICRO_REGISTRY_ADDRESS=127.0.0.1:8500 go run main.go
+```

internal/website/docs/examples/rpc-client.md

@@ -0,0 +1,36 @@
+---
+layout: default
+---
+
+# RPC Client
+
+Call a running service using the Go Micro client.
+
+```go
+package main
+
+import (
+    "context"
+    "fmt"
+    "go-micro.dev/v5"
+)
+
+type Request struct { Name string }
+
+type Response struct { Message string }
+
+func main() {
+    svc := micro.New("caller")
+    svc.Init()
+
+    req := svc.Client().NewRequest("helloworld", "Say.Hello", &Request{Name: "John"})
+    var rsp Response
+
+    if err := svc.Client().Call(context.TODO(), req, &rsp); err != nil {
+        fmt.Println("error:", err)
+        return
+    }
+
+    fmt.Println(rsp.Message)
+}
+```

internal/website/docs/examples/store-postgres.md

@@ -0,0 +1,44 @@
+---
+layout: default
+---
+
+# State with Postgres Store
+
+Use the Postgres store for persistent key/value state.
+
+## In code
+
+```go
+package main
+
+import (
+    "log"
+    "go-micro.dev/v5"
+    "go-micro.dev/v5/store"
+    postgres "go-micro.dev/v5/store/postgres"
+)
+
+func main() {
+    st := postgres.NewStore()
+    svc := micro.NewService(micro.Store(st))
+    svc.Init()
+
+    _ = store.Write(&store.Record{Key: "foo", Value: []byte("bar")})
+    recs, _ := store.Read("foo")
+    log.Println("value:", string(recs[0].Value))
+
+    svc.Run()
+}
+```
+
+## Via environment
+
+Run your service with env vars set:
+
+```bash
+MICRO_STORE=postgres \
+MICRO_STORE_ADDRESS=postgres://user:pass@127.0.0.1:5432/postgres \
+MICRO_STORE_DATABASE=micro \
+MICRO_STORE_TABLE=micro \
+go run main.go
+```

internal/website/docs/examples/transport-nats.md

@@ -0,0 +1,33 @@
+---
+layout: default
+---
+
+# NATS Transport
+
+Use NATS as the transport between services.
+
+## In code
+
+```go
+package main
+
+import (
+    "go-micro.dev/v5"
+    tnats "go-micro.dev/v5/transport/nats"
+)
+
+func main() {
+    t := tnats.NewTransport()
+    svc := micro.NewService(micro.Transport(t))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Via environment
+
+Run your service with env vars set:
+
+```bash
+MICRO_TRANSPORT=nats MICRO_TRANSPORT_ADDRESS=nats://127.0.0.1:4222 go run main.go
+```

internal/website/docs/getting-started.md

@@ -7,7 +7,7 @@ layout: default
 To make use of Go Micro 
 
 ```golang
-go get "go-micro.dev/v5"
+go get go-micro.dev/v5@latest
 ```
 
 ## Create a service
@@ -105,7 +105,13 @@ curl -XPOST \
 
 ## 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)
+If you want to define services with protobuf you can use protoc-gen-micro (go-micro.dev/v5/cmd/protoc-gen-micro).
+
+Install the generator:
+
+```
+go install go-micro.dev/v5/cmd/protoc-gen-micro@latest
+```
 
 ```
 cd helloworld
@@ -133,7 +139,7 @@ message Response {
 }
 ```
 
-You can now generate a client/server like so
+You can now generate a client/server like so (ensure `$GOBIN` is on your `$PATH` so `protoc` can find `protoc-gen-micro`):
 
 ```
 protoc --proto_path=. --micro_out=. --go_out=. helloworld.proto
@@ -213,17 +219,19 @@ func main() {
 
 ## Command line
 
-If you'd like to use a command line checkout [Micro](https://github.com/micro/micro)
+Install the Micro CLI:
 
 ```
-go get github.com/micro/micro/v5@latest
+go install go-micro.dev/v5/cmd/micro@latest
 ```
 
+Call a running service via RPC:
+
 ```
 micro call helloworld Say.Hello '{"name": "John"}'
 ```
 
-Alternative using the dynamic CLI commands
+Alternative using the dynamic CLI commands:
 
 ```
 micro helloworld say hello --name="John"

internal/website/docs/index.md

@@ -32,3 +32,5 @@ about the framework.
 - [Client/Server](client-server.md)
 - [Transport](transport.md)
 - [Store](store.md)
+- [Plugins](plugins.md)
+- [Examples](examples/index.md)

internal/website/docs/plugins.md

@@ -0,0 +1,132 @@
+---
+layout: default
+---
+
+# Plugins
+
+Plugins are scoped under each interface directory within this repository. To use a plugin, import it directly from the corresponding interface subpackage and pass it to your service via options.
+
+Common interfaces and locations:
+- Registry: `go-micro.dev/v5/registry/*` (e.g. `consul`, `etcd`, `nats`, `mdns`)
+- Broker: `go-micro.dev/v5/broker/*` (e.g. `nats`, `rabbitmq`, `http`, `memory`)
+- Transport: `go-micro.dev/v5/transport/*` (e.g. `nats`, default `http`)
+- Store: `go-micro.dev/v5/store/*` (e.g. `postgres`, `mysql`, `nats-js-kv`, `memory`)
+- Auth, Cache, etc. follow the same pattern under their respective directories.
+
+## Registry Examples
+
+Consul:
+```go
+import (
+    "go-micro.dev/v5"
+    "go-micro.dev/v5/registry/consul"
+)
+
+func main() {
+    reg := consul.NewConsulRegistry()
+    svc := micro.NewService(
+        micro.Registry(reg),
+    )
+    svc.Init()
+    svc.Run()
+}
+```
+
+Etcd:
+```go
+import (
+    "go-micro.dev/v5"
+    "go-micro.dev/v5/registry/etcd"
+)
+
+func main() {
+    reg := etcd.NewRegistry()
+    svc := micro.NewService(micro.Registry(reg))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Broker Examples
+
+NATS:
+```go
+import (
+    "go-micro.dev/v5"
+    bnats "go-micro.dev/v5/broker/nats"
+)
+
+func main() {
+    b := bnats.NewNatsBroker()
+    svc := micro.NewService(micro.Broker(b))
+    svc.Init()
+    svc.Run()
+}
+```
+
+RabbitMQ:
+```go
+import (
+    "go-micro.dev/v5"
+    "go-micro.dev/v5/broker/rabbitmq"
+)
+
+func main() {
+    b := rabbitmq.NewBroker()
+    svc := micro.NewService(micro.Broker(b))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Transport Example (NATS)
+```go
+import (
+    "go-micro.dev/v5"
+    tnats "go-micro.dev/v5/transport/nats"
+)
+
+func main() {
+    t := tnats.NewTransport()
+    svc := micro.NewService(micro.Transport(t))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Store Examples
+
+Postgres:
+```go
+import (
+    "go-micro.dev/v5"
+    postgres "go-micro.dev/v5/store/postgres"
+)
+
+func main() {
+    st := postgres.NewStore()
+    svc := micro.NewService(micro.Store(st))
+    svc.Init()
+    svc.Run()
+}
+```
+
+NATS JetStream KV:
+```go
+import (
+    "go-micro.dev/v5"
+    natsjskv "go-micro.dev/v5/store/nats-js-kv"
+)
+
+func main() {
+    st := natsjskv.NewStore()
+    svc := micro.NewService(micro.Store(st))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Notes
+- Defaults: If you don’t set an implementation, Go Micro uses sensible in-memory or local defaults (e.g., mDNS for registry, HTTP transport, memory broker/store).
+- Options: Each plugin exposes constructor options to configure addresses, credentials, TLS, etc.
+- Imports: Only import the plugin you need; this keeps binaries small and dependencies explicit.

internal/website/docs/registry.md

@@ -20,6 +20,23 @@ Go Micro supports multiple registry backends, including:
 
 You can configure the registry when initializing your service.
 
+## Plugins Location
+
+Registry plugins live in this repository under `go-micro.dev/v5/registry/<plugin>` (e.g., `consul`, `etcd`, `nats`). Import the desired package and pass it via `micro.Registry(...)`.
+
+## Configure via environment
+
+```
+MICRO_REGISTRY=etcd MICRO_REGISTRY_ADDRESS=127.0.0.1:2379 micro server
+```
+
+Common variables:
+- `MICRO_REGISTRY`: selects the registry implementation (`mdns`, `consul`, `etcd`, `nats`).
+- `MICRO_REGISTRY_ADDRESS`: comma-separated list of registry addresses.
+
+Backend-specific variables:
+- Etcd: `ETCD_USERNAME`, `ETCD_PASSWORD` for authenticated clusters.
+
 ## Example Usage
 
 Here's how to use a custom registry (e.g., Consul) in your Go Micro service:

internal/website/docs/store.md

@@ -13,11 +13,14 @@ The store provides a pluggable interface for data storage in Go Micro.
 ## Implementations
 Supported stores include:
 - Memory (default)
-- File
-- MySQL
-- Redis
+- File (`go-micro.dev/v5/store/file`)
+- MySQL (`go-micro.dev/v5/store/mysql`)
+- Postgres (`go-micro.dev/v5/store/postgres`)
+- NATS JetStream KV (`go-micro.dev/v5/store/nats-js-kv`)
 
-Configure the store as needed for your application.
+Plugins are scoped under `go-micro.dev/v5/store/<plugin>`.
+
+Configure the store in code or via environment variables.
 
 ## Example Usage
 
@@ -49,3 +52,49 @@ func main() {
     log.Printf("Read value: %s", string(recs[0].Value))
 }
 ```
+
+## Configure a specific store in code
+
+Postgres:
+```go
+import (
+    "go-micro.dev/v5"
+    postgres "go-micro.dev/v5/store/postgres"
+)
+
+func main() {
+    st := postgres.NewStore()
+    svc := micro.NewService(micro.Store(st))
+    svc.Init()
+    svc.Run()
+}
+```
+
+NATS JetStream KV:
+```go
+import (
+    "go-micro.dev/v5"
+    natsjskv "go-micro.dev/v5/store/nats-js-kv"
+)
+
+func main() {
+    st := natsjskv.NewStore()
+    svc := micro.NewService(micro.Store(st))
+    svc.Init()
+    svc.Run()
+}
+```
+
+## Configure via environment
+
+```
+MICRO_STORE=postgres MICRO_STORE_ADDRESS=postgres://user:pass@127.0.0.1:5432/db \
+MICRO_STORE_DATABASE=micro MICRO_STORE_TABLE=micro \
+micro server
+```
+
+Common variables:
+- `MICRO_STORE`: selects the store implementation (`memory`, `file`, `mysql`, `postgres`, `nats-js-kv`).
+- `MICRO_STORE_ADDRESS`: connection/address string for the store (plugin-specific format).
+- `MICRO_STORE_DATABASE`: logical database or namespace (plugin-specific).
+- `MICRO_STORE_TABLE`: logical table/bucket (plugin-specific).

internal/website/docs/transport.md

@@ -12,10 +12,14 @@ The transport layer is responsible for communication between services.
 
 ## Implementations
 Supported transports include:
-- TCP (default)
-- gRPC
+- HTTP (default)
+- NATS (`go-micro.dev/v5/transport/nats`)
+- gRPC (`go-micro.dev/v5/transport/grpc`)
+- Memory (`go-micro.dev/v5/transport/memory`)
 
-You can specify the transport when initializing your service.
+Plugins are scoped under `go-micro.dev/v5/transport/<plugin>`.
+
+You can specify the transport when initializing your service or via env vars.
 
 ## Example Usage
 
@@ -38,3 +42,28 @@ func main() {
     service.Run()
 }
 ```
+
+NATS transport:
+```go
+import (
+    "go-micro.dev/v5"
+    tnats "go-micro.dev/v5/transport/nats"
+)
+
+func main() {
+    t := tnats.NewTransport()
+    service := micro.NewService(micro.Transport(t))
+    service.Init()
+    service.Run()
+}
+```
+
+## Configure via environment
+
+```
+MICRO_TRANSPORT=nats MICRO_TRANSPORT_ADDRESS=nats://127.0.0.1:4222 micro server
+```
+
+Common variables:
+- `MICRO_TRANSPORT`: selects the transport implementation (`http`, `nats`, `grpc`, `memory`).
+- `MICRO_TRANSPORT_ADDRESS`: comma-separated list of transport addresses.