docs: readme

.github/workflows/tests.yaml

@@ -6,6 +6,8 @@ name: tests
 on:
   push:
     branches: [ main ]
+  pull_request:
+    branches: [ '*' ]
 
 permissions:
   contents: read

README.md

@@ -1,3 +1,56 @@
 # gocosi
 
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](CODE_OF_CONDUCT.md)
+[![GitHub](https://img.shields.io/github/license/doomshrine/gocosi)](LICENSE.txt)
+[![Go Report Card](https://goreportcard.com/badge/github.com/doomshrine/gocosi)](https://goreportcard.com/report/github.com/doomshrine/gocosi)
+[![codecov](https://codecov.io/gh/shanduur/gocosi/branch/main/graph/badge.svg?token=8NA6HYH122)](https://codecov.io/gh/shanduur/gocosi)
+[![GitHub Workflow Status (with event)](https://img.shields.io/github/actions/workflow/status/doomshrine/gocosi/tests.yaml)](https://github.com/shanduur/gocosi/actions/workflows/tests.yaml)
+[![Static Badge](https://img.shields.io/badge/COSI_Specification-v1alpha1-green)](https://github.com/kubernetes-sigs/container-object-storage-interface-spec/tree/v0.1.0)
+
+A Container Object Storage Interface (COSI) library and other helpful utilities created with Go, that simplify process of writing your own Object Storage Plugin (OSP).
+
+## Table of contents
+
+- [gocosi](#gocosi)
+  - [Table of contents](#table-of-contents)
+  - [Quick Start](#quick-start)
+  - [Configuration](#configuration)
+    - [Environment variables](#environment-variables)
+
+## Quick Start
+
+The following example illustrates using `gocosi` Object Storage Plugin bootstrapper to create a new COSI Object Storage Plugin from scratch:
+
+```bash
+mkdir -p cosi-osp && cd cosi-osp
+go run \
+  github.com/doomshrine/gocosi/cmd/generate@main \
+  example.com/your/cosi-osp
+```
+
+You will obtain the following file structure in the `cosi-osp` folder:
+
+```
+cosi-osp
+├── go.mod
+├── go.sum
+├── main.go
+└── servers
+    ├── identity
+    │   └── identity.go
+    └── provisioner
+        └── provisioner.go
+
+4 directories, 5 files
+```
+
+## Configuration
+
+### Environment variables
+
+`gocosi` defines several constants used to specify environment variables for configuring the COSI (Container Object Storage Interface) endpoint. The COSI endpoint is used to interact with an object storage plugin in a containerized environment.
+
+- `COSI_ENDPOINT` (default: `unix:///var/lib/cosi/cosi.sock`) - it should be set to the address or location of the COSI endpoint, such as the URL or file path.
+- `X_COSI_ENDPOINT_PERMS` (default: `0755`) - it should be set when the COSI endpoint is a UNIX socket file. It determines the file permissions (in octal notation) of the UNIX socket file. If the COSI endpoint is a TCP socket, this setting has no effect.
+- `X_COSI_ENDPOINT_USER`  (default: *The user that starts the process*) - it should be set when the COSI endpoint is a UNIX socket file. It determines the owner (user) of the UNIX socket file. If the COSI endpoint is a TCP socket, this setting has no effect.
+- `X_COSI_ENDPOINT_GROUP` (default: *The group that starts the process*) - it should be set when the COSI endpoint is a UNIX socket file. It determines the group ownership of the UNIX socket file. If the COSI endpoint is a TCP socket, this setting has no effect.

cmd/generate/main.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Doomshrine and gocosi authors. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package main
 
 import (

cmd/generate/templates.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package main
 
 const mainGo = `package main

doc.go

@@ -0,0 +1,44 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package gocosi is a Container Object Storage Interface (COSI) library that simplifies process of writing your own Object Storage Plugin (OSP).
+//
+// ## Quick Start
+//
+// The following example illustrates using `gocosi` Object Storage Plugin bootstrapper to create a new COSI Object Storage Plugin from scratch:
+//
+// ```bash
+// mkdir -p cosi-osp && cd cosi-osp
+//
+//	go run \
+//	  github.com/doomshrine/gocosi/cmd/generate@main \
+//	  example.com/your/cosi-osp
+//
+// ```
+//
+// You will obtain the following file structure in the `cosi-osp` folder:
+//
+// ```
+// cosi-osp
+// ├── go.mod
+// ├── go.sum
+// ├── main.go
+// └── servers
+//
+//	├── identity
+//	│   └── identity.go
+//	└── provisioner
+//	    └── provisioner.go
+//
+// 4 directories, 5 files
+// ```
+package gocosi

endpoint.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi
 
 import (
@@ -15,6 +27,7 @@ import (
 	"github.com/doomshrine/must"
 )
 
+// Schemes supported by COSI.
 const (
 	SchemeUNIX = "unix"
 	SchemeTCP  = "tcp"

endpoint_test.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi
 
 import (

env.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi
 
 const (
@@ -24,11 +36,9 @@ const (
 	// specifies a TCP socket. The default value is the group that starts
 	// the process.
 	EnvCOSIEndpointGroup = "X_COSI_ENDPOINT_GROUP"
-
-	// EnvOTELCollectorEndpoint is ... TODO: continue the description.
-	EnvOTELCollectorEndpoint = "X_OPEN_TELEMETRY_COLLECTOR_ENDPOINT"
 )
 
 const (
+	// cosiSocket is default location of COSI UNIX socket.
 	cosiSocket = "unix:///var/lib/cosi/cosi.sock"
 )

env_test.go

@@ -1 +1,13 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi

gocosi.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi
 
 import (
@@ -39,7 +51,7 @@ func New(identity cosi.IdentityServer, provisioner cosi.ProvisionerServer, opts
 		provisioner: provisioner,
 
 		endpoint: &Endpoint{
-			permissions: 0o660,
+			permissions: 0o755,
 			address:     must.Do(url.Parse(cosiSocket)),
 		},
 	}

gocosi_test.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi
 
 import (

grpc/handlers/handlers.go

@@ -1,3 +1,16 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package handlers includes common HandlerFuncs that can be used around the gRPC environment.
 package handlers
 
 import (
@@ -8,6 +21,8 @@ import (
 	"github.com/grpc-ecosystem/go-grpc-middleware/v2/interceptors/recovery"
 )
 
+// PanicRecovery returns handler of the panics, that logs the panic and call stack.
+// It take optional argument called callbacks, that are functions, e.g. wrapping incrementing the panicMetric.
 func PanicRecovery(logger *log.Logger, callbacks ...func(context.Context)) recovery.RecoveryHandlerFunc {
 	return func(p any) (err error) {
 		ctx := context.Background()
@@ -16,10 +31,12 @@ func PanicRecovery(logger *log.Logger, callbacks ...func(context.Context)) recov
 			callback(ctx)
 		}
 
-		logger.Log(ctx, 0,
-			"recovered from panic",
-			"panic", p,
-			"stack", debug.Stack())
+		if logger != nil {
+			logger.Log(ctx, 0,
+				"recovered from panic",
+				"panic", p,
+				"stack", debug.Stack())
+		}
 
 		return nil
 	}

grpc/log/log.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package log
 
 import (

metrics.go

@@ -1,3 +1,15 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi
 
 import (
@@ -6,7 +18,7 @@ import (
 )
 
 var (
-	meter = otel.Meter("github.com/doomshrine/gocosi")
+	DefaultMeter = otel.Meter("github.com/doomshrine/gocosi")
 
-	panicsTotal = must.Do(meter.Int64Counter("grpc_req_panics_recovered_total"))
+	PanicsTotal = must.Do(DefaultMeter.Int64Counter("grpc_req_panics_recovered_total"))
 )

mocking.go

@@ -1,13 +1,27 @@
+// Copyright © 2023 Dell Inc. or its subsidiaries. All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//      http://www.apache.org/licenses/LICENSE-2.0
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
 package gocosi
 
 import cosi "sigs.k8s.io/container-object-storage-interface-spec"
 
 //go:generate go run github.com/vektra/mockery/v2@v2.32.0
 
+// COSIProvisionerServer is a wrapper around cosi.ProvisionerServer so the mock can be generated.
 type COSIProvisionerServer interface {
 	cosi.ProvisionerServer
 }
 
+// COSIIdentityServer is a wrapper around cosi.IdentityServer so the mock can be generated.
 type COSIIdentityServer interface {
 	cosi.IdentityServer
 }