Move v1 examples to v1 subdirectory (#1963)

Motivation:

We'll need to add examples for v2, to make the separation more obvious
we can put them in version specfici subdirecoties.

Modifications:

- Move examples to v1
- Update package manifest
- Update proto generation script
- Update docs/tutorials

Result:

v1 examples are separated in their own directory

Package.swift

@@ -294,7 +294,7 @@ extension Target {
       .nio,
       .protobuf,
     ],
-    path: "Sources/Examples/Echo/Model"
+    path: "Sources/Examples/v1/Echo/Model"
   )
 
   static let echoImplementation: Target = .target(
@@ -306,7 +306,7 @@ extension Target {
       .nioHTTP2,
       .protobuf,
     ],
-    path: "Sources/Examples/Echo/Implementation"
+    path: "Sources/Examples/v1/Echo/Implementation"
   )
 
   static let echo: Target = .executableTarget(
@@ -323,7 +323,7 @@ extension Target {
     ].appending(
       .nioSSL, if: includeNIOSSL
     ),
-    path: "Sources/Examples/Echo/Runtime"
+    path: "Sources/Examples/v1/Echo/Runtime"
   )
 
   static let helloWorldModel: Target = .target(
@@ -333,7 +333,7 @@ extension Target {
       .nio,
       .protobuf,
     ],
-    path: "Sources/Examples/HelloWorld/Model"
+    path: "Sources/Examples/v1/HelloWorld/Model"
   )
 
   static let helloWorldClient: Target = .executableTarget(
@@ -345,7 +345,7 @@ extension Target {
       .nioPosix,
       .argumentParser,
     ],
-    path: "Sources/Examples/HelloWorld/Client"
+    path: "Sources/Examples/v1/HelloWorld/Client"
   )
 
   static let helloWorldServer: Target = .executableTarget(
@@ -357,7 +357,7 @@ extension Target {
       .nioPosix,
       .argumentParser,
     ],
-    path: "Sources/Examples/HelloWorld/Server"
+    path: "Sources/Examples/v1/HelloWorld/Server"
   )
 
   static let routeGuideModel: Target = .target(
@@ -367,7 +367,7 @@ extension Target {
       .nio,
       .protobuf,
     ],
-    path: "Sources/Examples/RouteGuide/Model"
+    path: "Sources/Examples/v1/RouteGuide/Model"
   )
 
   static let routeGuideClient: Target = .executableTarget(
@@ -379,7 +379,7 @@ extension Target {
       .nioPosix,
       .argumentParser,
     ],
-    path: "Sources/Examples/RouteGuide/Client"
+    path: "Sources/Examples/v1/RouteGuide/Client"
   )
 
   static let routeGuideServer: Target = .executableTarget(
@@ -392,7 +392,7 @@ extension Target {
       .nioPosix,
       .argumentParser,
     ],
-    path: "Sources/Examples/RouteGuide/Server"
+    path: "Sources/Examples/v1/RouteGuide/Server"
   )
 
   static let packetCapture: Target = .executableTarget(
@@ -405,7 +405,7 @@ extension Target {
       .nioExtras,
       .argumentParser,
     ],
-    path: "Sources/Examples/PacketCapture",
+    path: "Sources/Examples/v1/PacketCapture",
     exclude: [
       "README.md",
     ]
@@ -433,7 +433,7 @@ extension Target {
       .echoModel,
       .echoImplementation
     ],
-    path: "Sources/Examples/ReflectionService",
+    path: "Sources/Examples/v1/ReflectionService",
     resources: [
       .copy("Generated")
     ]

Package@swift-6.swift

@@ -586,7 +586,7 @@ extension Target {
         .nio,
         .protobuf,
       ],
-      path: "Sources/Examples/Echo/Model",
+      path: "Sources/Examples/v1/Echo/Model",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -601,7 +601,7 @@ extension Target {
         .nioHTTP2,
         .protobuf,
       ],
-      path: "Sources/Examples/Echo/Implementation",
+      path: "Sources/Examples/v1/Echo/Implementation",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -621,7 +621,7 @@ extension Target {
       ].appending(
         .nioSSL, if: includeNIOSSL
       ),
-      path: "Sources/Examples/Echo/Runtime",
+      path: "Sources/Examples/v1/Echo/Runtime",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -634,7 +634,7 @@ extension Target {
         .nio,
         .protobuf,
       ],
-      path: "Sources/Examples/HelloWorld/Model",
+      path: "Sources/Examples/v1/HelloWorld/Model",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -649,7 +649,7 @@ extension Target {
         .nioPosix,
         .argumentParser,
       ],
-      path: "Sources/Examples/HelloWorld/Client",
+      path: "Sources/Examples/v1/HelloWorld/Client",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -664,7 +664,7 @@ extension Target {
         .nioPosix,
         .argumentParser,
       ],
-      path: "Sources/Examples/HelloWorld/Server",
+      path: "Sources/Examples/v1/HelloWorld/Server",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -677,7 +677,7 @@ extension Target {
         .nio,
         .protobuf,
       ],
-      path: "Sources/Examples/RouteGuide/Model",
+      path: "Sources/Examples/v1/RouteGuide/Model",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -692,7 +692,7 @@ extension Target {
         .nioPosix,
         .argumentParser,
       ],
-      path: "Sources/Examples/RouteGuide/Client",
+      path: "Sources/Examples/v1/RouteGuide/Client",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -708,7 +708,7 @@ extension Target {
         .nioPosix,
         .argumentParser,
       ],
-      path: "Sources/Examples/RouteGuide/Server",
+      path: "Sources/Examples/v1/RouteGuide/Server",
       swiftSettings: [.swiftLanguageVersion(.v5)]
     )
   }
@@ -724,7 +724,7 @@ extension Target {
         .nioExtras,
         .argumentParser,
       ],
-      path: "Sources/Examples/PacketCapture",
+      path: "Sources/Examples/v1/PacketCapture",
       exclude: [
         "README.md",
       ],
@@ -758,7 +758,7 @@ extension Target {
         .echoModel,
         .echoImplementation
       ],
-      path: "Sources/Examples/ReflectionService",
+      path: "Sources/Examples/v1/ReflectionService",
       resources: [
         .copy("Generated")
       ],

Protos/generate.sh

@@ -72,17 +72,25 @@ function invoke_protoc {
 
 #------------------------------------------------------------------------------
 
-function generate_echo_example {
+function generate_echo_v1_example {
   local proto="$here/examples/echo/echo.proto"
-  local output="$root/Sources/Examples/Echo/Model"
+  local output="$root/Sources/Examples/v1/Echo/Model"
 
   generate_message "$proto" "$(dirname "$proto")" "$output" "Visibility=Public"
   generate_grpc "$proto" "$(dirname "$proto")" "$output" "Visibility=Public" "TestClient=true"
 }
 
+function generate_echo_v2_example {
+  local proto="$here/examples/echo/echo.proto"
+  local output="$root/Sources/Examples/v2/Echo/Generated"
+
+  generate_message "$proto" "$(dirname "$proto")" "$output" "Visibility=Internal"
+  generate_grpc "$proto" "$(dirname "$proto")" "$output" "Visibility=Internal" "_V2=true"
+}
+
 function generate_routeguide_example {
   local proto="$here/examples/route_guide/route_guide.proto"
-  local output="$root/Sources/Examples/RouteGuide/Model"
+  local output="$root/Sources/Examples/v1/RouteGuide/Model"
 
   generate_message "$proto" "$(dirname "$proto")" "$output" "Visibility=Public"
   generate_grpc "$proto" "$(dirname "$proto")" "$output" "Visibility=Public"
@@ -90,7 +98,7 @@ function generate_routeguide_example {
 
 function generate_helloworld_example {
   local proto="$here/upstream/grpc/examples/helloworld.proto"
-  local output="$root/Sources/Examples/HelloWorld/Model"
+  local output="$root/Sources/Examples/v1/HelloWorld/Model"
 
   generate_message "$proto" "$(dirname "$proto")" "$output" "Visibility=Public"
   generate_grpc "$proto" "$(dirname "$proto")" "$output" "Visibility=Public"
@@ -165,7 +173,7 @@ function generate_echo_reflection_data_for_tests {
 
 function generate_reflection_data_example {
   local protos=("$here/examples/echo/echo.proto" "$here/upstream/grpc/examples/helloworld.proto")
-  local output="$root/Sources/Examples/ReflectionService/Generated"
+  local output="$root/Sources/Examples/v1/ReflectionService/Generated"
 
   for proto in "${protos[@]}"; do
     generate_grpc "$proto" "$(dirname "$proto")" "$output" "Client=false" "Server=false" "ReflectionData=true"
@@ -243,7 +251,8 @@ function generate_health_service {
 #------------------------------------------------------------------------------
 
 # Examples
-generate_echo_example
+generate_echo_v1_example
+generate_echo_v2_example
 generate_routeguide_example
 generate_helloworld_example
 generate_reflection_data_example

Sources/GRPCPerformanceTests/Benchmarks/echo.grpc.swift

@@ -1 +1 @@
-../../Examples/Echo/Model/echo.grpc.swift
+../../Examples/v1/Echo/Model/echo.grpc.swift

Sources/GRPCPerformanceTests/Benchmarks/echo.pb.swift

@@ -1 +1 @@
-../../Examples/Echo/Model/echo.pb.swift
+../../Examples/v1/Echo/Model/echo.pb.swift

Sources/GRPCReflectionService/Documentation.docc/ReflectionServiceTutorial.md

@@ -4,7 +4,7 @@ This tutorial goes through the steps of adding Reflection service to a
 server, running it and testing it using gRPCurl.
 
  The server used in this example is implemented at
- [Sources/Examples/ReflectionService/ReflectionServer.swift][reflection-server]
+ [Sources/Examples/v1/ReflectionService/ReflectionServer.swift][reflection-server]
  and it supports the "Greeter", "Echo", and "Reflection" services.
 
 
@@ -38,27 +38,27 @@ describing the services of the server and the version of the reflection service.
 The server from this example uses the `GreeterProvider` and the `EchoProvider`,
 besides the `ReflectionService`.
 
-The associated proto files are located at `Sources/Examples/HelloWorld/Model/helloworld.proto`, and
-`Sources/Examples/Echo/Model/echo.proto` respectively.
+The associated proto files are located at `Sources/Examples/v1/HelloWorld/Model/helloworld.proto`, and
+`Sources/Examples/v1/Echo/Model/echo.proto` respectively.
 
 In order to generate the reflection data for the `helloworld.proto`, you can run the following command:
 
 ```sh
-$ protoc Sources/Examples/HelloWorld/Model/helloworld.proto \
-    --proto_path=Sources/Examples/HelloWorld/Model \
+$ protoc Sources/Examples/v1/HelloWorld/Model/helloworld.proto \
+    --proto_path=Sources/Examples/v1/HelloWorld/Model \
     --grpc-swift_opt=Client=false,Server=false,ReflectionData=true \
-    --grpc-swift_out=Sources/Examples/ReflectionService/Generated
+    --grpc-swift_out=Sources/Examples/v1/ReflectionService/Generated
 ```
 
 Let's break the command down:
 - The first argument passed to `protoc` is the path
   to the `.proto` file to generate reflection data
-  for: [`Sources/Examples/HelloWorld/Model/helloworld.proto`][helloworld-proto].
-- The `proto_path` flag is the path to search for imports: `Sources/Examples/HelloWorld/Model`.
+  for: [`Sources/Examples/v1/HelloWorld/Model/helloworld.proto`][helloworld-proto].
+- The `proto_path` flag is the path to search for imports: `Sources/Examples/v1/HelloWorld/Model`.
 - The 'grpc-swift_opt' flag allows us to list options for the Swift generator.
   To generate only the reflection data set: `Client=false,Server=false,ReflectionData=true`.
 - The `grpc-swift_out` flag is used to set the path of the directory
-  where the generated file will be located: `Sources/Examples/ReflectionService/Generated`.
+  where the generated file will be located: `Sources/Examples/v1/ReflectionService/Generated`.
 
 This command assumes that the `protoc-gen-grpc-swift` plugin is in your `$PATH` environment variable.
 You can learn how to get the plugin from this section of the `grpc-swift` README:
@@ -219,9 +219,9 @@ Note that when specifying a service, a method or a symbol, we have to use the fu
 [grpc-cli]: https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md
 [v1]: ../v1/reflection-v1.proto
 [v1alpha]: ../v1Alpha/reflection-v1alpha.proto
-[reflection-server]: ../../Examples/ReflectionService/ReflectionServer.swift
-[helloworld-proto]: ../../Examples/HelloWorld/Model/helloworld.proto
-[echo-proto]: ../../Examples/Echo/Model/echo.proto
+[reflection-server]: ../../Examples/v1/ReflectionService/ReflectionServer.swift
+[helloworld-proto]: ../../Examples/v1/HelloWorld/Model/helloworld.proto
+[echo-proto]: ../../Examples/v1/Echo/Model/echo.proto
 [grpcurl-v188]: https://github.com/fullstorydev/grpcurl/releases/tag/v1.8.8
 [swiftpm-resources]: https://github.com/apple/swift-package-manager/blob/main/Documentation/PackageDescription.md#resource
-[spm-plugin]: ../../protoc-gen-grpc-swift/Docs.docc/spm-plugin.md
+[spm-plugin]: ../../protoc-gen-grpc-swift/Docs.docc/spm-plugin.md

docs/basic-tutorial.md

@@ -34,7 +34,7 @@ updating.
 ### Example code and setup
 
 The example code for our tutorial is in
-[grpc/grpc-swift/Sources/Examples/RouteGuide][routeguide-source].
+[grpc/grpc-swift/Sources/Examples/v1/RouteGuide][routeguide-source].
 To download the example, clone the latest release in `grpc-swift` repository by
 running the following command (replacing `x.y.z` with the latest release, for
 example `1.7.0`):
@@ -43,10 +43,10 @@ example `1.7.0`):
 $ git clone -b x.y.z https://github.com/grpc/grpc-swift
 ```
 
-Then change your current directory to `grpc-swift/Sources/Examples/RouteGuide`:
+Then change your current directory to `grpc-swift/Sources/Examples/v1/RouteGuide`:
 
 ```sh
-$ cd grpc-swift/Sources/Examples/RouteGuide
+$ cd grpc-swift/Sources/Examples/v1/RouteGuide
 ```
 
 
@@ -151,7 +151,7 @@ $ Protos/generate.sh
 ```
 
 Running this command generates the following files in the
-`Sources/Examples/RouteGuide/Model` directory:
+`Sources/Examples/v1/RouteGuide/Model` directory:
 
 - `route_guide.pb.swift`, which contains the implementation of your generated
     message classes
@@ -165,10 +165,10 @@ $ protoc Protos/examples/route_guide/route_guide.proto \
     --proto_path=Protos/examples/route_guide \
     --plugin=./.build/debug/protoc-gen-swift \
     --swift_opt=Visibility=Public \
-    --swift_out=Sources/Examples/RouteGuide/Model \
+    --swift_out=Sources/Examples/v1/RouteGuide/Model \
     --plugin=./.build/debug/protoc-gen-grpc-swift \
     --grpc-swift_opt=Visibility=Public \
-    --grpc-swift_out=Sources/Examples/RouteGuide/Model
+    --grpc-swift_out=Sources/Examples/v1/RouteGuide/Model
 ```
 
 We invoke the protocol buffer compiler `protoc` with the path to our service
@@ -197,7 +197,7 @@ There are two parts to making our `RouteGuide` service do its job:
   service responses.
 
 You can find our example `RouteGuide` provider in
-[grpc-swift/Sources/Examples/RouteGuide/Server/RouteGuideProvider.swift][routeguide-provider].
+[grpc-swift/Sources/Examples/v1/RouteGuide/Server/RouteGuideProvider.swift][routeguide-provider].
 Let's take a closer look at how it works.
 
 #### Implementing RouteGuide
@@ -455,7 +455,7 @@ program from exiting (since `close()` is never called on the server).
 
 In this section, we'll look at creating a Swift client for our `RouteGuide`
 service. You can see our complete example client code in
-[grpc-swift/Sources/Examples/RouteGuide/Client/RouteGuideClient.swift][routeguide-client].
+[grpc-swift/Sources/Examples/v1/RouteGuide/Client/RouteGuideClient.swift][routeguide-client].
 
 #### Creating a stub
 
@@ -604,11 +604,11 @@ Follow the instructions in the Route Guide example directory
 [protobuf-docs]: https://developers.google.com/protocol-buffers/docs/proto3
 [protobuf-releases]: https://github.com/google/protobuf/releases
 [protocol-buffers]: https://developers.google.com/protocol-buffers/docs/overview
-[routeguide-client]: ../Sources/Examples/RouteGuide/Client/RouteGuideClient.swift
+[routeguide-client]: ../Sources/Examples/v1/RouteGuide/Client/RouteGuideClient.swift
 [routeguide-proto]: ../Protos/examples/route_guide/route_guide.proto
-[routeguide-provider]: ../Sources/Examples/RouteGuide/Server/RouteGuideProvider.swift
-[routeguide-readme]: ../Sources/Examples/RouteGuide/README.md
-[routeguide-source]: ../Sources/Examples/RouteGuide
+[routeguide-provider]: ../Sources/Examples/v1/RouteGuide/Server/RouteGuideProvider.swift
+[routeguide-readme]: ../Sources/Examples/v1/RouteGuide/README.md
+[routeguide-source]: ../Sources/Examples/v1/RouteGuide
 [run-protoc]: ../Protos/generate.sh
 [swift-protobuf-guide]: https://github.com/apple/swift-protobuf/blob/main/Documentation/API.md
 [swift-protobuf]: https://github.com/apple/swift-protobuf

docs/client-without-codegen.md

@@ -27,4 +27,4 @@ using `makeClientStreamingCall`, `makeServerStreamingCall`, and
 These methods are also available on generated clients, allowing you to call
 methods which have been added to the service since the client was generated.
 
-[helloworld-source]: ../Sources/Examples/HelloWorld
+[helloworld-source]: ../Sources/Examples/v1/HelloWorld

docs/interceptors-tutorial.md

@@ -293,4 +293,4 @@ by invoking methods on the `context` from that `EventLoop`.
 
 [quick-start]: ./quick-start.md
 [basic-tutorial]: ./basic-tutorial.md
-[echo-example]: ../Sources/Examples/Echo
+[echo-example]: ../Sources/Examples/v1/Echo

docs/quick-start.md

@@ -109,7 +109,7 @@ message HelloReply {
 ### Update and run the application
 
 We need to regenerate
-`Sources/Examples/HelloWorld/Model/helloworld.grpc.swift`, which
+`Sources/Examples/v1/HelloWorld/Model/helloworld.grpc.swift`, which
 contains our generated gRPC client and server classes.
 
 From the `grpc-swift` directory run
@@ -127,7 +127,7 @@ parts of our example application.
 #### Update the server
 
 In the same directory, open
-`Sources/Examples/HelloWorld/Server/GreeterProvider.swift`. Implement the new
+`Sources/Examples/v1/HelloWorld/Server/GreeterProvider.swift`. Implement the new
 method like this:
 
 ```swift
@@ -159,7 +159,7 @@ final class GreeterProvider: Helloworld_GreeterAsyncProvider {
 #### Update the client
 
 In the same directory, open
-`Sources/Examples/HelloWorld/Client/HelloWorldClient.swift`. Call the new method like this:
+`Sources/Examples/v1/HelloWorld/Client/HelloWorldClient.swift`. Call the new method like this:
 
 ```swift
 func run() async throws {