examples: unix abstract socket (#4848)

examples/examples_test.sh

@@ -58,6 +58,7 @@ EXAMPLES=(
     "features/metadata"
     "features/multiplex"
     "features/name_resolving"
+    "features/unix_abstract"
 )
 
 declare -A EXPECTED_SERVER_OUTPUT=(
@@ -73,6 +74,7 @@ declare -A EXPECTED_SERVER_OUTPUT=(
     ["features/metadata"]="message:\"this is examples/metadata\", sending echo"
     ["features/multiplex"]=":50051"
     ["features/name_resolving"]="serving on localhost:50051"
+    ["features/unix_abstract"]="serving on @abstract-unix-socket"
 )
 
 declare -A EXPECTED_CLIENT_OUTPUT=(
@@ -88,6 +90,7 @@ declare -A EXPECTED_CLIENT_OUTPUT=(
     ["features/metadata"]="this is examples/metadata"
     ["features/multiplex"]="Greeting:  Hello multiplex"
     ["features/name_resolving"]="calling helloworld.Greeter/SayHello to \"example:///resolver.example.grpc.io\""
+    ["features/unix_abstract"]="calling echo.Echo/UnaryEcho to unix-abstract:abstract-unix-socket"
 )
 
 cd ./examples

examples/features/unix_abstract/README.md

@@ -0,0 +1,29 @@
+# Unix abstract sockets
+
+This examples shows how to start a gRPC server listening on a unix abstract
+socket and how to get a gRPC client to connect to it.
+
+## What is a unix abstract socket
+
+An abstract socket address is distinguished from a regular unix socket by the
+fact that the first byte of the address is a null byte ('\0'). The address has
+no connection with filesystem path names.
+
+## Try it
+
+```
+go run server/main.go
+```
+
+```
+go run client/main.go
+```
+
+## Explanation
+
+The gRPC server in this example listens on an address starting with a null byte
+and the network is `unix`. The client uses the `unix-abstract` scheme with the
+endpoint set to the abstract unix socket address without the null byte. The
+`unix` resolver takes care of adding the null byte on the client. See
+https://github.com/grpc/grpc/blob/master/doc/naming.md for the more details.
+

examples/features/unix_abstract/client/main.go

@@ -0,0 +1,68 @@
+//go:build linux
+// +build linux
+
+/*
+ *
+ * Copyright 2021 gRPC authors.
+ *
+ * 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.
+ *
+ */
+
+// Binary client is an example client which dials a server on an abstract unix
+// socket.
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"time"
+
+	"google.golang.org/grpc"
+	ecpb "google.golang.org/grpc/examples/features/proto/echo"
+)
+
+func callUnaryEcho(c ecpb.EchoClient, message string) {
+	ctx, cancel := context.WithTimeout(context.Background(), time.Second)
+	defer cancel()
+	r, err := c.UnaryEcho(ctx, &ecpb.EchoRequest{Message: message})
+	if err != nil {
+		log.Fatalf("could not greet: %v", err)
+	}
+	fmt.Println(r.Message)
+}
+
+func makeRPCs(cc *grpc.ClientConn, n int) {
+	hwc := ecpb.NewEchoClient(cc)
+	for i := 0; i < n; i++ {
+		callUnaryEcho(hwc, "this is examples/unix_abstract")
+	}
+}
+
+func main() {
+	// A dial target of `unix:@abstract-unix-socket` should also work fine for
+	// this example because of golang conventions (net.Dial behavior). But we do
+	// not recommend this since we explicitly added the `unix-abstract` scheme
+	// for cross-language compatibility.
+	addr := "unix-abstract:abstract-unix-socket"
+	cc, err := grpc.Dial(addr, grpc.WithInsecure(), grpc.WithBlock())
+	if err != nil {
+		log.Fatalf("grpc.Dial(%q) failed: %v", addr, err)
+	}
+	defer cc.Close()
+
+	fmt.Printf("--- calling echo.Echo/UnaryEcho to %s\n", addr)
+	makeRPCs(cc, 10)
+	fmt.Println()
+}

examples/features/unix_abstract/server/main.go

@@ -0,0 +1,58 @@
+//go:build linux
+// +build linux
+
+/*
+ *
+ * Copyright 2021 gRPC authors.
+ *
+ * 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.
+ *
+ */
+
+// Binary server is an example server listening for gRPC connections on an
+// abstract unix socket.
+package main
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"net"
+
+	"google.golang.org/grpc"
+
+	pb "google.golang.org/grpc/examples/features/proto/echo"
+)
+
+type ecServer struct {
+	pb.UnimplementedEchoServer
+	addr string
+}
+
+func (s *ecServer) UnaryEcho(ctx context.Context, req *pb.EchoRequest) (*pb.EchoResponse, error) {
+	return &pb.EchoResponse{Message: fmt.Sprintf("%s (from %s)", req.Message, s.addr)}, nil
+}
+
+func main() {
+	netw, addr := "unix", "\x00abstract-unix-socket"
+	lis, err := net.Listen(netw, addr)
+	if err != nil {
+		log.Fatalf("net.Listen(%q, %q) failed: %v", netw, addr, err)
+	}
+	s := grpc.NewServer()
+	pb.RegisterEchoServer(s, &ecServer{addr: addr})
+	log.Printf("serving on %s\n", lis.Addr().String())
+	if err := s.Serve(lis); err != nil {
+		log.Fatalf("failed to serve: %v", err)
+	}
+}