revise doc (#51)

config/konf.go

@@ -7,14 +7,13 @@
 //
 // It loads configuration from the following sources,
 // and each source takes precedence over the sources below it:
-//
+//   - environment variables which matches the following pattern:
+//     prefix + "_" + key, all in ALL CAPS.
+//     For example, FOO_BAR is the name of environment variable for configuration `foo.bar`.
 //   - config files specified by WithFS and WithFile.
 //     WithFile also can be overridden by the environment variable `CONFIG_FILE`.
 //     For example, if CONFIG_FILE = "f1, f2,f3", it will load f1, f2, and f3,
 //     and each file takes precedence over the files before it.
-//   - environment variables which matches the following pattern:
-//     prefix + "_" + key, all in ALL CAPS.
-//     For example, FOO_BAR is the name of environment variable for configuration `foo.bar`.
 //
 // [konf]: https://pkg.go.dev/github.com/nil-go/konf
 package config

dev/doc.go

@@ -0,0 +1,7 @@
+// Copyright (c) 2024 The nilgo authors
+// Use of this source code is governed by a MIT license found in the LICENSE file.
+
+// Package dev provides function useful for local development.
+//
+// Please note that the functions in this package are not intended for production use.
+package dev

pprof.go → dev/pprof.go

@@ -1,7 +1,7 @@
 // Copyright (c) 2024 The nilgo authors
 // Use of this source code is governed by a MIT license found in the LICENSE file.
 
-package nilgo
+package dev
 
 import (
 	"context"
@@ -10,25 +10,15 @@ import (
 	"log/slog"
 	"net"
 	"net/http"
-	"net/http/pprof"
+	_ "net/http/pprof" //nolint:gosec
 	"runtime"
 	"time"
 )
 
-// PProf starts a pprof server at localhost:6060.
-//
+// Pprof starts a pprof server at localhost:6060.
 // If port 6060 is not available, it will try to find an available port.
-func PProf(ctx context.Context) error {
-	mux := http.NewServeMux()
-	mux.HandleFunc("/debug/pprof/", pprof.Index)
-	mux.HandleFunc("/debug/pprof/cmdline", pprof.Cmdline)
-	mux.HandleFunc("/debug/pprof/profile", pprof.Profile)
-	mux.HandleFunc("/debug/pprof/symbol", pprof.Symbol)
-	mux.HandleFunc("/debug/pprof/trace", pprof.Trace)
-	server := &http.Server{
-		Handler:     mux,
-		ReadTimeout: time.Second,
-	}
+func Pprof(ctx context.Context) error {
+	server := &http.Server{ReadTimeout: time.Second}
 
 	defer context.AfterFunc(ctx, func() {
 		slog.LogAttrs(ctx, slog.LevelInfo, "Starting shutdown pprof Server...")

pprof_test.go → dev/pprof_test.go

@@ -3,7 +3,7 @@
 
 //go:build !race
 
-package nilgo_test
+package dev_test
 
 import (
 	"context"
@@ -12,6 +12,7 @@ import (
 	"time"
 
 	"github.com/nil-go/nilgo"
+	"github.com/nil-go/nilgo/dev"
 	"github.com/nil-go/nilgo/internal/assert"
 )
 
@@ -20,7 +21,7 @@ func TestPProf(t *testing.T) {
 	defer cancel()
 
 	go func() {
-		assert.NoError(t, nilgo.Run(nilgo.PProf))
+		assert.NoError(t, nilgo.Run(dev.Pprof))
 	}()
 	time.Sleep(100 * time.Millisecond) // wait for pprof server to start.
 

examples/grpc/cmd/main.go

@@ -12,6 +12,7 @@ import (
 
 	"github.com/nil-go/nilgo"
 	"github.com/nil-go/nilgo/config"
+	"github.com/nil-go/nilgo/dev"
 	"github.com/nil-go/nilgo/gcp"
 	"github.com/nil-go/nilgo/gcp/profiler"
 	ngrpc "github.com/nil-go/nilgo/grpc"
@@ -24,7 +25,7 @@ func main() {
 	var args []any
 	switch {
 	case metadata.OnGCE():
-		opts, err := gcp.Options(
+		opts, err := gcp.Args(
 			gcp.WithLog(),
 			gcp.WithTrace(),
 			gcp.WithMetric(),
@@ -35,7 +36,7 @@ func main() {
 		}
 		args = append(args, opts...)
 	default:
-		args = append(args, nilgo.PProf)
+		args = append(args, dev.Pprof)
 	}
 	args = append(args,
 		config.WithFS(configFS),

examples/http/cmd/main.go

@@ -14,6 +14,7 @@ import (
 
 	"github.com/nil-go/nilgo"
 	"github.com/nil-go/nilgo/config"
+	"github.com/nil-go/nilgo/dev"
 	"github.com/nil-go/nilgo/gcp"
 	nhttp "github.com/nil-go/nilgo/http"
 )
@@ -25,7 +26,7 @@ func main() {
 	var args []any
 	switch {
 	case metadata.OnGCE():
-		opts, err := gcp.Options(
+		opts, err := gcp.Args(
 			gcp.WithLog(),
 			gcp.WithTrace(),
 			gcp.WithMetric(),
@@ -36,7 +37,7 @@ func main() {
 		}
 		args = append(args, opts...)
 	default:
-		args = append(args, nilgo.PProf)
+		args = append(args, dev.Pprof)
 	}
 
 	mux := http.NewServeMux()

gcp/gcp.go

@@ -33,37 +33,32 @@ import (
 	"github.com/nil-go/nilgo/gcp/profiler"
 )
 
-// Options provides the [nilgo.Run] options for application runs on GCP.
-//
-// By default, only logging and error reporting are configured.
-// Profiler need to enable explicitly
-// using corresponding Option(s).
-func Options(opts ...Option) ([]any, error) { //nolint:cyclop,funlen
+// Args provides the [nilgo.Run] args with given options for application runs on GCP.
+func Args(opts ...Option) ([]any, error) { //nolint:cyclop,funlen
 	option := options{}
 	for _, opt := range opts {
 		opt(&option)
 	}
-	if option.project == "" {
-		option.project, _ = metadata.ProjectID()
-	}
+
+	// Get service and version from Google Cloud Run environment variables.
 	if option.service == "" {
 		option.service = os.Getenv("K_SERVICE")
 	}
 	if option.version == "" {
 		option.version = os.Getenv("K_REVISION")
 	}
-
-	if option.logOpts != nil {
-		option.logOpts = append([]gcp.Option{gcp.WithErrorReporting(option.service, option.version)}, option.logOpts...)
-	}
 	if option.project == "" {
-		return []any{gcp.New(option.logOpts...)}, nil
+		option.project, _ = metadata.ProjectID()
 	}
 
-	if option.traceOpts != nil {
-		option.logOpts = append([]gcp.Option{gcp.WithTrace(option.project)}, option.logOpts...)
+	var appOpts []any
+	if option.logOpts != nil {
+		option.logOpts = append([]gcp.Option{gcp.WithErrorReporting(option.service, option.version)}, option.logOpts...)
+		if option.traceOpts != nil {
+			option.logOpts = append([]gcp.Option{gcp.WithTrace(option.project)}, option.logOpts...)
+		}
+		appOpts = append(appOpts, gcp.New(option.logOpts...))
 	}
-	appOpts := []any{gcp.New(option.logOpts...)}
 
 	res := resource.Default()
 	ctx := context.Background()

gcp/gcp_test.go

@@ -8,7 +8,6 @@ import (
 	"log/slog"
 	"testing"
 
-	sgcp "github.com/nil-go/sloth/gcp"
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"go.opentelemetry.io/otel/sdk/metric"
@@ -27,11 +26,9 @@ func TestOptions(t *testing.T) {
 		assertion   func(*testing.T, []any)
 	}{
 		{
-			description: "with project",
+			description: "with log",
 			opts: []gcp.Option{
-				gcp.WithProject("project"),
-				gcp.WithService("service"),
-				gcp.WithVersion("version"),
+				gcp.WithLog(),
 			},
 			assertion: func(t *testing.T, opts []any) {
 				t.Helper()
@@ -42,16 +39,20 @@ func TestOptions(t *testing.T) {
 			},
 		},
 		{
-			description: "with options",
+			description: "with log and trace",
 			opts: []gcp.Option{
 				gcp.WithProject("project"),
+				gcp.WithLog(),
+				gcp.WithTrace(),
 			},
 			assertion: func(t *testing.T, opts []any) {
 				t.Helper()
 
-				assert.Len(t, opts, 1)
+				assert.Len(t, opts, 2)
 				_, ok := opts[0].(slog.Handler)
 				assert.True(t, ok)
+				_, ok = opts[1].(*trace.TracerProvider)
+				assert.True(t, ok)
 			},
 		},
 		{
@@ -63,10 +64,8 @@ func TestOptions(t *testing.T) {
 			assertion: func(t *testing.T, opts []any) {
 				t.Helper()
 
-				assert.Len(t, opts, 2)
-				_, ok := opts[0].(slog.Handler)
-				assert.True(t, ok)
-				_, ok = opts[1].(func(context.Context) error)
+				assert.Len(t, opts, 1)
+				_, ok := opts[0].(func(context.Context) error)
 				assert.True(t, ok)
 			},
 		},
@@ -79,10 +78,8 @@ func TestOptions(t *testing.T) {
 			assertion: func(t *testing.T, opts []any) {
 				t.Helper()
 
-				assert.Len(t, opts, 2)
-				_, ok := opts[0].(slog.Handler)
-				assert.True(t, ok)
-				_, ok = opts[1].(*trace.TracerProvider)
+				assert.Len(t, opts, 1)
+				_, ok := opts[0].(*trace.TracerProvider)
 				assert.True(t, ok)
 			},
 		},
@@ -95,24 +92,8 @@ func TestOptions(t *testing.T) {
 			assertion: func(t *testing.T, opts []any) {
 				t.Helper()
 
-				assert.Len(t, opts, 2)
-				_, ok := opts[0].(slog.Handler)
-				assert.True(t, ok)
-				_, ok = opts[1].(*metric.MeterProvider)
-				assert.True(t, ok)
-			},
-		},
-		{
-			description: "without project",
-			opts: []gcp.Option{
-				gcp.WithLog(sgcp.WithLevel(slog.LevelError)),
-				gcp.WithProfiler(),
-			},
-			assertion: func(t *testing.T, opts []any) {
-				t.Helper()
-
 				assert.Len(t, opts, 1)
-				_, ok := opts[0].(slog.Handler)
+				_, ok := opts[0].(*metric.MeterProvider)
 				assert.True(t, ok)
 			},
 		},
@@ -124,7 +105,7 @@ func TestOptions(t *testing.T) {
 		t.Run(testcase.description, func(t *testing.T) {
 			t.Parallel()
 
-			opts, err := gcp.Options(testcase.opts...)
+			opts, err := gcp.Args(testcase.opts...)
 			require.NoError(t, err)
 			testcase.assertion(t, opts)
 		})

gcp/option.go

@@ -21,7 +21,7 @@ func WithProject(project string) Option {
 
 // WithService provides the GCP service name.
 //
-// By default, it reads from environment variable "K_SERVICE" if it's running on GCP.
+// By default, it reads from environment variable "K_SERVICE" if it's running on Google Cloud Run.
 func WithService(service string) Option {
 	return func(options *options) {
 		options.service = service
@@ -30,7 +30,7 @@ func WithService(service string) Option {
 
 // WithVersion provides the GCP service version.
 //
-// By default, it reads from environment variable "K_REVISION" if it's running on GCP.
+// By default, it reads from environment variable "K_REVISION" if it's running on Google Cloud Run.
 func WithVersion(version string) Option {
 	return func(options *options) {
 		options.version = version

gcp/profiler/profiler.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2024 The nilgo authors
 // Use of this source code is governed by a MIT license found in the LICENSE file.
 
+// Package profiler enables the Cloud Profiler for the application.
 package profiler
 
 import (
@@ -12,6 +13,10 @@ import (
 	"google.golang.org/api/option"
 )
 
+// Run starts the Cloud Profiler with given options.
+//
+// It's not indented to be used directly in the application.
+// Please use [gcp.WithProfiler] instead.
 func Run(opts ...option.ClientOption) func(context.Context) error {
 	return func(ctx context.Context) error {
 		config := profiler.Config{}

grpc/client/client.go

@@ -1,6 +1,7 @@
 // Copyright (c) 2024 The nilgo authors
 // Use of this source code is governed by a MIT license found in the LICENSE file.
 
+// Package client provides utilities for gRPC client.
 package client
 
 import (