docs: Improve comments and docs for welcoming helix.ts

Signed-off-by: Loïc Saint-Roch <[email protected]>

Author: loicsaintroch

README.md

@@ -6,16 +6,11 @@
 [![GitHub Release](https://img.shields.io/github/v/release/nunchistudio/helix.go)](https://github.com/nunchistudio/helix.go/releases/latest)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
 
-helix.go is the Go implementation of [helix](https://github.com/nunchistudio/helix).
-
-helix.go was developed with the following use cases in mind:
-
-- Consistent and high-performance (micro) services;
-- Effortless end-to-end observability and event propagation across services.
-
-By using helix.go, organizations can benefit from automatic distributed tracing,
-error recording, and event propagation across Go services and integrations with
-no additional lines of code!
+helix.go is the Go implementation of [helix](https://github.com/nunchistudio/helix),
+for building cloud-native, consistent, reliable, and high-performance (micro)
+services. It allows back-end engineers to simplify development of complex problems
+through a thin layer of abstraction that handles automatic logging, tracing,
+observability, and event propagation across services and integrations.
 
 ![Event propagation with helix](https://nunchi.studio/helix/screenshots/trace-distributed.png)
 

documentation/api-references.md

@@ -20,7 +20,7 @@ import (
   "context"
   "errors"
 
-  natsinte "go.nunchi.studio/helix/integration/nats"
+  "go.nunchi.studio/helix/integration/nats"
   "go.nunchi.studio/helix/service"
   "go.nunchi.studio/helix/telemetry/trace"
 
@@ -32,7 +32,7 @@ App holds the different components needed to run our Go service. In this
 case, it only holds a NATS JetStream context.
 */
 type App struct {
-  JetStream natsinte.JetStream
+  JetStream nats.JetStream
 }
 
 /*
@@ -47,7 +47,7 @@ func NewAndStart() error {
 
   // First, create a new NATS JetStream context. We keep empty config but feel
   // free to dive more later for advanced configuration.
-  js, err := natsinte.Connect(natsinte.Config{})
+  js, err := nats.Connect(nats.Config{})
   if err != nil {
     return err
   }
@@ -58,7 +58,7 @@ func NewAndStart() error {
   }
 
   // Create a new stream in NATS JetStream called "demo-stream", for subject "demo".
-  stream, _ := js.CreateStream(context.Background(), jetstream.StreamConfig{
+  stream, _ := js.CreateOrUpdateStream(context.Background(), jetstream.StreamConfig{
     Name:     "demo-stream",
     Subjects: []string{"demo"},
   })

documentation/from-zero-to-hero-second.md

@@ -11,9 +11,8 @@ var _ error = (*Error)(nil)
 
 /*
 Error implements the Go native error type and is designed for handling errors
-in the helix.go ecosystem. When exposing errors to clients (such as via HTTP
-API), the root error should not give away too much information such as internal
-messages.
+in the helix ecosystem. When exposing errors to clients (such as via HTTP API),
+the root error should not give away too much information such as internal messages.
 */
 type Error struct {
 
@@ -30,9 +29,9 @@ type Error struct {
 	// Message is the top-level message of the error.
 	Message string `json:"message"`
 
-	// Validations represents a list of failed configuration validations. This is
-	// used when a Integration's configuration encountered errors related to values
-	// set by clients.
+	// Validations represents a list of failure validations related to the error
+	// itself. This allows to pass/retrieve additional details, such as validation
+	// failures encountered in the request payload.
 	Validations []Validation `json:"validations,omitempty"`
 
 	// Children holds child errors encountered in cascade related to the current
@@ -53,7 +52,7 @@ type Validation struct {
 	//
 	// Example:
 	//
-	//   []string{"Options", "Producer", "MaxRetries"}
+	//   []string{"request", "body", "user", "email"}
 	Path []string `json:"path,omitempty"`
 }
 

errorstack/error.go

@@ -1,6 +1,6 @@
 /*
 Package errorstack exposes a set of utilities for consistent error handling in
-the helix.go ecosystem. Every package in helix.go relies on this one.
+the helix ecosystem. Every package in helix.go relies on this one.
 
 This package must not import any other package of this ecosystem.
 */

errorstack/overview.go

@@ -5,8 +5,7 @@ import (
 )
 
 /*
-Key is the key that shall be present in a JSON-encoded value representing
-an Event.
+Key is the key that shall be present in a JSON-encoded value representing an Event.
 
 Example:
 

event/json.go

@@ -3,7 +3,7 @@ Package event exposes some objects and utilities to get/set contextual informati
 about an event. In a distributed architecture where events are flowing across
 internal services and third-party integrations, it is highly encouraged to pass
 an Event through a context.Context in order to trace them from end-to-end.
-helix.go core and integrations relies on contexts to manage logs and traces
+helix.go core and integrations rely on Go contexts to manage logs and traces
 across services.
 
 This package must not import any other package of this ecosystem.

event/overview.go

@@ -3,7 +3,7 @@ module go.nunchi.studio/helix/integration/nats
 go 1.22
 
 require (
-	github.com/nats-io/nats.go v1.33.0
+	github.com/nats-io/nats.go v1.33.1
 	github.com/stretchr/testify v1.8.4
 	go.nunchi.studio/helix v0.17.0
 	go.opentelemetry.io/otel v1.23.1

integration/nats/go.mod

@@ -21,8 +21,8 @@ github.com/kr/pretty v0.3.1 h1:flRD4NNwYAUpkphVc1HcthR4KEIFJ65n8Mw5qdRn3LE=
 github.com/kr/pretty v0.3.1/go.mod h1:hoEshYVHaxMs3cyo3Yncou5ZscifuDolrwPKZanG3xk=
 github.com/kr/text v0.2.0 h1:5Nx0Ya0ZqY2ygV366QzturHI13Jq95ApcVaJBhpS+AY=
 github.com/kr/text v0.2.0/go.mod h1:eLer722TekiGuMkidMxC/pM04lWEeraHUUmBw8l2grE=
-github.com/nats-io/nats.go v1.33.0 h1:rRg0l2F29B30n6EPl0j50hl8eYp7rA2ecoJ74E62US8=
-github.com/nats-io/nats.go v1.33.0/go.mod h1:Ubdu4Nh9exXdSz0RVWRFBbRfrbSxOYd26oF0wkWclB8=
+github.com/nats-io/nats.go v1.33.1 h1:8TxLZZ/seeEfR97qV0/Bl939tpDnt2Z2fK3HkPypj70=
+github.com/nats-io/nats.go v1.33.1/go.mod h1:Ubdu4Nh9exXdSz0RVWRFBbRfrbSxOYd26oF0wkWclB8=
 github.com/nats-io/nkeys v0.4.7 h1:RwNJbbIdYCoClSDNY7QVKZlyb/wfT6ugvFCiKy6vDvI=
 github.com/nats-io/nkeys v0.4.7/go.mod h1:kqXRgRDPlGy7nGaEDMuYzmiJCIAAWDK0IMBtDmGD0nc=
 github.com/nats-io/nuid v1.0.1 h1:5iA8DT8V7q8WK2EScv2padNa/rTESc1KdnPw4TC2paw=

integration/nats/go.sum

@@ -46,7 +46,7 @@ retrieved or request times out.
 It automatically handles tracing and error recording.
 */
 func (c *consumer) Fetch(ctx context.Context, batch int, opts ...jetstream.FetchOpt) (jetstream.MessageBatch, error) {
-	_, span := trace.Start(ctx, trace.SpanKindClient, fmt.Sprintf("%s: Consumer / Fetch", humanized))
+	_, span := trace.Start(ctx, trace.SpanKindConsumer, fmt.Sprintf("%s: Consumer / Fetch", humanized))
 	defer span.End()
 
 	var err error
@@ -70,7 +70,7 @@ exceeded or request times out.
 It automatically handles tracing and error recording.
 */
 func (c *consumer) FetchBytes(ctx context.Context, maxBytes int, opts ...jetstream.FetchOpt) (jetstream.MessageBatch, error) {
-	_, span := trace.Start(ctx, trace.SpanKindClient, fmt.Sprintf("%s: Consumer / FetchBytes", humanized))
+	_, span := trace.Start(ctx, trace.SpanKindConsumer, fmt.Sprintf("%s: Consumer / FetchBytes", humanized))
 	defer span.End()
 
 	var err error
@@ -94,7 +94,7 @@ provided number of messages.
 It automatically handles tracing and error recording.
 */
 func (c *consumer) FetchNoWait(ctx context.Context, batch int) (jetstream.MessageBatch, error) {
-	_, span := trace.Start(ctx, trace.SpanKindClient, fmt.Sprintf("%s: Consumer / FetchNoWait", humanized))
+	_, span := trace.Start(ctx, trace.SpanKindConsumer, fmt.Sprintf("%s: Consumer / FetchNoWait", humanized))
 	defer span.End()
 
 	var err error