From 2906a98d02a12abb6d5dd1c7ef5db60003973265 Mon Sep 17 00:00:00 2001 From: Marco Ferrer <35935108+marcoferrer@users.noreply.github.com> Date: Mon, 3 Dec 2018 12:52:50 -0500 Subject: [PATCH 1/6] start 0.2.2 dev cycle --- CHANGELOG.md | 3 +++ build.gradle | 2 +- community-scripts/extendable-messages/build.gradle | 2 +- community-scripts/var-arg-extensions/build.gradle | 2 +- example-project/build.gradle | 3 ++- 5 files changed, 8 insertions(+), 4 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c9dacd..cd45b6a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,6 @@ +## Version 0.2.2 +_2018-12-3_ + ## Version 0.2.1 _2018-11-02_ * Fix: Address regression in file filter matching diff --git a/build.gradle b/build.gradle index a39608a..e50cb27 100644 --- a/build.gradle +++ b/build.gradle @@ -44,7 +44,7 @@ subprojects{ subproject -> apply plugin: 'kotlin' group = 'com.github.marcoferrer.krotoplus' - version = '0.2.1' + version = '0.2.2-SNAPSHOT' compileKotlin { kotlinOptions.jvmTarget = "1.8" diff --git a/community-scripts/extendable-messages/build.gradle b/community-scripts/extendable-messages/build.gradle index 8947369..9322451 100644 --- a/community-scripts/extendable-messages/build.gradle +++ b/community-scripts/extendable-messages/build.gradle @@ -1,4 +1,4 @@ -def krotoPlusVersion = '0.2.1' +def krotoPlusVersion = '0.2.2-SNAPSHOT' plugins { id "org.jetbrains.kotlin.jvm" version "1.3.0" diff --git a/community-scripts/var-arg-extensions/build.gradle b/community-scripts/var-arg-extensions/build.gradle index 0298b22..46809d8 100644 --- a/community-scripts/var-arg-extensions/build.gradle +++ b/community-scripts/var-arg-extensions/build.gradle @@ -1,4 +1,4 @@ -def krotoPlusVersion = '0.2.1' +def krotoPlusVersion = '0.2.2.-SNAPSHOT' plugins { id "org.jetbrains.kotlin.jvm" version "1.3.0" diff --git a/example-project/build.gradle b/example-project/build.gradle index 9158f29..8cec9d3 100644 --- a/example-project/build.gradle +++ b/example-project/build.gradle @@ -5,7 +5,7 @@ buildscript { "grpc": '1.15.1', "kotlin": '1.3.0', "coroutines": '1.0.0', - "krotoplus": '0.2.1' + "krotoplus": '0.2.2-SNAPSHOT' ] } @@ -44,6 +44,7 @@ allprojects { repositories { jcenter() maven { url 'http://dl.bintray.com/kotlin/kotlin-eap' } + maven { url "https://kotlin.bintray.com/kotlinx" } if(versions.krotoplus.endsWith("SNAPSHOT")) { flatDir dirs: "${rootDir}/../kroto-plus-message/build/libs/" flatDir dirs: "${rootDir}/../kroto-plus-coroutines/build/libs/" From af21d5b44194e296aabf9b618839ce24a387379b Mon Sep 17 00:00:00 2001 From: Marco Ferrer <35935108+marcoferrer@users.noreply.github.com> Date: Sat, 8 Dec 2018 16:56:44 -0500 Subject: [PATCH 2/6] remove debug statement in sendChannel builder --- .../marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt | 2 -- 1 file changed, 2 deletions(-) diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt index 3341259..bdad772 100644 --- a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt @@ -51,10 +51,8 @@ fun StreamObserver.toSendChannel(parent: Job? = null): SendChannel { try { channel.consumeEach { streamObserver.onNext(it) } streamObserver.onCompleted() - println("completed") } catch (e: Throwable) { streamObserver.onError(e) - println("error: ${e.message} ") } } } From 34956ca92214ee948c1ddc5529893356fe5bbd88 Mon Sep 17 00:00:00 2001 From: Marco Ferrer <35935108+marcoferrer@users.noreply.github.com> Date: Tue, 18 Dec 2018 00:00:46 -0500 Subject: [PATCH 3/6] generate dsl marker insertions for nested messages (#11) --- .../generators/ProtoBuildersGenerator.kt | 34 ++++++++++++++----- 1 file changed, 26 insertions(+), 8 deletions(-) diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/ProtoBuildersGenerator.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/ProtoBuildersGenerator.kt index 536a196..8db1e75 100644 --- a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/ProtoBuildersGenerator.kt +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/ProtoBuildersGenerator.kt @@ -20,6 +20,8 @@ object ProtoBuildersGenerator : Generator { override fun invoke(): PluginProtos.CodeGeneratorResponse { val responseBuilder = PluginProtos.CodeGeneratorResponse.newBuilder() + + // Build Exts & DSL Marker context.schema.protoFiles.asSequence() .filter { it.protoMessages.isNotEmpty() } .forEach { protoFile -> @@ -28,6 +30,18 @@ object ProtoBuildersGenerator : Generator { buildFileSpec(protoFile, options, responseBuilder) } } + + // Build DSL Insertions + context.schema.protoTypes.asSequence() + .filterIsInstance() + .filterNot { it.isMapEntry } + .forEach { protoMessage -> + for (options in context.config.protoBuildersList) { + if (options.filter.matches(protoMessage.protoFile.name)) + responseBuilder.addFile(protoMessage.buildDslInsertion()) + } + } + return responseBuilder.build() } @@ -61,7 +75,6 @@ object ProtoBuildersGenerator : Generator { if (options.useDslMarkers) { fileSpecBuilder.buildDslMarkerInterface(protoFile) - responseBuilder.addFiles(protoFile.buildDslInterfaceInsertions()) } fileSpecBuilder.build().takeIf { it.members.isNotEmpty() }?.let { @@ -81,6 +94,7 @@ object ProtoBuildersGenerator : Generator { returnType = UNIT ) + // Builder Spec FunSpec.builder(protoType.name) .addModifiers(KModifier.INLINE) .addParameter("block", builderLambdaTypeName) @@ -93,6 +107,7 @@ object ProtoBuildersGenerator : Generator { this.addFunction(it.build()) } + // Copy Spec FunSpec.builder("copy") .receiver(protoType.className) .addModifiers(KModifier.INLINE) @@ -103,6 +118,7 @@ object ProtoBuildersGenerator : Generator { fileSpecBuilder.addFunction(it.build()) } + // Plus Operator Spec FunSpec.builder("plus") .receiver(protoType.className) .addModifiers(KModifier.OPERATOR) @@ -113,6 +129,15 @@ object ProtoBuildersGenerator : Generator { fileSpecBuilder.addFunction(it.build()) } + // Or Default Spec + FunSpec.builder("orDefault") + .receiver(protoType.className.asNullable()) + .returns(protoType.className) + .addStatement("return this ?: %T.getDefaultInstance()", protoType.className) + .also { + fileSpecBuilder.addFunction(it.build()) + } + fileSpecBuilder.addFunctions(buildNestedBuildersForMessage(protoType)) if (protoType.nestedMessageTypes.isNotEmpty()) { @@ -186,13 +211,6 @@ object ProtoBuildersGenerator : Generator { .also { this@buildDslMarkerInterface.addType(it) } } - private fun ProtoFile.buildDslInterfaceInsertions(): List = - protoMessages - .asSequence() - .filter { !it.isMapEntry } - .map { it.buildDslInsertion() } - .toList() - private fun ProtoMessage.buildDslInsertion() = PluginProtos.CodeGeneratorResponse.File.newBuilder() .apply { From 679e0b841d913e3efdc154cc106d2e98c21b6439 Mon Sep 17 00:00:00 2001 From: Marco Ferrer <35935108+marcoferrer@users.noreply.github.com> Date: Tue, 18 Dec 2018 00:01:09 -0500 Subject: [PATCH 4/6] add script for generating grpc-gateway entry point (#12) --- .../grpc-gateway-entry-point/README.md | 49 +++++++++ .../grpc-gateway-entry-point/build.gradle | 16 +++ .../src/main/kotlin/grpcGatewayEntryPoint.kts | 103 ++++++++++++++++++ 3 files changed, 168 insertions(+) create mode 100644 community-scripts/grpc-gateway-entry-point/README.md create mode 100644 community-scripts/grpc-gateway-entry-point/build.gradle create mode 100644 community-scripts/grpc-gateway-entry-point/src/main/kotlin/grpcGatewayEntryPoint.kts diff --git a/community-scripts/grpc-gateway-entry-point/README.md b/community-scripts/grpc-gateway-entry-point/README.md new file mode 100644 index 0000000..e6b3ae5 --- /dev/null +++ b/community-scripts/grpc-gateway-entry-point/README.md @@ -0,0 +1,49 @@ +## Grpc Gateway - Entry Point + +Kotlin script for generating an entry point for a [grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway) + +The code generated is based off the example given in the project readme. + +```go +package main + +import ( + "flag" + "net/http" + + "github.com/golang/glog" + "golang.org/x/net/context" + "github.com/grpc-ecosystem/grpc-gateway/runtime" + "google.golang.org/grpc" + + gw "path/to/your_service_package" +) + +var ( + echoEndpoint = flag.String("echo_endpoint", "localhost:9090", "endpoint of YourService") +) + +func run() error { + ctx := context.Background() + ctx, cancel := context.WithCancel(ctx) + defer cancel() + + mux := runtime.NewServeMux() + opts := []grpc.DialOption{grpc.WithInsecure()} + err := gw.RegisterYourServiceHandlerFromEndpoint(ctx, mux, *echoEndpoint, opts) + if err != nil { + return err + } + + return http.ListenAndServe(":8080", mux) +} + +func main() { + flag.Parse() + defer glog.Flush() + + if err := run(); err != nil { + glog.Fatal(err) + } +} +``` \ No newline at end of file diff --git a/community-scripts/grpc-gateway-entry-point/build.gradle b/community-scripts/grpc-gateway-entry-point/build.gradle new file mode 100644 index 0000000..9322451 --- /dev/null +++ b/community-scripts/grpc-gateway-entry-point/build.gradle @@ -0,0 +1,16 @@ +def krotoPlusVersion = '0.2.2-SNAPSHOT' + +plugins { + id "org.jetbrains.kotlin.jvm" version "1.3.0" +} + +repositories { + jcenter() + maven { url 'https://oss.jfrog.org/artifactory/oss-snapshot-local' } +} + +dependencies{ + implementation "com.github.marcoferrer.krotoplus:protoc-gen-kroto-plus:$krotoPlusVersion" + implementation "com.google.protobuf:protobuf-java:3.6.1" + implementation "org.jetbrains.kotlin:kotlin-script-util" +} \ No newline at end of file diff --git a/community-scripts/grpc-gateway-entry-point/src/main/kotlin/grpcGatewayEntryPoint.kts b/community-scripts/grpc-gateway-entry-point/src/main/kotlin/grpcGatewayEntryPoint.kts new file mode 100644 index 0000000..e0a136f --- /dev/null +++ b/community-scripts/grpc-gateway-entry-point/src/main/kotlin/grpcGatewayEntryPoint.kts @@ -0,0 +1,103 @@ +import com.github.marcoferrer.krotoplus.generators.Generator +import com.github.marcoferrer.krotoplus.proto.ProtoService +import com.github.marcoferrer.krotoplus.utils.addFile +import com.google.protobuf.compiler.PluginProtos + + +object GrpcGatewayEntryPointGenerator : Generator { + + private const val httpOptionId = "72295728" + + override fun invoke(): PluginProtos.CodeGeneratorResponse { + + val services = context.schema.protoServices + .filter { service -> + service.methodDefinitions.any { method -> + httpOptionId in method.descriptorProto.options.toString() + } + } + + return PluginProtos.CodeGeneratorResponse.newBuilder() + .addFile { + name = "main.go" + content = buildMain(services) + } + .build() + } + + // language=go + private fun buildMain(services: List) = buildString { + append( + """ + package main + + import ( + "flag" + "net/http" + + "github.com/golang/glog" + "github.com/grpc-ecosystem/grpc-gateway/runtime" + "golang.org/x/net/context" + "google.golang.org/grpc" + """.trimIndent() + ) + + for (service in services) { + val goPackage = service.protoFile.protoPackage.replace(".", "/") + + appendln() + append(" ${service.varName} \"../$goPackage\"") + } + + appendln() + append( + """ + ) + + var ( + serviceEndpoint = flag.String("service_endpoint", "localhost:8000", "endpoint of YourService") + ) + + func run() error { + ctx := context.Background() + ctx, cancel := context.WithCancel(ctx) + defer cancel() + + mux := runtime.NewServeMux() + opts := []grpc.DialOption{grpc.WithInsecure()} + var err error + """.trimIndent() + ) + + for (service in services) { + appendln() + appendln( + """ + err = ${service.varName}.Register${service.name}HandlerFromEndpoint(ctx, mux, *serviceEndpoint, opts) + if err != nil { + return err + } + """.trimIndent() + ) + } + + append( + """ + return http.ListenAndServe(":8080", mux) + } + + func main() { + flag.Parse() + defer glog.Flush() + + if err := run(); err != nil { + glog.Fatal(err) + } + } + """.trimIndent() + ) + } + + val ProtoService.varName: String get() = name.decapitalize() + "Gw" +} + From 06e0189657ec01f4f4c59a2eb0e461b92386fec2 Mon Sep 17 00:00:00 2001 From: Marco Ferrer <35935108+marcoferrer@users.noreply.github.com> Date: Thu, 3 Jan 2019 22:14:57 -0500 Subject: [PATCH 5/6] gRPC Client and Service code gen (#16) --- CHANGELOG.md | 16 +- build.gradle | 11 +- buildSrc/src/main/kotlin/Versions.kt | 4 +- docs/html/kroto-plus-config.html | 3950 ++++++++++++++++- docs/markdown/kroto-plus-config.md | 2176 ++++++++- example-grpc-client-server/README.md | 119 + example-project/build.gradle | 11 +- example-project/krotoPlusConfig.asciipb | 3 + .../kotlin/krotoplus/example/DummyServices.kt | 94 +- .../main/kotlin/krotoplus/example/Entities.kt | 5 + .../kotlin/krotoplus/example/StandService.kt | 60 + .../krotoplus/example/TestSomeRandomClass.kt | 2 +- .../krotoplus/example/TestStandService.kt | 86 + gradle.properties | 1 + kroto-plus-coroutines/benchmark/README.md | 1 + kroto-plus-coroutines/benchmark/build.gradle | 55 + .../benchmark/krotoPlusConfig.asciipb | 3 + .../src/main/kotlin/BenchMarkService.kt | 88 + .../benchmark/src/main/kotlin/main.kt | 36 + kroto-plus-coroutines/build.gradle | 26 +- .../krotoplus/coroutines/Annotations.kt | 5 +- .../krotoplus/coroutines/CallChannelExts.kt | 110 + .../coroutines/CompletableDeferredResponse.kt | 59 + .../krotoplus/coroutines/CoroutineStub.kt | 20 + .../krotoplus/coroutines/FlowControl.kt | 57 + .../krotoplus/coroutines/GrpcDispatcher.kt | 52 + .../coroutines/InboundStreamChannel.kt | 10 +- .../krotoplus/coroutines/RpcBidiChannel.kt | 15 +- .../coroutines/ServiceStubRpcBuilders.kt | 52 +- .../coroutines/client/ClientCalls.kt | 77 + .../coroutines/client/ClientChannels.kt | 64 + .../coroutines/server/ResponseExts.kt | 33 + .../coroutines/server/ServerCalls.kt | 127 + .../coroutines/server/ServerChannels.kt | 41 + .../coroutines/CallChannelExtsTest.kt | 73 + .../CompletableDeferredResponseTest.kt | 2 + .../EnableManualFlowControlTests.kt | 156 + .../coroutines/FlowControlledObserverTests.kt | 91 + .../coroutines/SuspendingUnaryObserverTest.kt | 2 + .../ClientResponseObserverChannelTest.kt | 2 + .../server/ServerRequestStreamChannelTest.kt | 2 + kroto-plus-test/build.gradle | 4 +- protoc-gen-grpc-coroutines/build.gradle | 57 + .../krotoplus/GrpcCoroutinesMain.kt | 21 + protoc-gen-kroto-plus/build.gradle | 10 +- .../krotoplus/config/CompilerConfig.java | 435 ++ .../config/CompilerConfigOrBuilder.java | 44 + .../marcoferrer/krotoplus/config/Config.java | 92 +- .../config/GrpcCoroutinesGenOptions.java | 663 +++ .../GrpcCoroutinesGenOptionsOrBuilder.java | 37 + .../krotoplus/KrotoPlusProtoCMain.kt | 1 + .../krotoplus/generators/Generator.kt | 11 +- .../generators/GrpcCoroutinesGenerator.kt | 687 +++ .../generators/GrpcStubExtsGenerator.kt | 5 +- .../krotoplus/proto/ProtoMethod.kt | 14 + .../krotoplus/utils/CommonNames.kt | 61 + .../marcoferrer/krotoplus/utils/Memoize.kt | 12 +- .../proto/krotoplus/compiler/config.proto | 11 + settings.gradle | 2 + 59 files changed, 9740 insertions(+), 224 deletions(-) create mode 100644 example-grpc-client-server/README.md create mode 100644 example-project/src/main/kotlin/krotoplus/example/StandService.kt create mode 100644 example-project/src/test/kotlin/krotoplus/example/TestStandService.kt create mode 100644 kroto-plus-coroutines/benchmark/README.md create mode 100644 kroto-plus-coroutines/benchmark/build.gradle create mode 100644 kroto-plus-coroutines/benchmark/krotoPlusConfig.asciipb create mode 100644 kroto-plus-coroutines/benchmark/src/main/kotlin/BenchMarkService.kt create mode 100644 kroto-plus-coroutines/benchmark/src/main/kotlin/main.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExts.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponse.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CoroutineStub.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControl.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/GrpcDispatcher.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientCalls.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientChannels.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ResponseExts.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerCalls.kt create mode 100644 kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerChannels.kt create mode 100644 kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExtsTest.kt create mode 100644 kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponseTest.kt create mode 100644 kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/EnableManualFlowControlTests.kt create mode 100644 kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControlledObserverTests.kt create mode 100644 kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/SuspendingUnaryObserverTest.kt create mode 100644 kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientResponseObserverChannelTest.kt create mode 100644 kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerRequestStreamChannelTest.kt create mode 100644 protoc-gen-grpc-coroutines/build.gradle create mode 100644 protoc-gen-grpc-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/GrpcCoroutinesMain.kt create mode 100644 protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptions.java create mode 100644 protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptionsOrBuilder.java create mode 100644 protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcCoroutinesGenerator.kt create mode 100644 protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/CommonNames.kt diff --git a/CHANGELOG.md b/CHANGELOG.md index cd45b6a..622675f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,17 @@ -## Version 0.2.2 -_2018-12-3_ +## Version 0.2.2-RC1 +_2018-01-03_ +* New: Update to kotlin ```1.3.11``` + +#### Protoc Plugin +* New: gRPC Coroutines Client & Server Code Generation +* New: Stand alone version of gRPC code gen. ```protoc-gen-grpc-coroutines``` + +#### Coroutines +* New: Benchmark implementation of gRPC coroutines +* New: Experimental global dispatcher ```Dispatchers.Grpc``` +* New: ```SendChannel``` utility api ```CoroutineScope.launchProducerJob``` +* Deprecated: ```InboundStreamChannel``` in favor of new stub APIs +* Deprecated: ```ServerBidiCallChannel``` in favor of new stub APIs ## Version 0.2.1 _2018-11-02_ diff --git a/build.gradle b/build.gradle index e50cb27..27459da 100644 --- a/build.gradle +++ b/build.gradle @@ -3,7 +3,7 @@ buildscript { versions = [ "protobuf": '3.6.1', "grpc": '1.15.1', - "kotlin": '1.3.0', + "kotlin": '1.3.11', "coroutines": '1.0.0', "bintray": '1.7.3', 'artifactory':'4.7.1', @@ -23,12 +23,13 @@ buildscript { } plugins{ - id 'com.google.protobuf' version '0.8.6' apply false - id 'org.jetbrains.kotlin.jvm' version '1.3.0-rc-116' apply false + id 'com.google.protobuf' version '0.8.7' apply false + id 'org.jetbrains.kotlin.jvm' version '1.3.11' apply false id "com.jfrog.bintray" version "1.8.4" apply false id "com.jfrog.artifactory" version "4.8.1" apply false id "org.springframework.boot" version "2.0.3.RELEASE" apply false id 'com.gradle.plugin-publish' version '0.9.7' apply false + id "com.google.osdetector" version "1.4.0" } subprojects{ subproject -> @@ -44,7 +45,7 @@ subprojects{ subproject -> apply plugin: 'kotlin' group = 'com.github.marcoferrer.krotoplus' - version = '0.2.2-SNAPSHOT' + version = '0.2.2-RC1' compileKotlin { kotlinOptions.jvmTarget = "1.8" @@ -55,7 +56,7 @@ subprojects{ subproject -> } dependencies { - implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8" + implementation "org.jetbrains.kotlin:kotlin-stdlib" testImplementation group: 'junit', name: 'junit', version: '[4,)' testImplementation "org.jetbrains.kotlin:kotlin-test" diff --git a/buildSrc/src/main/kotlin/Versions.kt b/buildSrc/src/main/kotlin/Versions.kt index ddf55ca..af1d445 100644 --- a/buildSrc/src/main/kotlin/Versions.kt +++ b/buildSrc/src/main/kotlin/Versions.kt @@ -1,6 +1,6 @@ object Versions { const val protobuf = "3.6.1" const val grpc = "1.15.1" - const val kotlin = "1.3.0" - const val coroutines = "1.0.0" + const val kotlin = "1.3.11" + const val coroutines = "1.1.0" } \ No newline at end of file diff --git a/docs/html/kroto-plus-config.html b/docs/html/kroto-plus-config.html index 7880f4a..688aa1f 100644 --- a/docs/html/kroto-plus-config.html +++ b/docs/html/kroto-plus-config.html @@ -175,59 +175,3896 @@

Table of Contents

  • - krotoplus/compiler/config.proto + google/protobuf/any.proto +
      + +
    • + MAny +
      • + + + + +
    +
    • + + +
  • + google/protobuf/api.proto + +
    • + + +
  • + google/protobuf/compiler/plugin.proto + +
    • + + +
  • + google/protobuf/descriptor.proto + +
    • + + +
  • + google/protobuf/duration.proto + +
    • + + +
  • + google/protobuf/empty.proto + +
    • + + +
  • + google/protobuf/field_mask.proto + +
    • + + +
  • + google/protobuf/source_context.proto + +
    • + + +
  • + google/protobuf/struct.proto + +
    • + + +
  • + google/protobuf/timestamp.proto + +
    • + + +
  • + google/protobuf/type.proto +
    • + + +
  • + google/protobuf/wrappers.proto + +
    • + + +
  • + krotoplus/compiler/config.proto + +
    • + +
  • Scalar Value Types
    • + + + + + +
    +

    google/protobuf/any.proto

    Top +
    +

    + + +

    Any

    +

    `Any` contains an arbitrary serialized protocol buffer message along with a

    URL that describes the type of the serialized message.

    Protobuf library provides support to pack/unpack Any values in the form

    of utility functions or additional generated methods of the Any type.

    Example 1: Pack and unpack a message in C++.

    Foo foo = ...;

    Any any;

    any.PackFrom(foo);

    ...

    if (any.UnpackTo(&foo)) {

    ...

    }

    Example 2: Pack and unpack a message in Java.

    Foo foo = ...;

    Any any = Any.pack(foo);

    ...

    if (any.is(Foo.class)) {

    foo = any.unpack(Foo.class);

    }

    Example 3: Pack and unpack a message in Python.

    foo = Foo(...)

    any = Any()

    any.Pack(foo)

    ...

    if any.Is(Foo.DESCRIPTOR):

    any.Unpack(foo)

    ...

    Example 4: Pack and unpack a message in Go

    foo := &pb.Foo{...}

    any, err := ptypes.MarshalAny(foo)

    ...

    foo := &pb.Foo{}

    if err := ptypes.UnmarshalAny(any, foo); err != nil {

    ...

    }

    The pack methods provided by protobuf library will by default use

    'type.googleapis.com/full.type.name' as the type URL and the unpack

    methods only use the fully qualified type name after the last '/'

    in the type URL, for example "foo.bar.com/x/y.z" will yield type

    name "y.z".

    JSON

    ====

    The JSON representation of an `Any` value uses the regular

    representation of the deserialized, embedded message, with an

    additional field `@type` which contains the type URL. Example:

    package google.profile;

    message Person {

    string first_name = 1;

    string last_name = 2;

    }

    {

    "@type": "type.googleapis.com/google.profile.Person",

    "firstName": ,

    "lastName":

    }

    If the embedded message type is well-known and has a custom JSON

    representation, that representation will be embedded adding a field

    `value` which holds the custom JSON in addition to the `@type`

    field. Example (for message [google.protobuf.Duration][]):

    {

    "@type": "type.googleapis.com/google.protobuf.Duration",

    "value": "1.212s"

    }

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    type_urlstring

    A URL/resource name that uniquely identifies the type of the serialized +protocol buffer message. The last segment of the URL's path must represent +the fully qualified name of the type (as in +`path/google.protobuf.Duration`). The name should be in a canonical form +(e.g., leading "." is not accepted). + +In practice, teams usually precompile into the binary all types that they +expect it to use in the context of Any. However, for URLs which use the +scheme `http`, `https`, or no scheme, one can optionally set up a type +server that maps type URLs to message definitions as follows: + +* If no scheme is provided, `https` is assumed. +* An HTTP GET on the URL must yield a [google.protobuf.Type][] + value in binary format, or produce an error. +* Applications are allowed to cache lookup results based on the + URL, or have them precompiled into a binary to avoid any + lookup. Therefore, binary compatibility needs to be preserved + on changes to types. (Use versioned type names to manage + breaking changes.) + +Note: this functionality is not currently available in the official +protobuf release, and it is not used for type URLs beginning with +type.googleapis.com. + +Schemes other than `http`, `https` (or the empty scheme) might be +used with implementation specific semantics.

    valuebytes

    Must be a valid serialized protocol buffer of the above specified type.

    + + + + + + + + + + + + +
    +

    google/protobuf/api.proto

    Top +
    +

    + + +

    Api

    +

    Api is a light-weight descriptor for an API Interface.

    Interfaces are also described as "protocol buffer services" in some contexts,

    such as by the "service" keyword in a .proto file, but they are different

    from API Services, which represent a concrete implementation of an interface

    as opposed to simply a description of methods and bindings. They are also

    sometimes simply referred to as "APIs" in other contexts, such as the name of

    this message itself. See https://cloud.google.com/apis/design/glossary for

    detailed terminology.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestring

    The fully qualified name of this interface, including package name +followed by the interface's simple name.

    methodsMethodrepeated

    The methods of this interface, in unspecified order.

    optionsOptionrepeated

    Any metadata attached to the interface.

    versionstring

    A version string for this interface. If specified, must have the form +`major-version.minor-version`, as in `1.10`. If the minor version is +omitted, it defaults to zero. If the entire version field is empty, the +major version is derived from the package name, as outlined below. If the +field is not empty, the version in the package name will be verified to be +consistent with what is provided here. + +The versioning schema uses [semantic +versioning](http://semver.org) where the major version number +indicates a breaking change and the minor version an additive, +non-breaking change. Both version numbers are signals to users +what to expect from different versions, and should be carefully +chosen based on the product plan. + +The major version is also reflected in the package name of the +interface, which must end in `v<major-version>`, as in +`google.feature.v1`. For major versions 0 and 1, the suffix can +be omitted. Zero major versions must only be used for +experimental, non-GA interfaces.

    source_contextSourceContext

    Source context for the protocol buffer service represented by this +message.

    mixinsMixinrepeated

    Included interfaces. See [Mixin][].

    syntaxSyntax

    The source syntax of the service.

    + + + + +

    Method

    +

    Method represents a method of an API interface.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestring

    The simple name of this method.

    request_type_urlstring

    A URL of the input message type.

    request_streamingbool

    If true, the request is streamed.

    response_type_urlstring

    The URL of the output message type.

    response_streamingbool

    If true, the response is streamed.

    optionsOptionrepeated

    Any metadata attached to the method.

    syntaxSyntax

    The source syntax of this method.

    + + + + +

    Mixin

    +

    Declares an API Interface to be included in this interface. The including

    interface must redeclare all the methods from the included interface, but

    documentation and options are inherited as follows:

    - If after comment and whitespace stripping, the documentation

    string of the redeclared method is empty, it will be inherited

    from the original method.

    - Each annotation belonging to the service config (http,

    visibility) which is not set in the redeclared method will be

    inherited.

    - If an http annotation is inherited, the path pattern will be

    modified as follows. Any version prefix will be replaced by the

    version of the including interface plus the [root][] path if

    specified.

    Example of a simple mixin:

    package google.acl.v1;

    service AccessControl {

    // Get the underlying ACL object.

    rpc GetAcl(GetAclRequest) returns (Acl) {

    option (google.api.http).get = "/v1/{resource=**}:getAcl";

    }

    }

    package google.storage.v2;

    service Storage {

    rpc GetAcl(GetAclRequest) returns (Acl);

    // Get a data record.

    rpc GetData(GetDataRequest) returns (Data) {

    option (google.api.http).get = "/v2/{resource=**}";

    }

    }

    Example of a mixin configuration:

    apis:

    - name: google.storage.v2.Storage

    mixins:

    - name: google.acl.v1.AccessControl

    The mixin construct implies that all methods in `AccessControl` are

    also declared with same name and request/response types in

    `Storage`. A documentation generator or annotation processor will

    see the effective `Storage.GetAcl` method after inherting

    documentation and annotations as follows:

    service Storage {

    // Get the underlying ACL object.

    rpc GetAcl(GetAclRequest) returns (Acl) {

    option (google.api.http).get = "/v2/{resource=**}:getAcl";

    }

    ...

    }

    Note how the version in the path pattern changed from `v1` to `v2`.

    If the `root` field in the mixin is specified, it should be a

    relative path under which inherited HTTP paths are placed. Example:

    apis:

    - name: google.storage.v2.Storage

    mixins:

    - name: google.acl.v1.AccessControl

    root: acls

    This implies the following inherited HTTP annotation:

    service Storage {

    // Get the underlying ACL object.

    rpc GetAcl(GetAclRequest) returns (Acl) {

    option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

    }

    ...

    }

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestring

    The fully qualified name of the interface which is included.

    rootstring

    If non-empty specifies a path under which inherited HTTP paths +are rooted.

    + + + + + + + + + + + + +
    +

    google/protobuf/compiler/plugin.proto

    Top +
    +

    + + +

    CodeGeneratorRequest

    +

    An encoded CodeGeneratorRequest is written to the plugin's stdin.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    file_to_generatestringrepeated

    The .proto files that were explicitly listed on the command-line. The +code generator should generate code only for these files. Each file's +descriptor will be included in proto_file, below.

    parameterstringoptional

    The generator parameter passed on the command-line.

    proto_filegoogle.protobuf.FileDescriptorProtorepeated

    FileDescriptorProtos for all files in files_to_generate and everything +they import. The files will appear in topological order, so each file +appears before any file that imports it. + +protoc guarantees that all proto_files will be written after +the fields above, even though this is not technically guaranteed by the +protobuf wire format. This theoretically could allow a plugin to stream +in the FileDescriptorProtos and handle them one by one rather than read +the entire set into memory at once. However, as of this writing, this +is not similarly optimized on protoc's end -- it will store all fields in +memory at once before sending them to the plugin. + +Type names of fields and extensions in the FileDescriptorProto are always +fully qualified.

    compiler_versionVersionoptional

    The version number of protocol compiler.

    + + + + +

    CodeGeneratorResponse

    +

    The plugin writes an encoded CodeGeneratorResponse to stdout.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    errorstringoptional

    Error message. If non-empty, code generation failed. The plugin process +should exit with status code zero even if it reports an error in this way. + +This should be used to indicate errors in .proto files which prevent the +code generator from generating correct code. Errors which indicate a +problem in protoc itself -- such as the input CodeGeneratorRequest being +unparseable -- should be reported by writing a message to stderr and +exiting with a non-zero status code.

    fileCodeGeneratorResponse.Filerepeated

    + + + + +

    CodeGeneratorResponse.File

    +

    Represents a single generated file.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    The file name, relative to the output directory. The name must not +contain "." or ".." components and must be relative, not be absolute (so, +the file cannot lie outside the output directory). "/" must be used as +the path separator, not "\". + +If the name is omitted, the content will be appended to the previous +file. This allows the generator to break large files into small chunks, +and allows the generated text to be streamed back to protoc so that large +files need not reside completely in memory at one time. Note that as of +this writing protoc does not optimize for this -- it will read the entire +CodeGeneratorResponse before writing files to disk.

    insertion_pointstringoptional

    If non-empty, indicates that the named file should already exist, and the +content here is to be inserted into that file at a defined insertion +point. This feature allows a code generator to extend the output +produced by another code generator. The original generator may provide +insertion points by placing special annotations in the file that look +like: + @@protoc_insertion_point(NAME) +The annotation can have arbitrary text before and after it on the line, +which allows it to be placed in a comment. NAME should be replaced with +an identifier naming the point -- this is what other generators will use +as the insertion_point. Code inserted at this point will be placed +immediately above the line containing the insertion point (thus multiple +insertions to the same point will come out in the order they were added). +The double-@ is intended to make it unlikely that the generated code +could contain things that look like insertion points by accident. + +For example, the C++ code generator places the following line in the +.pb.h files that it generates: + // @@protoc_insertion_point(namespace_scope) +This line appears within the scope of the file's package namespace, but +outside of any particular class. Another plugin can then specify the +insertion_point "namespace_scope" to generate additional classes or +other declarations that should be placed in this scope. + +Note that if the line containing the insertion point begins with +whitespace, the same whitespace will be added to every line of the +inserted text. This is useful for languages like Python, where +indentation matters. In these languages, the insertion point comment +should be indented the same amount as any inserted code will need to be +in order to work correctly in that context. + +The code generator that generates the initial file and the one which +inserts into it must both run as part of a single invocation of protoc. +Code generators are executed in the order in which they appear on the +command line. + +If |insertion_point| is present, |name| must also be present.

    contentstringoptional

    The file contents.

    + + + + +

    Version

    +

    The version number of protocol compiler.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    majorint32optional

    minorint32optional

    patchint32optional

    suffixstringoptional

    A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should +be empty for mainline stable releases.

    + + + + + + + + + + + + +
    +

    google/protobuf/descriptor.proto

    Top +
    +

    + + +

    DescriptorProto

    +

    Describes a message type.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    fieldFieldDescriptorProtorepeated

    extensionFieldDescriptorProtorepeated

    nested_typeDescriptorProtorepeated

    enum_typeEnumDescriptorProtorepeated

    extension_rangeDescriptorProto.ExtensionRangerepeated

    oneof_declOneofDescriptorProtorepeated

    optionsMessageOptionsoptional

    reserved_rangeDescriptorProto.ReservedRangerepeated

    reserved_namestringrepeated

    Reserved field names, which may not be used by fields in the same message. +A given name may only be reserved once.

    + + + + +

    DescriptorProto.ExtensionRange

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    startint32optional

    endint32optional

    optionsExtensionRangeOptionsoptional

    + + + + +

    DescriptorProto.ReservedRange

    +

    Range of reserved tag numbers. Reserved tag numbers may not be used by

    fields or extension ranges in the same message. Reserved ranges may

    not overlap.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    startint32optional

    Inclusive.

    endint32optional

    Exclusive.

    + + + + +

    EnumDescriptorProto

    +

    Describes an enum type.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    valueEnumValueDescriptorProtorepeated

    optionsEnumOptionsoptional

    reserved_rangeEnumDescriptorProto.EnumReservedRangerepeated

    Range of reserved numeric values. Reserved numeric values may not be used +by enum values in the same enum declaration. Reserved ranges may not +overlap.

    reserved_namestringrepeated

    Reserved enum value names, which may not be reused. A given name may only +be reserved once.

    + + + + +

    EnumDescriptorProto.EnumReservedRange

    +

    Range of reserved numeric values. Reserved values may not be used by

    entries in the same enum. Reserved ranges may not overlap.

    Note that this is distinct from DescriptorProto.ReservedRange in that it

    is inclusive such that it can appropriately represent the entire int32

    domain.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    startint32optional

    Inclusive.

    endint32optional

    Inclusive.

    + + + + +

    EnumOptions

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    allow_aliasbooloptional

    Set this option to true to allow mapping different tag names to the same +value.

    deprecatedbooloptional

    Is this enum deprecated? +Depending on the target platform, this can emit Deprecated annotations +for the enum, or it will be completely ignored; in the very least, this +is a formalization for deprecating enums. Default: false

    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    EnumValueDescriptorProto

    +

    Describes a value within an enum.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    numberint32optional

    optionsEnumValueOptionsoptional

    + + + + +

    EnumValueOptions

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    deprecatedbooloptional

    Is this enum value deprecated? +Depending on the target platform, this can emit Deprecated annotations +for the enum value, or it will be completely ignored; in the very least, +this is a formalization for deprecating enum values. Default: false

    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    ExtensionRangeOptions

    +

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    FieldDescriptorProto

    +

    Describes a field within a message.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    numberint32optional

    labelFieldDescriptorProto.Labeloptional

    typeFieldDescriptorProto.Typeoptional

    If type_name is set, this need not be set. If both this and type_name +are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP.

    type_namestringoptional

    For message and enum types, this is the name of the type. If the name +starts with a '.', it is fully-qualified. Otherwise, C++-like scoping +rules are used to find the type (i.e. first the nested types within this +message are searched, then within the parent, on up to the root +namespace).

    extendeestringoptional

    For extensions, this is the name of the type being extended. It is +resolved in the same manner as type_name.

    default_valuestringoptional

    For numeric types, contains the original text representation of the value. +For booleans, "true" or "false". +For strings, contains the default text contents (not escaped in any way). +For bytes, contains the C escaped value. All bytes >= 128 are escaped. +TODO(kenton): Base-64 encode?

    oneof_indexint32optional

    If set, gives the index of a oneof in the containing type's oneof_decl +list. This field is a member of that oneof.

    json_namestringoptional

    JSON name of this field. The value is set by protocol compiler. If the +user has set a "json_name" option on this field, that option's value +will be used. Otherwise, it's deduced from the field's name by converting +it to camelCase.

    optionsFieldOptionsoptional

    + + + + +

    FieldOptions

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    ctypeFieldOptions.CTypeoptional

    The ctype option instructs the C++ code generator to use a different +representation of the field than it normally would. See the specific +options below. This option is not yet implemented in the open source +release -- sorry, we'll try to include it in a future version! Default: STRING

    packedbooloptional

    The packed option can be enabled for repeated primitive fields to enable +a more efficient representation on the wire. Rather than repeatedly +writing the tag and type for each element, the entire array is encoded as +a single length-delimited blob. In proto3, only explicit setting it to +false will avoid using packed encoding.

    jstypeFieldOptions.JSTypeoptional

    The jstype option determines the JavaScript type used for values of the +field. The option is permitted only for 64 bit integral and fixed types +(int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING +is represented as JavaScript string, which avoids loss of precision that +can happen when a large value is converted to a floating point JavaScript. +Specifying JS_NUMBER for the jstype causes the generated JavaScript code to +use the JavaScript "number" type. The behavior of the default option +JS_NORMAL is implementation dependent. + +This option is an enum to permit additional types to be added, e.g. +goog.math.Integer. Default: JS_NORMAL

    lazybooloptional

    Should this field be parsed lazily? Lazy applies only to message-type +fields. It means that when the outer message is initially parsed, the +inner message's contents will not be parsed but instead stored in encoded +form. The inner message will actually be parsed when it is first accessed. + +This is only a hint. Implementations are free to choose whether to use +eager or lazy parsing regardless of the value of this option. However, +setting this option true suggests that the protocol author believes that +using lazy parsing on this field is worth the additional bookkeeping +overhead typically needed to implement it. + +This option does not affect the public interface of any generated code; +all method signatures remain the same. Furthermore, thread-safety of the +interface is not affected by this option; const methods remain safe to +call from multiple threads concurrently, while non-const methods continue +to require exclusive access. + + +Note that implementations may choose not to check required fields within +a lazy sub-message. That is, calling IsInitialized() on the outer message +may return true even if the inner message has missing required fields. +This is necessary because otherwise the inner message would have to be +parsed in order to perform the check, defeating the purpose of lazy +parsing. An implementation which chooses not to check required fields +must be consistent about it. That is, for any particular sub-message, the +implementation must either *always* check its required fields, or *never* +check its required fields, regardless of whether or not the message has +been parsed. Default: false

    deprecatedbooloptional

    Is this field deprecated? +Depending on the target platform, this can emit Deprecated annotations +for accessors, or it will be completely ignored; in the very least, this +is a formalization for deprecating fields. Default: false

    weakbooloptional

    For Google-internal migration only. Do not use. Default: false

    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    FileDescriptorProto

    +

    Describes a complete .proto file.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    file name, relative to root of source tree

    packagestringoptional

    e.g. "foo", "foo.bar", etc.

    dependencystringrepeated

    Names of files imported by this file.

    public_dependencyint32repeated

    Indexes of the public imported files in the dependency list above.

    weak_dependencyint32repeated

    Indexes of the weak imported files in the dependency list. +For Google-internal migration only. Do not use.

    message_typeDescriptorProtorepeated

    All top-level definitions in this file.

    enum_typeEnumDescriptorProtorepeated

    serviceServiceDescriptorProtorepeated

    extensionFieldDescriptorProtorepeated

    optionsFileOptionsoptional

    source_code_infoSourceCodeInfooptional

    This field contains optional information about the original source code. +You may safely remove this entire field without harming runtime +functionality of the descriptors -- the information is needed only by +development tools.

    syntaxstringoptional

    The syntax of the proto file. +The supported values are "proto2" and "proto3".

    + + + + +

    FileDescriptorSet

    +

    The protocol compiler can output a FileDescriptorSet containing the .proto

    files it parses.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fileFileDescriptorProtorepeated

    + + + + +

    FileOptions

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    java_packagestringoptional

    Sets the Java package where classes generated from this .proto will be +placed. By default, the proto package is used, but this is often +inappropriate because proto packages do not normally start with backwards +domain names.

    java_outer_classnamestringoptional

    If set, all the classes from the .proto file are wrapped in a single +outer class with the given name. This applies to both Proto1 +(equivalent to the old "--one_java_file" option) and Proto2 (where +a .proto always translates to a single class, but you may want to +explicitly choose the class name).

    java_multiple_filesbooloptional

    If set true, then the Java code generator will generate a separate .java +file for each top-level message, enum, and service defined in the .proto +file. Thus, these types will *not* be nested inside the outer class +named by java_outer_classname. However, the outer class will still be +generated to contain the file's getDescriptor() method as well as any +top-level extensions defined in the file. Default: false

    java_generate_equals_and_hashbooloptional

    This option does nothing.

    java_string_check_utf8booloptional

    If set true, then the Java2 code generator will generate code that +throws an exception whenever an attempt is made to assign a non-UTF-8 +byte sequence to a string field. +Message reflection will do the same. +However, an extension field still accepts non-UTF-8 byte sequences. +This option has no effect on when used with the lite runtime. Default: false

    optimize_forFileOptions.OptimizeModeoptional

    Default: SPEED

    go_packagestringoptional

    Sets the Go package where structs generated from this .proto will be +placed. If omitted, the Go package will be derived from the following: + - The basename of the package import path, if provided. + - Otherwise, the package statement in the .proto file, if present. + - Otherwise, the basename of the .proto file, without extension.

    cc_generic_servicesbooloptional

    Should generic services be generated in each language? "Generic" services +are not specific to any particular RPC system. They are generated by the +main code generators in each language (without additional plugins). +Generic services were the only kind of service generation supported by +early versions of google.protobuf. + +Generic services are now considered deprecated in favor of using plugins +that generate code specific to your particular RPC system. Therefore, +these default to false. Old code which depends on generic services should +explicitly set them to true. Default: false

    java_generic_servicesbooloptional

    Default: false

    py_generic_servicesbooloptional

    Default: false

    php_generic_servicesbooloptional

    Default: false

    deprecatedbooloptional

    Is this file deprecated? +Depending on the target platform, this can emit Deprecated annotations +for everything in the file, or it will be completely ignored; in the very +least, this is a formalization for deprecating files. Default: false

    cc_enable_arenasbooloptional

    Enables the use of arenas for the proto messages in this file. This applies +only to generated classes for C++. Default: false

    objc_class_prefixstringoptional

    Sets the objective c class prefix which is prepended to all objective c +generated classes from this .proto. There is no default.

    csharp_namespacestringoptional

    Namespace for generated classes; defaults to the package.

    swift_prefixstringoptional

    By default Swift generators will take the proto package and CamelCase it +replacing '.' with underscore and use that to prefix the types/symbols +defined. When this options is provided, they will use this value instead +to prefix the types/symbols defined.

    php_class_prefixstringoptional

    Sets the php class prefix which is prepended to all php generated classes +from this .proto. Default is empty.

    php_namespacestringoptional

    Use this option to change the namespace of php generated classes. Default +is empty. When this option is empty, the package name will be used for +determining the namespace.

    php_metadata_namespacestringoptional

    Use this option to change the namespace of php generated metadata classes. +Default is empty. When this option is empty, the proto file name will be used +for determining the namespace.

    ruby_packagestringoptional

    Use this option to change the package of ruby generated classes. Default +is empty. When this option is not set, the package name will be used for +determining the ruby package.

    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. +See the documentation for the "Options" section above.

    + + + + +

    GeneratedCodeInfo

    +

    Describes the relationship between generated code and its original source

    file. A GeneratedCodeInfo message is associated with only one generated

    source file, but may contain references to different source .proto files.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    annotationGeneratedCodeInfo.Annotationrepeated

    An Annotation connects some span of text in generated code to an element +of its generating .proto file.

    + + + + +

    GeneratedCodeInfo.Annotation

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    pathint32repeated

    Identifies the element in the original source .proto file. This field +is formatted the same as SourceCodeInfo.Location.path.

    source_filestringoptional

    Identifies the filesystem path to the original source .proto.

    beginint32optional

    Identifies the starting offset in bytes in the generated code +that relates to the identified object.

    endint32optional

    Identifies the ending offset in bytes in the generated code that +relates to the identified offset. The end offset should be one past +the last relevant byte (so the length of the text = end - begin).

    + + + + +

    MessageOptions

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    message_set_wire_formatbooloptional

    Set true to use the old proto1 MessageSet wire format for extensions. +This is provided for backwards-compatibility with the MessageSet wire +format. You should not use this for any other reason: It's less +efficient, has fewer features, and is more complicated. + +The message must be defined exactly as follows: + message Foo { + option message_set_wire_format = true; + extensions 4 to max; + } +Note that the message cannot have any defined fields; MessageSets only +have extensions. + +All extensions of your type must be singular messages; e.g. they cannot +be int32s, enums, or repeated messages. + +Because this is an option, the above two restrictions are not enforced by +the protocol compiler. Default: false

    no_standard_descriptor_accessorbooloptional

    Disables the generation of the standard "descriptor()" accessor, which can +conflict with a field of the same name. This is meant to make migration +from proto1 easier; new code should avoid fields named "descriptor". Default: false

    deprecatedbooloptional

    Is this message deprecated? +Depending on the target platform, this can emit Deprecated annotations +for the message, or it will be completely ignored; in the very least, +this is a formalization for deprecating messages. Default: false

    map_entrybooloptional

    Whether the message is an automatically generated map entry type for the +maps field. + +For maps fields: + map<KeyType, ValueType> map_field = 1; +The parsed descriptor looks like: + message MapFieldEntry { + option map_entry = true; + optional KeyType key = 1; + optional ValueType value = 2; + } + repeated MapFieldEntry map_field = 1; + +Implementations may choose not to generate the map_entry=true message, but +use a native map in the target language to hold the keys and values. +The reflection APIs in such implementions still need to work as +if the field is a repeated message field. + +NOTE: Do not set the option in .proto files. Always use the maps syntax +instead. The option should only be implicitly set by the proto compiler +parser.

    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    MethodDescriptorProto

    +

    Describes a method of a service.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    input_typestringoptional

    Input and output type names. These are resolved in the same way as +FieldDescriptorProto.type_name, but must refer to a message type.

    output_typestringoptional

    optionsMethodOptionsoptional

    client_streamingbooloptional

    Identifies if client streams multiple client messages Default: false

    server_streamingbooloptional

    Identifies if server streams multiple server messages Default: false

    + + + + +

    MethodOptions

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    deprecatedbooloptional

    Is this method deprecated? +Depending on the target platform, this can emit Deprecated annotations +for the method, or it will be completely ignored; in the very least, +this is a formalization for deprecating methods. Default: false

    idempotency_levelMethodOptions.IdempotencyLeveloptional

    Default: IDEMPOTENCY_UNKNOWN

    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    OneofDescriptorProto

    +

    Describes a oneof.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    optionsOneofOptionsoptional

    + + + + +

    OneofOptions

    +

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    ServiceDescriptorProto

    +

    Describes a service.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestringoptional

    methodMethodDescriptorProtorepeated

    optionsServiceOptionsoptional

    + + + + +

    ServiceOptions

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    deprecatedbooloptional

    Is this service deprecated? +Depending on the target platform, this can emit Deprecated annotations +for the service, or it will be completely ignored; in the very least, +this is a formalization for deprecating services. Default: false

    uninterpreted_optionUninterpretedOptionrepeated

    The parser stores options it doesn't recognize here. See above.

    + + + + +

    SourceCodeInfo

    +

    Encapsulates information about the original source file from which a

    FileDescriptorProto was generated.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    locationSourceCodeInfo.Locationrepeated

    A Location identifies a piece of source code in a .proto file which +corresponds to a particular definition. This information is intended +to be useful to IDEs, code indexers, documentation generators, and similar +tools. + +For example, say we have a file like: + message Foo { + optional string foo = 1; + } +Let's look at just the field definition: + optional string foo = 1; + ^ ^^ ^^ ^ ^^^ + a bc de f ghi +We have the following locations: + span path represents + [a,i) [ 4, 0, 2, 0 ] The whole field definition. + [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). + [c,d) [ 4, 0, 2, 0, 5 ] The type (string). + [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). + [g,h) [ 4, 0, 2, 0, 3 ] The number (1). + +Notes: +- A location may refer to a repeated field itself (i.e. not to any + particular index within it). This is used whenever a set of elements are + logically enclosed in a single code segment. For example, an entire + extend block (possibly containing multiple extension definitions) will + have an outer location whose path refers to the "extensions" repeated + field without an index. +- Multiple locations may have the same path. This happens when a single + logical declaration is spread out across multiple places. The most + obvious example is the "extend" block again -- there may be multiple + extend blocks in the same scope, each of which will have the same path. +- A location's span is not always a subset of its parent's span. For + example, the "extendee" of an extension declaration appears at the + beginning of the "extend" block and is shared by all extensions within + the block. +- Just because a location's span is a subset of some other location's span + does not mean that it is a descendent. For example, a "group" defines + both a type and a field in a single declaration. Thus, the locations + corresponding to the type and field and their components will overlap. +- Code which tries to interpret locations should probably be designed to + ignore those that it doesn't understand, as more types of locations could + be recorded in the future.

    + + + + +

    SourceCodeInfo.Location

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    pathint32repeated

    Identifies which part of the FileDescriptorProto was defined at this +location. + +Each element is a field number or an index. They form a path from +the root FileDescriptorProto to the place where the definition. For +example, this path: + [ 4, 3, 2, 7, 1 ] +refers to: + file.message_type(3) // 4, 3 + .field(7) // 2, 7 + .name() // 1 +This is because FileDescriptorProto.message_type has field number 4: + repeated DescriptorProto message_type = 4; +and DescriptorProto.field has field number 2: + repeated FieldDescriptorProto field = 2; +and FieldDescriptorProto.name has field number 1: + optional string name = 1; + +Thus, the above path gives the location of a field name. If we removed +the last element: + [ 4, 3, 2, 7 ] +this path refers to the whole field declaration (from the beginning +of the label to the terminating semicolon).

    spanint32repeated

    Always has exactly three or four elements: start line, start column, +end line (optional, otherwise assumed same as start line), end column. +These are packed into a single field for efficiency. Note that line +and column numbers are zero-based -- typically you will want to add +1 to each before displaying to a user.

    leading_commentsstringoptional

    If this SourceCodeInfo represents a complete declaration, these are any +comments appearing before and after the declaration which appear to be +attached to the declaration. + +A series of line comments appearing on consecutive lines, with no other +tokens appearing on those lines, will be treated as a single comment. + +leading_detached_comments will keep paragraphs of comments that appear +before (but not connected to) the current element. Each paragraph, +separated by empty lines, will be one comment element in the repeated +field. + +Only the comment content is provided; comment markers (e.g. //) are +stripped out. For block comments, leading whitespace and an asterisk +will be stripped from the beginning of each line other than the first. +Newlines are included in the output. + +Examples: + + optional int32 foo = 1; // Comment attached to foo. + // Comment attached to bar. + optional int32 bar = 2; + + optional string baz = 3; + // Comment attached to baz. + // Another line attached to baz. + + // Comment attached to qux. + // + // Another line attached to qux. + optional double qux = 4; + + // Detached comment for corge. This is not leading or trailing comments + // to qux or corge because there are blank lines separating it from + // both. + + // Detached comment for corge paragraph 2. + + optional string corge = 5; + /* Block comment attached + * to corge. Leading asterisks + * will be removed. */ + /* Block comment attached to + * grault. */ + optional int32 grault = 6; + + // ignored detached comments.

    trailing_commentsstringoptional

    leading_detached_commentsstringrepeated

    + + + + +

    UninterpretedOption

    +

    A message representing a option the parser does not recognize. This only

    appears in options protos created by the compiler::Parser class.

    DescriptorPool resolves these when building Descriptor objects. Therefore,

    options protos in descriptor objects (e.g. returned by Descriptor::options(),

    or produced by Descriptor::CopyTo()) will never have UninterpretedOptions

    in them.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    nameUninterpretedOption.NamePartrepeated

    identifier_valuestringoptional

    The value of the uninterpreted option, in whatever type the tokenizer +identified it as during parsing. Exactly one of these should be set.

    positive_int_valueuint64optional

    negative_int_valueint64optional

    double_valuedoubleoptional

    string_valuebytesoptional

    aggregate_valuestringoptional

    + + + + +

    UninterpretedOption.NamePart

    +

    The name of the uninterpreted option. Each string represents a segment in

    a dot-separated name. is_extension is true iff a segment represents an

    extension (denoted with parentheses in options specs in .proto files).

    E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents

    "foo.(bar.baz).qux".

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    name_partstringrequired

    is_extensionboolrequired

    + + + + + + +

    FieldDescriptorProto.Label

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    LABEL_OPTIONAL1

    0 is reserved for errors

    LABEL_REQUIRED2

    LABEL_REPEATED3

    + +

    FieldDescriptorProto.Type

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    TYPE_DOUBLE1

    0 is reserved for errors. +Order is weird for historical reasons.

    TYPE_FLOAT2

    TYPE_INT643

    Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if +negative values are likely.

    TYPE_UINT644

    TYPE_INT325

    Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if +negative values are likely.

    TYPE_FIXED646

    TYPE_FIXED327

    TYPE_BOOL8

    TYPE_STRING9

    TYPE_GROUP10

    Tag-delimited aggregate. +Group type is deprecated and not supported in proto3. However, Proto3 +implementations should still be able to parse the group wire format and +treat group fields as unknown fields.

    TYPE_MESSAGE11

    Length-delimited aggregate.

    TYPE_BYTES12

    New in version 2.

    TYPE_UINT3213

    TYPE_ENUM14

    TYPE_SFIXED3215

    TYPE_SFIXED6416

    TYPE_SINT3217

    Uses ZigZag encoding.

    TYPE_SINT6418

    Uses ZigZag encoding.

    + +

    FieldOptions.CType

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    STRING0

    Default mode.

    CORD1

    STRING_PIECE2

    + +

    FieldOptions.JSType

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    JS_NORMAL0

    Use the default type.

    JS_STRING1

    Use JavaScript strings.

    JS_NUMBER2

    Use JavaScript numbers.

    + +

    FileOptions.OptimizeMode

    +

    Generated classes can be optimized for speed or code size.

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    SPEED1

    Generate complete code for parsing, serialization,

    CODE_SIZE2

    etc. + +Use ReflectionOps to implement these methods.

    LITE_RUNTIME3

    Generate code using MessageLite and the lite runtime.

    + +

    MethodOptions.IdempotencyLevel

    +

    Is this method side-effect-free (or safe in HTTP parlance), or idempotent,

    or neither? HTTP based RPC implementation may choose GET verb for safe

    methods, and PUT verb for idempotent methods instead of the default POST.

    + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    IDEMPOTENCY_UNKNOWN0

    NO_SIDE_EFFECTS1

    implies idempotent

    IDEMPOTENT2

    idempotent, but may have side effects

    + + + + + + + +
    +

    google/protobuf/duration.proto

    Top +
    +

    + + +

    Duration

    +

    A Duration represents a signed, fixed-length span of time represented

    as a count of seconds and fractions of seconds at nanosecond

    resolution. It is independent of any calendar and concepts like "day"

    or "month". It is related to Timestamp in that the difference between

    two Timestamp values is a Duration and it can be added or subtracted

    from a Timestamp. Range is approximately +-10,000 years.

    # Examples

    Example 1: Compute Duration from two Timestamps in pseudo code.

    Timestamp start = ...;

    Timestamp end = ...;

    Duration duration = ...;

    duration.seconds = end.seconds - start.seconds;

    duration.nanos = end.nanos - start.nanos;

    if (duration.seconds < 0 && duration.nanos > 0) {

    duration.seconds += 1;

    duration.nanos -= 1000000000;

    } else if (durations.seconds > 0 && duration.nanos < 0) {

    duration.seconds -= 1;

    duration.nanos += 1000000000;

    }

    Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.

    Timestamp start = ...;

    Duration duration = ...;

    Timestamp end = ...;

    end.seconds = start.seconds + duration.seconds;

    end.nanos = start.nanos + duration.nanos;

    if (end.nanos < 0) {

    end.seconds -= 1;

    end.nanos += 1000000000;

    } else if (end.nanos >= 1000000000) {

    end.seconds += 1;

    end.nanos -= 1000000000;

    }

    Example 3: Compute Duration from datetime.timedelta in Python.

    td = datetime.timedelta(days=3, minutes=10)

    duration = Duration()

    duration.FromTimedelta(td)

    # JSON Mapping

    In JSON format, the Duration type is encoded as a string rather than an

    object, where the string ends in the suffix "s" (indicating seconds) and

    is preceded by the number of seconds, with nanoseconds expressed as

    fractional seconds. For example, 3 seconds with 0 nanoseconds should be

    encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should

    be expressed in JSON format as "3.000000001s", and 3 seconds and 1

    microsecond should be expressed in JSON format as "3.000001s".

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    secondsint64

    Signed seconds of the span of time. Must be from -315,576,000,000 +to +315,576,000,000 inclusive. Note: these bounds are computed from: +60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

    nanosint32

    Signed fractions of a second at nanosecond resolution of the span +of time. Durations less than one second are represented with a 0 +`seconds` field and a positive or negative `nanos` field. For durations +of one second or more, a non-zero value for the `nanos` field must be +of the same sign as the `seconds` field. Must be from -999,999,999 +to +999,999,999 inclusive.

    + + + + + + + + + + + + +
    +

    google/protobuf/empty.proto

    Top +
    +

    + + +

    Empty

    +

    A generic empty message that you can re-use to avoid defining duplicated

    empty messages in your APIs. A typical example is to use it as the request

    or the response type of an API method. For instance:

    service Foo {

    rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

    }

    The JSON representation for `Empty` is empty JSON object `{}`.

    + + + + + + + + + + + + + +
    +

    google/protobuf/field_mask.proto

    Top +
    +

    + + +

    FieldMask

    +

    `FieldMask` represents a set of symbolic field paths, for example:

    paths: "f.a"

    paths: "f.b.d"

    Here `f` represents a field in some root message, `a` and `b`

    fields in the message found in `f`, and `d` a field found in the

    message in `f.b`.

    Field masks are used to specify a subset of fields that should be

    returned by a get operation or modified by an update operation.

    Field masks also have a custom JSON encoding (see below).

    # Field Masks in Projections

    When used in the context of a projection, a response message or

    sub-message is filtered by the API to only contain those fields as

    specified in the mask. For example, if the mask in the previous

    example is applied to a response message as follows:

    f {

    a : 22

    b {

    d : 1

    x : 2

    }

    y : 13

    }

    z: 8

    The result will not contain specific values for fields x,y and z

    (their value will be set to the default, and omitted in proto text

    output):

    f {

    a : 22

    b {

    d : 1

    }

    }

    A repeated field is not allowed except at the last position of a

    paths string.

    If a FieldMask object is not present in a get operation, the

    operation applies to all fields (as if a FieldMask of all fields

    had been specified).

    Note that a field mask does not necessarily apply to the

    top-level response message. In case of a REST get operation, the

    field mask applies directly to the response, but in case of a REST

    list operation, the mask instead applies to each individual message

    in the returned resource list. In case of a REST custom method,

    other definitions may be used. Where the mask applies will be

    clearly documented together with its declaration in the API. In

    any case, the effect on the returned resource/resources is required

    behavior for APIs.

    # Field Masks in Update Operations

    A field mask in update operations specifies which fields of the

    targeted resource are going to be updated. The API is required

    to only change the values of the fields as specified in the mask

    and leave the others untouched. If a resource is passed in to

    describe the updated values, the API ignores the values of all

    fields not covered by the mask.

    If a repeated field is specified for an update operation, the existing

    repeated values in the target resource will be overwritten by the new values.

    Note that a repeated field is only allowed in the last position of a `paths`

    string.

    If a sub-message is specified in the last position of the field mask for an

    update operation, then the existing sub-message in the target resource is

    overwritten. Given the target message:

    f {

    b {

    d : 1

    x : 2

    }

    c : 1

    }

    And an update message:

    f {

    b {

    d : 10

    }

    }

    then if the field mask is:

    paths: "f.b"

    then the result will be:

    f {

    b {

    d : 10

    }

    c : 1

    }

    However, if the update mask was:

    paths: "f.b.d"

    then the result would be:

    f {

    b {

    d : 10

    x : 2

    }

    c : 1

    }

    In order to reset a field's value to the default, the field must

    be in the mask and set to the default value in the provided resource.

    Hence, in order to reset all fields of a resource, provide a default

    instance of the resource and set all fields in the mask, or do

    not provide a mask as described below.

    If a field mask is not present on update, the operation applies to

    all fields (as if a field mask of all fields has been specified).

    Note that in the presence of schema evolution, this may mean that

    fields the client does not know and has therefore not filled into

    the request will be reset to their default. If this is unwanted

    behavior, a specific service may require a client to always specify

    a field mask, producing an error if not.

    As with get operations, the location of the resource which

    describes the updated values in the request message depends on the

    operation kind. In any case, the effect of the field mask is

    required to be honored by the API.

    ## Considerations for HTTP REST

    The HTTP kind of an update operation which uses a field mask must

    be set to PATCH instead of PUT in order to satisfy HTTP semantics

    (PUT must only be used for full updates).

    # JSON Encoding of Field Masks

    In JSON, a field mask is encoded as a single string where paths are

    separated by a comma. Fields name in each path are converted

    to/from lower-camel naming conventions.

    As an example, consider the following message declarations:

    message Profile {

    User user = 1;

    Photo photo = 2;

    }

    message User {

    string display_name = 1;

    string address = 2;

    }

    In proto a field mask for `Profile` may look as such:

    mask {

    paths: "user.display_name"

    paths: "photo"

    }

    In JSON, the same mask is represented as below:

    {

    mask: "user.displayName,photo"

    }

    # Field Masks and Oneof Fields

    Field masks treat fields in oneofs just as regular fields. Consider the

    following message:

    message SampleMessage {

    oneof test_oneof {

    string name = 4;

    SubMessage sub_message = 9;

    }

    }

    The field mask can be:

    mask {

    paths: "name"

    }

    Or:

    mask {

    paths: "sub_message"

    }

    Note that oneof type names ("test_oneof" in this case) cannot be used in

    paths.

    ## Field Mask Verification

    The implementation of any API method which has a FieldMask type field in the

    request should verify the included field paths, and return an

    `INVALID_ARGUMENT` error if any path is duplicated or unmappable.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    pathsstringrepeated

    The set of field mask paths.

    + + + + + + + + + + + + +
    +

    google/protobuf/source_context.proto

    Top +
    +

    + + +

    SourceContext

    +

    `SourceContext` represents information about the source of a

    protobuf element, like the file in which it is defined.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    file_namestring

    The path-qualified name of the .proto file that contained the associated +protobuf element. For example: `"google/protobuf/source_context.proto"`.

    + + + + + + + + + + + + +
    +

    google/protobuf/struct.proto

    Top +
    +

    + + +

    ListValue

    +

    `ListValue` is a wrapper around a repeated field of values.

    The JSON representation for `ListValue` is JSON array.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valuesValuerepeated

    Repeated field of dynamically typed values.

    + + + + +

    Struct

    +

    `Struct` represents a structured data value, consisting of fields

    which map to dynamically typed values. In some languages, `Struct`

    might be supported by a native representation. For example, in

    scripting languages like JS a struct is represented as an

    object. The details of that representation are described together

    with the proto support for the language.

    The JSON representation for `Struct` is JSON object.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    fieldsStruct.FieldsEntryrepeated

    Unordered map of dynamically typed values.

    + + + + +

    Struct.FieldsEntry

    +

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    keystring

    valueValue

    + + + + +

    Value

    +

    `Value` represents a dynamically typed value which can be either

    null, a number, a string, a boolean, a recursive struct value, or a

    list of values. A producer of value is expected to set one of that

    variants, absence of any variant indicates an error.

    The JSON representation for `Value` is JSON value.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    null_valueNullValue

    Represents a null value.

    number_valuedouble

    Represents a double value.

    string_valuestring

    Represents a string value.

    bool_valuebool

    Represents a boolean value.

    struct_valueStruct

    Represents a structured value.

    list_valueListValue

    Represents a repeated `Value`.

    + + + + + + +

    NullValue

    +

    `NullValue` is a singleton enumeration to represent the null value for the

    `Value` type union.

    The JSON representation for `NullValue` is JSON `null`.

    + + + + + + + + + + + + + +
    NameNumberDescription
    NULL_VALUE0

    Null value.

    + + + + + + + +
    +

    google/protobuf/timestamp.proto

    Top +
    +

    + + +

    Timestamp

    +

    A Timestamp represents a point in time independent of any time zone

    or calendar, represented as seconds and fractions of seconds at

    nanosecond resolution in UTC Epoch time. It is encoded using the

    Proleptic Gregorian Calendar which extends the Gregorian calendar

    backwards to year one. It is encoded assuming all minutes are 60

    seconds long, i.e. leap seconds are "smeared" so that no leap second

    table is needed for interpretation. Range is from

    0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.

    By restricting to that range, we ensure that we can convert to

    and from RFC 3339 date strings.

    See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).

    # Examples

    Example 1: Compute Timestamp from POSIX `time()`.

    Timestamp timestamp;

    timestamp.set_seconds(time(NULL));

    timestamp.set_nanos(0);

    Example 2: Compute Timestamp from POSIX `gettimeofday()`.

    struct timeval tv;

    gettimeofday(&tv, NULL);

    Timestamp timestamp;

    timestamp.set_seconds(tv.tv_sec);

    timestamp.set_nanos(tv.tv_usec * 1000);

    Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.

    FILETIME ft;

    GetSystemTimeAsFileTime(&ft);

    UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

    // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z

    // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.

    Timestamp timestamp;

    timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));

    timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

    Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.

    long millis = System.currentTimeMillis();

    Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)

    .setNanos((int) ((millis % 1000) * 1000000)).build();

    Example 5: Compute Timestamp from current time in Python.

    timestamp = Timestamp()

    timestamp.GetCurrentTime()

    # JSON Mapping

    In JSON format, the Timestamp type is encoded as a string in the

    [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the

    format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"

    where {year} is always expressed using four digits while {month}, {day},

    {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional

    seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),

    are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone

    is required. A proto3 JSON serializer should always use UTC (as indicated by

    "Z") when printing the Timestamp type and a proto3 JSON parser should be

    able to accept both UTC and other timezones (as indicated by an offset).

    For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past

    01:30 UTC on January 15, 2017.

    In JavaScript, one can convert a Date object to this format using the

    standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]

    method. In Python, a standard `datetime.datetime` object can be converted

    to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)

    with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one

    can use the Joda Time's [`ISODateTimeFormat.dateTime()`](

    http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--

    ) to obtain a formatter capable of generating timestamps in this format.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    secondsint64

    Represents seconds of UTC time since Unix epoch +1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to +9999-12-31T23:59:59Z inclusive.

    nanosint32

    Non-negative fractions of a second at nanosecond resolution. Negative +second values with fractions must still have non-negative nanos values +that count forward in time. Must be from 0 to 999,999,999 +inclusive.

    + + + + + + + + + + + + +
    +

    google/protobuf/type.proto

    Top +
    +

    + + +

    Enum

    +

    Enum type definition.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestring

    Enum type name.

    enumvalueEnumValuerepeated

    Enum value definitions.

    optionsOptionrepeated

    Protocol buffer options.

    source_contextSourceContext

    The source context.

    syntaxSyntax

    The source syntax.

    + + + + +

    EnumValue

    +

    Enum value definition.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestring

    Enum value name.

    numberint32

    Enum value number.

    optionsOptionrepeated

    Protocol buffer options.

    + + + + +

    Field

    +

    A single field of a message type.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    kindField.Kind

    The field type.

    cardinalityField.Cardinality

    The field cardinality.

    numberint32

    The field number.

    namestring

    The field name.

    type_urlstring

    The field type URL, without the scheme, for message or enumeration +types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

    oneof_indexint32

    The index of the field type in `Type.oneofs`, for message or enumeration +types. The first type has index 1; zero means the type is not in the list.

    packedbool

    Whether to use alternative packed wire representation.

    optionsOptionrepeated

    The protocol buffer options.

    json_namestring

    The field JSON name.

    default_valuestring

    The string value of the default value of this field. Proto2 syntax only.

    + + + + +

    Option

    +

    A protocol buffer option, which can be attached to a message, field,

    enumeration, etc.

    + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestring

    The option's name. For protobuf built-in options (options defined in +descriptor.proto), this is the short name. For example, `"map_entry"`. +For custom options, it should be the fully-qualified name. For example, +`"google.api.http"`.

    valueAny

    The option's value packed in an Any message. If the value is a primitive, +the corresponding wrapper type defined in google/protobuf/wrappers.proto +should be used. If the value is an enum, it should be stored as an int32 +value using the google.protobuf.Int32Value type.

    + + + + +

    Type

    +

    A protocol buffer message type.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    namestring

    The fully qualified message name.

    fieldsFieldrepeated

    The list of fields.

    oneofsstringrepeated

    The list of types appearing in `oneof` definitions in this type.

    optionsOptionrepeated

    The protocol buffer options.

    source_contextSourceContext

    The source context.

    syntaxSyntax

    The source syntax.

    + + + + + + +

    Field.Cardinality

    +

    Whether a field is optional, required, or repeated.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    CARDINALITY_UNKNOWN0

    For fields with unknown cardinality.

    CARDINALITY_OPTIONAL1

    For optional fields.

    CARDINALITY_REQUIRED2

    For required fields. Proto2 syntax only.

    CARDINALITY_REPEATED3

    For repeated fields.

    + +

    Field.Kind

    +

    Basic field types.

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    TYPE_UNKNOWN0

    Field type unknown.

    TYPE_DOUBLE1

    Field type double.

    TYPE_FLOAT2

    Field type float.

    TYPE_INT643

    Field type int64.

    TYPE_UINT644

    Field type uint64.

    TYPE_INT325

    Field type int32.

    TYPE_FIXED646

    Field type fixed64.

    TYPE_FIXED327

    Field type fixed32.

    TYPE_BOOL8

    Field type bool.

    TYPE_STRING9

    Field type string.

    TYPE_GROUP10

    Field type group. Proto2 syntax only, and deprecated.

    TYPE_MESSAGE11

    Field type message.

    TYPE_BYTES12

    Field type bytes.

    TYPE_UINT3213

    Field type uint32.

    TYPE_ENUM14

    Field type enum.

    TYPE_SFIXED3215

    Field type sfixed32.

    TYPE_SFIXED6416

    Field type sfixed64.

    TYPE_SINT3217

    Field type sint32.

    TYPE_SINT6418

    Field type sint64.

    + +

    Syntax

    +

    The syntax in which a protocol buffer element is defined.

    + + + + + + + + + + + + + + + + + + + +
    NameNumberDescription
    SYNTAX_PROTO20

    Syntax `proto2`.

    SYNTAX_PROTO31

    Syntax `proto3`.

    + + + + + + + +
    +

    google/protobuf/wrappers.proto

    Top +
    +

    + + +

    BoolValue

    +

    Wrapper message for `bool`.

    The JSON representation for `BoolValue` is JSON `true` and `false`.

    + + + + + + + + + + + + + + -
  • - MExtenableMessagesGenOptions -
    • + +
    FieldTypeLabelDescription
    valuebool

    The bool value.

    + + + + +

    BytesValue

    +

    Wrapper message for `bytes`.

    The JSON representation for `BytesValue` is JSON string.

    + + + + + + + -
  • - MFileFilter -
    • + + + + + + -
  • - MGeneratorScriptsGenOptions -
    • + +
    FieldTypeLabelDescription
    valuebytes

    The bytes value.

    + + + + +

    DoubleValue

    +

    Wrapper message for `double`.

    The JSON representation for `DoubleValue` is JSON number.

    + + + + + + + -
  • - MGrpcStubExtsGenOptions -
    • + + + + + + -
  • - MInsertionsGenOptions -
    • + +
    FieldTypeLabelDescription
    valuedouble

    The double value.

    + + + + +

    FloatValue

    +

    Wrapper message for `float`.

    The JSON representation for `FloatValue` is JSON number.

    + + + + + + + -
  • - MInsertionsGenOptions.Entry -
    • + + + + + + -
  • - MMockServicesGenOptions -
    • + +
    FieldTypeLabelDescription
    valuefloat

    The float value.

    + + + + +

    Int32Value

    +

    Wrapper message for `int32`.

    The JSON representation for `Int32Value` is JSON number.

    + + + + + + + -
  • - MProtoBuildersGenOptions -
    • + + + + + + + +
    FieldTypeLabelDescription
    valueint32

    The int32 value.

    + + + + +

    Int64Value

    +

    Wrapper message for `int64`.

    The JSON representation for `Int64Value` is JSON string.

    + + + + + + + -
  • - EInsertionPoint -
    • + + + + + + + +
    FieldTypeLabelDescription
    valueint64

    The int64 value.

    + + + + +

    StringValue

    +

    Wrapper message for `string`.

    The JSON representation for `StringValue` is JSON string.

    + + + + + + + + + + + + + - - + +
    FieldTypeLabelDescription
    valuestring

    The string value.

    -
  • Scalar Value Types
    • - - + + +

    UInt32Value

    +

    Wrapper message for `uint32`.

    The JSON representation for `UInt32Value` is JSON number.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valueuint32

    The uint32 value.

    + + + + +

    UInt64Value

    +

    Wrapper message for `uint64`.

    The JSON representation for `UInt64Value` is JSON string.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    valueuint64

    The uint64 value.

    + + + + + + + + + +
    @@ -288,6 +4125,13 @@

    CompilerConfig

    Configuration entries for the 'Generator Scripts' code generator.

    + + grpc_coroutines + GrpcCoroutinesGenOptions + repeated +

    Configuration entries for the 'Grpc Coroutines' code generator.

    + + @@ -435,6 +4279,30 @@

    GeneratorScriptsGenOption +

    GrpcCoroutinesGenOptions

    +

    Configuration used by the 'gRPC Coroutines' code generator.

    + + + + + + + + + + + + + + + + +
    FieldTypeLabelDescription
    filterFileFilter

    Filter used for limiting the input files that are processed by the code generator +The default filter will match true against all input files.

    + + + +

    GrpcStubExtsGenOptions

    Configuration used by the 'gRPC Stub Extensions' code generator.

    @@ -634,6 +4502,16 @@

    ProtoBuildersGenOptions

    the output file.

    + + use_dsl_markers + bool + +

    Tag java builder classes with a kotlin interface annotated +with @DslMarker. This requires the kroto-plus output directory to +match the generated java classes directory. Using @DslMarker +provides safer and predictable dsl usage.

    + + diff --git a/docs/markdown/kroto-plus-config.md b/docs/markdown/kroto-plus-config.md index d7a9e3c..646edaa 100644 --- a/docs/markdown/kroto-plus-config.md +++ b/docs/markdown/kroto-plus-config.md @@ -3,11 +3,152 @@ ## Table of Contents +- [google/protobuf/any.proto](#google/protobuf/any.proto) + - [Any](#google.protobuf.Any) + + + + + +- [google/protobuf/api.proto](#google/protobuf/api.proto) + - [Api](#google.protobuf.Api) + - [Method](#google.protobuf.Method) + - [Mixin](#google.protobuf.Mixin) + + + + + +- [google/protobuf/compiler/plugin.proto](#google/protobuf/compiler/plugin.proto) + - [CodeGeneratorRequest](#google.protobuf.compiler.CodeGeneratorRequest) + - [CodeGeneratorResponse](#google.protobuf.compiler.CodeGeneratorResponse) + - [CodeGeneratorResponse.File](#google.protobuf.compiler.CodeGeneratorResponse.File) + - [Version](#google.protobuf.compiler.Version) + + + + + +- [google/protobuf/descriptor.proto](#google/protobuf/descriptor.proto) + - [DescriptorProto](#google.protobuf.DescriptorProto) + - [DescriptorProto.ExtensionRange](#google.protobuf.DescriptorProto.ExtensionRange) + - [DescriptorProto.ReservedRange](#google.protobuf.DescriptorProto.ReservedRange) + - [EnumDescriptorProto](#google.protobuf.EnumDescriptorProto) + - [EnumDescriptorProto.EnumReservedRange](#google.protobuf.EnumDescriptorProto.EnumReservedRange) + - [EnumOptions](#google.protobuf.EnumOptions) + - [EnumValueDescriptorProto](#google.protobuf.EnumValueDescriptorProto) + - [EnumValueOptions](#google.protobuf.EnumValueOptions) + - [ExtensionRangeOptions](#google.protobuf.ExtensionRangeOptions) + - [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) + - [FieldOptions](#google.protobuf.FieldOptions) + - [FileDescriptorProto](#google.protobuf.FileDescriptorProto) + - [FileDescriptorSet](#google.protobuf.FileDescriptorSet) + - [FileOptions](#google.protobuf.FileOptions) + - [GeneratedCodeInfo](#google.protobuf.GeneratedCodeInfo) + - [GeneratedCodeInfo.Annotation](#google.protobuf.GeneratedCodeInfo.Annotation) + - [MessageOptions](#google.protobuf.MessageOptions) + - [MethodDescriptorProto](#google.protobuf.MethodDescriptorProto) + - [MethodOptions](#google.protobuf.MethodOptions) + - [OneofDescriptorProto](#google.protobuf.OneofDescriptorProto) + - [OneofOptions](#google.protobuf.OneofOptions) + - [ServiceDescriptorProto](#google.protobuf.ServiceDescriptorProto) + - [ServiceOptions](#google.protobuf.ServiceOptions) + - [SourceCodeInfo](#google.protobuf.SourceCodeInfo) + - [SourceCodeInfo.Location](#google.protobuf.SourceCodeInfo.Location) + - [UninterpretedOption](#google.protobuf.UninterpretedOption) + - [UninterpretedOption.NamePart](#google.protobuf.UninterpretedOption.NamePart) + + - [FieldDescriptorProto.Label](#google.protobuf.FieldDescriptorProto.Label) + - [FieldDescriptorProto.Type](#google.protobuf.FieldDescriptorProto.Type) + - [FieldOptions.CType](#google.protobuf.FieldOptions.CType) + - [FieldOptions.JSType](#google.protobuf.FieldOptions.JSType) + - [FileOptions.OptimizeMode](#google.protobuf.FileOptions.OptimizeMode) + - [MethodOptions.IdempotencyLevel](#google.protobuf.MethodOptions.IdempotencyLevel) + + + + +- [google/protobuf/duration.proto](#google/protobuf/duration.proto) + - [Duration](#google.protobuf.Duration) + + + + + +- [google/protobuf/empty.proto](#google/protobuf/empty.proto) + - [Empty](#google.protobuf.Empty) + + + + + +- [google/protobuf/field_mask.proto](#google/protobuf/field_mask.proto) + - [FieldMask](#google.protobuf.FieldMask) + + + + + +- [google/protobuf/source_context.proto](#google/protobuf/source_context.proto) + - [SourceContext](#google.protobuf.SourceContext) + + + + + +- [google/protobuf/struct.proto](#google/protobuf/struct.proto) + - [ListValue](#google.protobuf.ListValue) + - [Struct](#google.protobuf.Struct) + - [Struct.FieldsEntry](#google.protobuf.Struct.FieldsEntry) + - [Value](#google.protobuf.Value) + + - [NullValue](#google.protobuf.NullValue) + + + + +- [google/protobuf/timestamp.proto](#google/protobuf/timestamp.proto) + - [Timestamp](#google.protobuf.Timestamp) + + + + + +- [google/protobuf/type.proto](#google/protobuf/type.proto) + - [Enum](#google.protobuf.Enum) + - [EnumValue](#google.protobuf.EnumValue) + - [Field](#google.protobuf.Field) + - [Option](#google.protobuf.Option) + - [Type](#google.protobuf.Type) + + - [Field.Cardinality](#google.protobuf.Field.Cardinality) + - [Field.Kind](#google.protobuf.Field.Kind) + - [Syntax](#google.protobuf.Syntax) + + + + +- [google/protobuf/wrappers.proto](#google/protobuf/wrappers.proto) + - [BoolValue](#google.protobuf.BoolValue) + - [BytesValue](#google.protobuf.BytesValue) + - [DoubleValue](#google.protobuf.DoubleValue) + - [FloatValue](#google.protobuf.FloatValue) + - [Int32Value](#google.protobuf.Int32Value) + - [Int64Value](#google.protobuf.Int64Value) + - [StringValue](#google.protobuf.StringValue) + - [UInt32Value](#google.protobuf.UInt32Value) + - [UInt64Value](#google.protobuf.UInt64Value) + + + + + - [krotoplus/compiler/config.proto](#krotoplus/compiler/config.proto) - [CompilerConfig](#krotoplus.compiler.CompilerConfig) - [ExtenableMessagesGenOptions](#krotoplus.compiler.ExtenableMessagesGenOptions) - [FileFilter](#krotoplus.compiler.FileFilter) - [GeneratorScriptsGenOptions](#krotoplus.compiler.GeneratorScriptsGenOptions) + - [GrpcCoroutinesGenOptions](#krotoplus.compiler.GrpcCoroutinesGenOptions) - [GrpcStubExtsGenOptions](#krotoplus.compiler.GrpcStubExtsGenOptions) - [InsertionsGenOptions](#krotoplus.compiler.InsertionsGenOptions) - [InsertionsGenOptions.Entry](#krotoplus.compiler.InsertionsGenOptions.Entry) @@ -19,7 +160,2024 @@ -- [Scalar Value Types](#scalar-value-types) +- [Scalar Value Types](#scalar-value-types) + + + + +

    Top

    + +## google/protobuf/any.proto + + + + + +### Any +`Any` contains an arbitrary serialized protocol buffer message along with a +URL that describes the type of the serialized message. + +Protobuf library provides support to pack/unpack Any values in the form +of utility functions or additional generated methods of the Any type. + +Example 1: Pack and unpack a message in C++. + + Foo foo = ...; + Any any; + any.PackFrom(foo); + ... + if (any.UnpackTo(&foo)) { + ... + } + +Example 2: Pack and unpack a message in Java. + + Foo foo = ...; + Any any = Any.pack(foo); + ... + if (any.is(Foo.class)) { + foo = any.unpack(Foo.class); + } + + Example 3: Pack and unpack a message in Python. + + foo = Foo(...) + any = Any() + any.Pack(foo) + ... + if any.Is(Foo.DESCRIPTOR): + any.Unpack(foo) + ... + + Example 4: Pack and unpack a message in Go + + foo := &pb.Foo{...} + any, err := ptypes.MarshalAny(foo) + ... + foo := &pb.Foo{} + if err := ptypes.UnmarshalAny(any, foo); err != nil { + ... + } + +The pack methods provided by protobuf library will by default use +'type.googleapis.com/full.type.name' as the type URL and the unpack +methods only use the fully qualified type name after the last '/' +in the type URL, for example "foo.bar.com/x/y.z" will yield type +name "y.z". + + +JSON +==== +The JSON representation of an `Any` value uses the regular +representation of the deserialized, embedded message, with an +additional field `@type` which contains the type URL. Example: + + package google.profile; + message Person { + string first_name = 1; + string last_name = 2; + } + + { + "@type": "type.googleapis.com/google.profile.Person", + "firstName": <string>, + "lastName": <string> + } + +If the embedded message type is well-known and has a custom JSON +representation, that representation will be embedded adding a field +`value` which holds the custom JSON in addition to the `@type` +field. Example (for message [google.protobuf.Duration][]): + + { + "@type": "type.googleapis.com/google.protobuf.Duration", + "value": "1.212s" + } + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| type_url | [string](#string) | | A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted). + +In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: + +* If no scheme is provided, `https` is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) + +Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. + +Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics. | +| value | [bytes](#bytes) | | Must be a valid serialized protocol buffer of the above specified type. | + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/api.proto + + + + + +### Api +Api is a light-weight descriptor for an API Interface. + +Interfaces are also described as "protocol buffer services" in some contexts, +such as by the "service" keyword in a .proto file, but they are different +from API Services, which represent a concrete implementation of an interface +as opposed to simply a description of methods and bindings. They are also +sometimes simply referred to as "APIs" in other contexts, such as the name of +this message itself. See https://cloud.google.com/apis/design/glossary for +detailed terminology. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The fully qualified name of this interface, including package name followed by the interface's simple name. | +| methods | [Method](#google.protobuf.Method) | repeated | The methods of this interface, in unspecified order. | +| options | [Option](#google.protobuf.Option) | repeated | Any metadata attached to the interface. | +| version | [string](#string) | | A version string for this interface. If specified, must have the form `major-version.minor-version`, as in `1.10`. If the minor version is omitted, it defaults to zero. If the entire version field is empty, the major version is derived from the package name, as outlined below. If the field is not empty, the version in the package name will be verified to be consistent with what is provided here. + +The versioning schema uses [semantic versioning](http://semver.org) where the major version number indicates a breaking change and the minor version an additive, non-breaking change. Both version numbers are signals to users what to expect from different versions, and should be carefully chosen based on the product plan. + +The major version is also reflected in the package name of the interface, which must end in `v<major-version>`, as in `google.feature.v1`. For major versions 0 and 1, the suffix can be omitted. Zero major versions must only be used for experimental, non-GA interfaces. | +| source_context | [SourceContext](#google.protobuf.SourceContext) | | Source context for the protocol buffer service represented by this message. | +| mixins | [Mixin](#google.protobuf.Mixin) | repeated | Included interfaces. See [Mixin][]. | +| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax of the service. | + + + + + + + + +### Method +Method represents a method of an API interface. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The simple name of this method. | +| request_type_url | [string](#string) | | A URL of the input message type. | +| request_streaming | [bool](#bool) | | If true, the request is streamed. | +| response_type_url | [string](#string) | | The URL of the output message type. | +| response_streaming | [bool](#bool) | | If true, the response is streamed. | +| options | [Option](#google.protobuf.Option) | repeated | Any metadata attached to the method. | +| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax of this method. | + + + + + + + + +### Mixin +Declares an API Interface to be included in this interface. The including +interface must redeclare all the methods from the included interface, but +documentation and options are inherited as follows: + +- If after comment and whitespace stripping, the documentation + string of the redeclared method is empty, it will be inherited + from the original method. + +- Each annotation belonging to the service config (http, + visibility) which is not set in the redeclared method will be + inherited. + +- If an http annotation is inherited, the path pattern will be + modified as follows. Any version prefix will be replaced by the + version of the including interface plus the [root][] path if + specified. + +Example of a simple mixin: + + package google.acl.v1; + service AccessControl { + // Get the underlying ACL object. + rpc GetAcl(GetAclRequest) returns (Acl) { + option (google.api.http).get = "/v1/{resource=**}:getAcl"; + } + } + + package google.storage.v2; + service Storage { + rpc GetAcl(GetAclRequest) returns (Acl); + + // Get a data record. + rpc GetData(GetDataRequest) returns (Data) { + option (google.api.http).get = "/v2/{resource=**}"; + } + } + +Example of a mixin configuration: + + apis: + - name: google.storage.v2.Storage + mixins: + - name: google.acl.v1.AccessControl + +The mixin construct implies that all methods in `AccessControl` are +also declared with same name and request/response types in +`Storage`. A documentation generator or annotation processor will +see the effective `Storage.GetAcl` method after inherting +documentation and annotations as follows: + + service Storage { + // Get the underlying ACL object. + rpc GetAcl(GetAclRequest) returns (Acl) { + option (google.api.http).get = "/v2/{resource=**}:getAcl"; + } + ... + } + +Note how the version in the path pattern changed from `v1` to `v2`. + +If the `root` field in the mixin is specified, it should be a +relative path under which inherited HTTP paths are placed. Example: + + apis: + - name: google.storage.v2.Storage + mixins: + - name: google.acl.v1.AccessControl + root: acls + +This implies the following inherited HTTP annotation: + + service Storage { + // Get the underlying ACL object. + rpc GetAcl(GetAclRequest) returns (Acl) { + option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; + } + ... + } + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The fully qualified name of the interface which is included. | +| root | [string](#string) | | If non-empty specifies a path under which inherited HTTP paths are rooted. | + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/compiler/plugin.proto + + + + + +### CodeGeneratorRequest +An encoded CodeGeneratorRequest is written to the plugin's stdin. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| file_to_generate | [string](#string) | repeated | The .proto files that were explicitly listed on the command-line. The code generator should generate code only for these files. Each file's descriptor will be included in proto_file, below. | +| parameter | [string](#string) | optional | The generator parameter passed on the command-line. | +| proto_file | [google.protobuf.FileDescriptorProto](#google.protobuf.FileDescriptorProto) | repeated | FileDescriptorProtos for all files in files_to_generate and everything they import. The files will appear in topological order, so each file appears before any file that imports it. + +protoc guarantees that all proto_files will be written after the fields above, even though this is not technically guaranteed by the protobuf wire format. This theoretically could allow a plugin to stream in the FileDescriptorProtos and handle them one by one rather than read the entire set into memory at once. However, as of this writing, this is not similarly optimized on protoc's end -- it will store all fields in memory at once before sending them to the plugin. + +Type names of fields and extensions in the FileDescriptorProto are always fully qualified. | +| compiler_version | [Version](#google.protobuf.compiler.Version) | optional | The version number of protocol compiler. | + + + + + + + + +### CodeGeneratorResponse +The plugin writes an encoded CodeGeneratorResponse to stdout. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| error | [string](#string) | optional | Error message. If non-empty, code generation failed. The plugin process should exit with status code zero even if it reports an error in this way. + +This should be used to indicate errors in .proto files which prevent the code generator from generating correct code. Errors which indicate a problem in protoc itself -- such as the input CodeGeneratorRequest being unparseable -- should be reported by writing a message to stderr and exiting with a non-zero status code. | +| file | [CodeGeneratorResponse.File](#google.protobuf.compiler.CodeGeneratorResponse.File) | repeated | | + + + + + + + + +### CodeGeneratorResponse.File +Represents a single generated file. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | The file name, relative to the output directory. The name must not contain "." or ".." components and must be relative, not be absolute (so, the file cannot lie outside the output directory). "/" must be used as the path separator, not "\". + +If the name is omitted, the content will be appended to the previous file. This allows the generator to break large files into small chunks, and allows the generated text to be streamed back to protoc so that large files need not reside completely in memory at one time. Note that as of this writing protoc does not optimize for this -- it will read the entire CodeGeneratorResponse before writing files to disk. | +| insertion_point | [string](#string) | optional | If non-empty, indicates that the named file should already exist, and the content here is to be inserted into that file at a defined insertion point. This feature allows a code generator to extend the output produced by another code generator. The original generator may provide insertion points by placing special annotations in the file that look like: @@protoc_insertion_point(NAME) The annotation can have arbitrary text before and after it on the line, which allows it to be placed in a comment. NAME should be replaced with an identifier naming the point -- this is what other generators will use as the insertion_point. Code inserted at this point will be placed immediately above the line containing the insertion point (thus multiple insertions to the same point will come out in the order they were added). The double-@ is intended to make it unlikely that the generated code could contain things that look like insertion points by accident. + +For example, the C++ code generator places the following line in the .pb.h files that it generates: // @@protoc_insertion_point(namespace_scope) This line appears within the scope of the file's package namespace, but outside of any particular class. Another plugin can then specify the insertion_point "namespace_scope" to generate additional classes or other declarations that should be placed in this scope. + +Note that if the line containing the insertion point begins with whitespace, the same whitespace will be added to every line of the inserted text. This is useful for languages like Python, where indentation matters. In these languages, the insertion point comment should be indented the same amount as any inserted code will need to be in order to work correctly in that context. + +The code generator that generates the initial file and the one which inserts into it must both run as part of a single invocation of protoc. Code generators are executed in the order in which they appear on the command line. + +If |insertion_point| is present, |name| must also be present. | +| content | [string](#string) | optional | The file contents. | + + + + + + + + +### Version +The version number of protocol compiler. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| major | [int32](#int32) | optional | | +| minor | [int32](#int32) | optional | | +| patch | [int32](#int32) | optional | | +| suffix | [string](#string) | optional | A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should be empty for mainline stable releases. | + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/descriptor.proto + + + + + +### DescriptorProto +Describes a message type. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | | +| field | [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) | repeated | | +| extension | [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) | repeated | | +| nested_type | [DescriptorProto](#google.protobuf.DescriptorProto) | repeated | | +| enum_type | [EnumDescriptorProto](#google.protobuf.EnumDescriptorProto) | repeated | | +| extension_range | [DescriptorProto.ExtensionRange](#google.protobuf.DescriptorProto.ExtensionRange) | repeated | | +| oneof_decl | [OneofDescriptorProto](#google.protobuf.OneofDescriptorProto) | repeated | | +| options | [MessageOptions](#google.protobuf.MessageOptions) | optional | | +| reserved_range | [DescriptorProto.ReservedRange](#google.protobuf.DescriptorProto.ReservedRange) | repeated | | +| reserved_name | [string](#string) | repeated | Reserved field names, which may not be used by fields in the same message. A given name may only be reserved once. | + + + + + + + + +### DescriptorProto.ExtensionRange + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| start | [int32](#int32) | optional | | +| end | [int32](#int32) | optional | | +| options | [ExtensionRangeOptions](#google.protobuf.ExtensionRangeOptions) | optional | | + + + + + + + + +### DescriptorProto.ReservedRange +Range of reserved tag numbers. Reserved tag numbers may not be used by +fields or extension ranges in the same message. Reserved ranges may +not overlap. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| start | [int32](#int32) | optional | Inclusive. | +| end | [int32](#int32) | optional | Exclusive. | + + + + + + + + +### EnumDescriptorProto +Describes an enum type. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | | +| value | [EnumValueDescriptorProto](#google.protobuf.EnumValueDescriptorProto) | repeated | | +| options | [EnumOptions](#google.protobuf.EnumOptions) | optional | | +| reserved_range | [EnumDescriptorProto.EnumReservedRange](#google.protobuf.EnumDescriptorProto.EnumReservedRange) | repeated | Range of reserved numeric values. Reserved numeric values may not be used by enum values in the same enum declaration. Reserved ranges may not overlap. | +| reserved_name | [string](#string) | repeated | Reserved enum value names, which may not be reused. A given name may only be reserved once. | + + + + + + + + +### EnumDescriptorProto.EnumReservedRange +Range of reserved numeric values. Reserved values may not be used by +entries in the same enum. Reserved ranges may not overlap. + +Note that this is distinct from DescriptorProto.ReservedRange in that it +is inclusive such that it can appropriately represent the entire int32 +domain. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| start | [int32](#int32) | optional | Inclusive. | +| end | [int32](#int32) | optional | Inclusive. | + + + + + + + + +### EnumOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| allow_alias | [bool](#bool) | optional | Set this option to true to allow mapping different tag names to the same value. | +| deprecated | [bool](#bool) | optional | Is this enum deprecated? Depending on the target platform, this can emit Deprecated annotations for the enum, or it will be completely ignored; in the very least, this is a formalization for deprecating enums. Default: false | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### EnumValueDescriptorProto +Describes a value within an enum. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | | +| number | [int32](#int32) | optional | | +| options | [EnumValueOptions](#google.protobuf.EnumValueOptions) | optional | | + + + + + + + + +### EnumValueOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| deprecated | [bool](#bool) | optional | Is this enum value deprecated? Depending on the target platform, this can emit Deprecated annotations for the enum value, or it will be completely ignored; in the very least, this is a formalization for deprecating enum values. Default: false | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### ExtensionRangeOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### FieldDescriptorProto +Describes a field within a message. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | | +| number | [int32](#int32) | optional | | +| label | [FieldDescriptorProto.Label](#google.protobuf.FieldDescriptorProto.Label) | optional | | +| type | [FieldDescriptorProto.Type](#google.protobuf.FieldDescriptorProto.Type) | optional | If type_name is set, this need not be set. If both this and type_name are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. | +| type_name | [string](#string) | optional | For message and enum types, this is the name of the type. If the name starts with a '.', it is fully-qualified. Otherwise, C++-like scoping rules are used to find the type (i.e. first the nested types within this message are searched, then within the parent, on up to the root namespace). | +| extendee | [string](#string) | optional | For extensions, this is the name of the type being extended. It is resolved in the same manner as type_name. | +| default_value | [string](#string) | optional | For numeric types, contains the original text representation of the value. For booleans, "true" or "false". For strings, contains the default text contents (not escaped in any way). For bytes, contains the C escaped value. All bytes >= 128 are escaped. TODO(kenton): Base-64 encode? | +| oneof_index | [int32](#int32) | optional | If set, gives the index of a oneof in the containing type's oneof_decl list. This field is a member of that oneof. | +| json_name | [string](#string) | optional | JSON name of this field. The value is set by protocol compiler. If the user has set a "json_name" option on this field, that option's value will be used. Otherwise, it's deduced from the field's name by converting it to camelCase. | +| options | [FieldOptions](#google.protobuf.FieldOptions) | optional | | + + + + + + + + +### FieldOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| ctype | [FieldOptions.CType](#google.protobuf.FieldOptions.CType) | optional | The ctype option instructs the C++ code generator to use a different representation of the field than it normally would. See the specific options below. This option is not yet implemented in the open source release -- sorry, we'll try to include it in a future version! Default: STRING | +| packed | [bool](#bool) | optional | The packed option can be enabled for repeated primitive fields to enable a more efficient representation on the wire. Rather than repeatedly writing the tag and type for each element, the entire array is encoded as a single length-delimited blob. In proto3, only explicit setting it to false will avoid using packed encoding. | +| jstype | [FieldOptions.JSType](#google.protobuf.FieldOptions.JSType) | optional | The jstype option determines the JavaScript type used for values of the field. The option is permitted only for 64 bit integral and fixed types (int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING is represented as JavaScript string, which avoids loss of precision that can happen when a large value is converted to a floating point JavaScript. Specifying JS_NUMBER for the jstype causes the generated JavaScript code to use the JavaScript "number" type. The behavior of the default option JS_NORMAL is implementation dependent. + +This option is an enum to permit additional types to be added, e.g. goog.math.Integer. Default: JS_NORMAL | +| lazy | [bool](#bool) | optional | Should this field be parsed lazily? Lazy applies only to message-type fields. It means that when the outer message is initially parsed, the inner message's contents will not be parsed but instead stored in encoded form. The inner message will actually be parsed when it is first accessed. + +This is only a hint. Implementations are free to choose whether to use eager or lazy parsing regardless of the value of this option. However, setting this option true suggests that the protocol author believes that using lazy parsing on this field is worth the additional bookkeeping overhead typically needed to implement it. + +This option does not affect the public interface of any generated code; all method signatures remain the same. Furthermore, thread-safety of the interface is not affected by this option; const methods remain safe to call from multiple threads concurrently, while non-const methods continue to require exclusive access. + +Note that implementations may choose not to check required fields within a lazy sub-message. That is, calling IsInitialized() on the outer message may return true even if the inner message has missing required fields. This is necessary because otherwise the inner message would have to be parsed in order to perform the check, defeating the purpose of lazy parsing. An implementation which chooses not to check required fields must be consistent about it. That is, for any particular sub-message, the implementation must either *always* check its required fields, or *never* check its required fields, regardless of whether or not the message has been parsed. Default: false | +| deprecated | [bool](#bool) | optional | Is this field deprecated? Depending on the target platform, this can emit Deprecated annotations for accessors, or it will be completely ignored; in the very least, this is a formalization for deprecating fields. Default: false | +| weak | [bool](#bool) | optional | For Google-internal migration only. Do not use. Default: false | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### FileDescriptorProto +Describes a complete .proto file. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | file name, relative to root of source tree | +| package | [string](#string) | optional | e.g. "foo", "foo.bar", etc. | +| dependency | [string](#string) | repeated | Names of files imported by this file. | +| public_dependency | [int32](#int32) | repeated | Indexes of the public imported files in the dependency list above. | +| weak_dependency | [int32](#int32) | repeated | Indexes of the weak imported files in the dependency list. For Google-internal migration only. Do not use. | +| message_type | [DescriptorProto](#google.protobuf.DescriptorProto) | repeated | All top-level definitions in this file. | +| enum_type | [EnumDescriptorProto](#google.protobuf.EnumDescriptorProto) | repeated | | +| service | [ServiceDescriptorProto](#google.protobuf.ServiceDescriptorProto) | repeated | | +| extension | [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) | repeated | | +| options | [FileOptions](#google.protobuf.FileOptions) | optional | | +| source_code_info | [SourceCodeInfo](#google.protobuf.SourceCodeInfo) | optional | This field contains optional information about the original source code. You may safely remove this entire field without harming runtime functionality of the descriptors -- the information is needed only by development tools. | +| syntax | [string](#string) | optional | The syntax of the proto file. The supported values are "proto2" and "proto3". | + + + + + + + + +### FileDescriptorSet +The protocol compiler can output a FileDescriptorSet containing the .proto +files it parses. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| file | [FileDescriptorProto](#google.protobuf.FileDescriptorProto) | repeated | | + + + + + + + + +### FileOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| java_package | [string](#string) | optional | Sets the Java package where classes generated from this .proto will be placed. By default, the proto package is used, but this is often inappropriate because proto packages do not normally start with backwards domain names. | +| java_outer_classname | [string](#string) | optional | If set, all the classes from the .proto file are wrapped in a single outer class with the given name. This applies to both Proto1 (equivalent to the old "--one_java_file" option) and Proto2 (where a .proto always translates to a single class, but you may want to explicitly choose the class name). | +| java_multiple_files | [bool](#bool) | optional | If set true, then the Java code generator will generate a separate .java file for each top-level message, enum, and service defined in the .proto file. Thus, these types will *not* be nested inside the outer class named by java_outer_classname. However, the outer class will still be generated to contain the file's getDescriptor() method as well as any top-level extensions defined in the file. Default: false | +| java_generate_equals_and_hash | [bool](#bool) | optional | This option does nothing. | +| java_string_check_utf8 | [bool](#bool) | optional | If set true, then the Java2 code generator will generate code that throws an exception whenever an attempt is made to assign a non-UTF-8 byte sequence to a string field. Message reflection will do the same. However, an extension field still accepts non-UTF-8 byte sequences. This option has no effect on when used with the lite runtime. Default: false | +| optimize_for | [FileOptions.OptimizeMode](#google.protobuf.FileOptions.OptimizeMode) | optional | Default: SPEED | +| go_package | [string](#string) | optional | Sets the Go package where structs generated from this .proto will be placed. If omitted, the Go package will be derived from the following: - The basename of the package import path, if provided. - Otherwise, the package statement in the .proto file, if present. - Otherwise, the basename of the .proto file, without extension. | +| cc_generic_services | [bool](#bool) | optional | Should generic services be generated in each language? "Generic" services are not specific to any particular RPC system. They are generated by the main code generators in each language (without additional plugins). Generic services were the only kind of service generation supported by early versions of google.protobuf. + +Generic services are now considered deprecated in favor of using plugins that generate code specific to your particular RPC system. Therefore, these default to false. Old code which depends on generic services should explicitly set them to true. Default: false | +| java_generic_services | [bool](#bool) | optional | Default: false | +| py_generic_services | [bool](#bool) | optional | Default: false | +| php_generic_services | [bool](#bool) | optional | Default: false | +| deprecated | [bool](#bool) | optional | Is this file deprecated? Depending on the target platform, this can emit Deprecated annotations for everything in the file, or it will be completely ignored; in the very least, this is a formalization for deprecating files. Default: false | +| cc_enable_arenas | [bool](#bool) | optional | Enables the use of arenas for the proto messages in this file. This applies only to generated classes for C++. Default: false | +| objc_class_prefix | [string](#string) | optional | Sets the objective c class prefix which is prepended to all objective c generated classes from this .proto. There is no default. | +| csharp_namespace | [string](#string) | optional | Namespace for generated classes; defaults to the package. | +| swift_prefix | [string](#string) | optional | By default Swift generators will take the proto package and CamelCase it replacing '.' with underscore and use that to prefix the types/symbols defined. When this options is provided, they will use this value instead to prefix the types/symbols defined. | +| php_class_prefix | [string](#string) | optional | Sets the php class prefix which is prepended to all php generated classes from this .proto. Default is empty. | +| php_namespace | [string](#string) | optional | Use this option to change the namespace of php generated classes. Default is empty. When this option is empty, the package name will be used for determining the namespace. | +| php_metadata_namespace | [string](#string) | optional | Use this option to change the namespace of php generated metadata classes. Default is empty. When this option is empty, the proto file name will be used for determining the namespace. | +| ruby_package | [string](#string) | optional | Use this option to change the package of ruby generated classes. Default is empty. When this option is not set, the package name will be used for determining the ruby package. | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See the documentation for the "Options" section above. | + + + + + + + + +### GeneratedCodeInfo +Describes the relationship between generated code and its original source +file. A GeneratedCodeInfo message is associated with only one generated +source file, but may contain references to different source .proto files. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| annotation | [GeneratedCodeInfo.Annotation](#google.protobuf.GeneratedCodeInfo.Annotation) | repeated | An Annotation connects some span of text in generated code to an element of its generating .proto file. | + + + + + + + + +### GeneratedCodeInfo.Annotation + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| path | [int32](#int32) | repeated | Identifies the element in the original source .proto file. This field is formatted the same as SourceCodeInfo.Location.path. | +| source_file | [string](#string) | optional | Identifies the filesystem path to the original source .proto. | +| begin | [int32](#int32) | optional | Identifies the starting offset in bytes in the generated code that relates to the identified object. | +| end | [int32](#int32) | optional | Identifies the ending offset in bytes in the generated code that relates to the identified offset. The end offset should be one past the last relevant byte (so the length of the text = end - begin). | + + + + + + + + +### MessageOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| message_set_wire_format | [bool](#bool) | optional | Set true to use the old proto1 MessageSet wire format for extensions. This is provided for backwards-compatibility with the MessageSet wire format. You should not use this for any other reason: It's less efficient, has fewer features, and is more complicated. + +The message must be defined exactly as follows: message Foo { option message_set_wire_format = true; extensions 4 to max; } Note that the message cannot have any defined fields; MessageSets only have extensions. + +All extensions of your type must be singular messages; e.g. they cannot be int32s, enums, or repeated messages. + +Because this is an option, the above two restrictions are not enforced by the protocol compiler. Default: false | +| no_standard_descriptor_accessor | [bool](#bool) | optional | Disables the generation of the standard "descriptor()" accessor, which can conflict with a field of the same name. This is meant to make migration from proto1 easier; new code should avoid fields named "descriptor". Default: false | +| deprecated | [bool](#bool) | optional | Is this message deprecated? Depending on the target platform, this can emit Deprecated annotations for the message, or it will be completely ignored; in the very least, this is a formalization for deprecating messages. Default: false | +| map_entry | [bool](#bool) | optional | Whether the message is an automatically generated map entry type for the maps field. + +For maps fields: map<KeyType, ValueType> map_field = 1; The parsed descriptor looks like: message MapFieldEntry { option map_entry = true; optional KeyType key = 1; optional ValueType value = 2; } repeated MapFieldEntry map_field = 1; + +Implementations may choose not to generate the map_entry=true message, but use a native map in the target language to hold the keys and values. The reflection APIs in such implementions still need to work as if the field is a repeated message field. + +NOTE: Do not set the option in .proto files. Always use the maps syntax instead. The option should only be implicitly set by the proto compiler parser. | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### MethodDescriptorProto +Describes a method of a service. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | | +| input_type | [string](#string) | optional | Input and output type names. These are resolved in the same way as FieldDescriptorProto.type_name, but must refer to a message type. | +| output_type | [string](#string) | optional | | +| options | [MethodOptions](#google.protobuf.MethodOptions) | optional | | +| client_streaming | [bool](#bool) | optional | Identifies if client streams multiple client messages Default: false | +| server_streaming | [bool](#bool) | optional | Identifies if server streams multiple server messages Default: false | + + + + + + + + +### MethodOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| deprecated | [bool](#bool) | optional | Is this method deprecated? Depending on the target platform, this can emit Deprecated annotations for the method, or it will be completely ignored; in the very least, this is a formalization for deprecating methods. Default: false | +| idempotency_level | [MethodOptions.IdempotencyLevel](#google.protobuf.MethodOptions.IdempotencyLevel) | optional | Default: IDEMPOTENCY_UNKNOWN | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### OneofDescriptorProto +Describes a oneof. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | | +| options | [OneofOptions](#google.protobuf.OneofOptions) | optional | | + + + + + + + + +### OneofOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### ServiceDescriptorProto +Describes a service. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | optional | | +| method | [MethodDescriptorProto](#google.protobuf.MethodDescriptorProto) | repeated | | +| options | [ServiceOptions](#google.protobuf.ServiceOptions) | optional | | + + + + + + + + +### ServiceOptions + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| deprecated | [bool](#bool) | optional | Is this service deprecated? Depending on the target platform, this can emit Deprecated annotations for the service, or it will be completely ignored; in the very least, this is a formalization for deprecating services. Default: false | +| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | + + + + + + + + +### SourceCodeInfo +Encapsulates information about the original source file from which a +FileDescriptorProto was generated. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| location | [SourceCodeInfo.Location](#google.protobuf.SourceCodeInfo.Location) | repeated | A Location identifies a piece of source code in a .proto file which corresponds to a particular definition. This information is intended to be useful to IDEs, code indexers, documentation generators, and similar tools. + +For example, say we have a file like: message Foo { optional string foo = 1; } Let's look at just the field definition: optional string foo = 1; ^ ^^ ^^ ^ ^^^ a bc de f ghi We have the following locations: span path represents [a,i) [ 4, 0, 2, 0 ] The whole field definition. [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). [c,d) [ 4, 0, 2, 0, 5 ] The type (string). [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). [g,h) [ 4, 0, 2, 0, 3 ] The number (1). + +Notes: - A location may refer to a repeated field itself (i.e. not to any particular index within it). This is used whenever a set of elements are logically enclosed in a single code segment. For example, an entire extend block (possibly containing multiple extension definitions) will have an outer location whose path refers to the "extensions" repeated field without an index. - Multiple locations may have the same path. This happens when a single logical declaration is spread out across multiple places. The most obvious example is the "extend" block again -- there may be multiple extend blocks in the same scope, each of which will have the same path. - A location's span is not always a subset of its parent's span. For example, the "extendee" of an extension declaration appears at the beginning of the "extend" block and is shared by all extensions within the block. - Just because a location's span is a subset of some other location's span does not mean that it is a descendent. For example, a "group" defines both a type and a field in a single declaration. Thus, the locations corresponding to the type and field and their components will overlap. - Code which tries to interpret locations should probably be designed to ignore those that it doesn't understand, as more types of locations could be recorded in the future. | + + + + + + + + +### SourceCodeInfo.Location + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| path | [int32](#int32) | repeated | Identifies which part of the FileDescriptorProto was defined at this location. + +Each element is a field number or an index. They form a path from the root FileDescriptorProto to the place where the definition. For example, this path: [ 4, 3, 2, 7, 1 ] refers to: file.message_type(3) // 4, 3 .field(7) // 2, 7 .name() // 1 This is because FileDescriptorProto.message_type has field number 4: repeated DescriptorProto message_type = 4; and DescriptorProto.field has field number 2: repeated FieldDescriptorProto field = 2; and FieldDescriptorProto.name has field number 1: optional string name = 1; + +Thus, the above path gives the location of a field name. If we removed the last element: [ 4, 3, 2, 7 ] this path refers to the whole field declaration (from the beginning of the label to the terminating semicolon). | +| span | [int32](#int32) | repeated | Always has exactly three or four elements: start line, start column, end line (optional, otherwise assumed same as start line), end column. These are packed into a single field for efficiency. Note that line and column numbers are zero-based -- typically you will want to add 1 to each before displaying to a user. | +| leading_comments | [string](#string) | optional | If this SourceCodeInfo represents a complete declaration, these are any comments appearing before and after the declaration which appear to be attached to the declaration. + +A series of line comments appearing on consecutive lines, with no other tokens appearing on those lines, will be treated as a single comment. + +leading_detached_comments will keep paragraphs of comments that appear before (but not connected to) the current element. Each paragraph, separated by empty lines, will be one comment element in the repeated field. + +Only the comment content is provided; comment markers (e.g. //) are stripped out. For block comments, leading whitespace and an asterisk will be stripped from the beginning of each line other than the first. Newlines are included in the output. + +Examples: + + optional int32 foo = 1; // Comment attached to foo. // Comment attached to bar. optional int32 bar = 2; + + optional string baz = 3; // Comment attached to baz. // Another line attached to baz. + + // Comment attached to qux. // // Another line attached to qux. optional double qux = 4; + + // Detached comment for corge. This is not leading or trailing comments // to qux or corge because there are blank lines separating it from // both. + + // Detached comment for corge paragraph 2. + + optional string corge = 5; /* Block comment attached * to corge. Leading asterisks * will be removed. */ /* Block comment attached to * grault. */ optional int32 grault = 6; + + // ignored detached comments. | +| trailing_comments | [string](#string) | optional | | +| leading_detached_comments | [string](#string) | repeated | | + + + + + + + + +### UninterpretedOption +A message representing a option the parser does not recognize. This only +appears in options protos created by the compiler::Parser class. +DescriptorPool resolves these when building Descriptor objects. Therefore, +options protos in descriptor objects (e.g. returned by Descriptor::options(), +or produced by Descriptor::CopyTo()) will never have UninterpretedOptions +in them. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [UninterpretedOption.NamePart](#google.protobuf.UninterpretedOption.NamePart) | repeated | | +| identifier_value | [string](#string) | optional | The value of the uninterpreted option, in whatever type the tokenizer identified it as during parsing. Exactly one of these should be set. | +| positive_int_value | [uint64](#uint64) | optional | | +| negative_int_value | [int64](#int64) | optional | | +| double_value | [double](#double) | optional | | +| string_value | [bytes](#bytes) | optional | | +| aggregate_value | [string](#string) | optional | | + + + + + + + + +### UninterpretedOption.NamePart +The name of the uninterpreted option. Each string represents a segment in +a dot-separated name. is_extension is true iff a segment represents an +extension (denoted with parentheses in options specs in .proto files). +E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents +"foo.(bar.baz).qux". + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name_part | [string](#string) | required | | +| is_extension | [bool](#bool) | required | | + + + + + + + + + + +### FieldDescriptorProto.Label + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| LABEL_OPTIONAL | 1 | 0 is reserved for errors | +| LABEL_REQUIRED | 2 | | +| LABEL_REPEATED | 3 | | + + + + + +### FieldDescriptorProto.Type + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| TYPE_DOUBLE | 1 | 0 is reserved for errors. Order is weird for historical reasons. | +| TYPE_FLOAT | 2 | | +| TYPE_INT64 | 3 | Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if negative values are likely. | +| TYPE_UINT64 | 4 | | +| TYPE_INT32 | 5 | Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if negative values are likely. | +| TYPE_FIXED64 | 6 | | +| TYPE_FIXED32 | 7 | | +| TYPE_BOOL | 8 | | +| TYPE_STRING | 9 | | +| TYPE_GROUP | 10 | Tag-delimited aggregate. Group type is deprecated and not supported in proto3. However, Proto3 implementations should still be able to parse the group wire format and treat group fields as unknown fields. | +| TYPE_MESSAGE | 11 | Length-delimited aggregate. | +| TYPE_BYTES | 12 | New in version 2. | +| TYPE_UINT32 | 13 | | +| TYPE_ENUM | 14 | | +| TYPE_SFIXED32 | 15 | | +| TYPE_SFIXED64 | 16 | | +| TYPE_SINT32 | 17 | Uses ZigZag encoding. | +| TYPE_SINT64 | 18 | Uses ZigZag encoding. | + + + + + +### FieldOptions.CType + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| STRING | 0 | Default mode. | +| CORD | 1 | | +| STRING_PIECE | 2 | | + + + + + +### FieldOptions.JSType + + +| Name | Number | Description | +| ---- | ------ | ----------- | +| JS_NORMAL | 0 | Use the default type. | +| JS_STRING | 1 | Use JavaScript strings. | +| JS_NUMBER | 2 | Use JavaScript numbers. | + + + + + +### FileOptions.OptimizeMode +Generated classes can be optimized for speed or code size. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| SPEED | 1 | Generate complete code for parsing, serialization, | +| CODE_SIZE | 2 | etc. + +Use ReflectionOps to implement these methods. | +| LITE_RUNTIME | 3 | Generate code using MessageLite and the lite runtime. | + + + + + +### MethodOptions.IdempotencyLevel +Is this method side-effect-free (or safe in HTTP parlance), or idempotent, +or neither? HTTP based RPC implementation may choose GET verb for safe +methods, and PUT verb for idempotent methods instead of the default POST. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| IDEMPOTENCY_UNKNOWN | 0 | | +| NO_SIDE_EFFECTS | 1 | implies idempotent | +| IDEMPOTENT | 2 | idempotent, but may have side effects | + + + + + + + + + + + +

    Top

    + +## google/protobuf/duration.proto + + + + + +### Duration +A Duration represents a signed, fixed-length span of time represented +as a count of seconds and fractions of seconds at nanosecond +resolution. It is independent of any calendar and concepts like "day" +or "month". It is related to Timestamp in that the difference between +two Timestamp values is a Duration and it can be added or subtracted +from a Timestamp. Range is approximately +-10,000 years. + +# Examples + +Example 1: Compute Duration from two Timestamps in pseudo code. + + Timestamp start = ...; + Timestamp end = ...; + Duration duration = ...; + + duration.seconds = end.seconds - start.seconds; + duration.nanos = end.nanos - start.nanos; + + if (duration.seconds < 0 && duration.nanos > 0) { + duration.seconds += 1; + duration.nanos -= 1000000000; + } else if (durations.seconds > 0 && duration.nanos < 0) { + duration.seconds -= 1; + duration.nanos += 1000000000; + } + +Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. + + Timestamp start = ...; + Duration duration = ...; + Timestamp end = ...; + + end.seconds = start.seconds + duration.seconds; + end.nanos = start.nanos + duration.nanos; + + if (end.nanos < 0) { + end.seconds -= 1; + end.nanos += 1000000000; + } else if (end.nanos >= 1000000000) { + end.seconds += 1; + end.nanos -= 1000000000; + } + +Example 3: Compute Duration from datetime.timedelta in Python. + + td = datetime.timedelta(days=3, minutes=10) + duration = Duration() + duration.FromTimedelta(td) + +# JSON Mapping + +In JSON format, the Duration type is encoded as a string rather than an +object, where the string ends in the suffix "s" (indicating seconds) and +is preceded by the number of seconds, with nanoseconds expressed as +fractional seconds. For example, 3 seconds with 0 nanoseconds should be +encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should +be expressed in JSON format as "3.000000001s", and 3 seconds and 1 +microsecond should be expressed in JSON format as "3.000001s". + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| seconds | [int64](#int64) | | Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years | +| nanos | [int32](#int32) | | Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 `seconds` field and a positive or negative `nanos` field. For durations of one second or more, a non-zero value for the `nanos` field must be of the same sign as the `seconds` field. Must be from -999,999,999 to +999,999,999 inclusive. | + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/empty.proto + + + + + +### Empty +A generic empty message that you can re-use to avoid defining duplicated +empty messages in your APIs. A typical example is to use it as the request +or the response type of an API method. For instance: + + service Foo { + rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); + } + +The JSON representation for `Empty` is empty JSON object `{}`. + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/field_mask.proto + + + + + +### FieldMask +`FieldMask` represents a set of symbolic field paths, for example: + + paths: "f.a" + paths: "f.b.d" + +Here `f` represents a field in some root message, `a` and `b` +fields in the message found in `f`, and `d` a field found in the +message in `f.b`. + +Field masks are used to specify a subset of fields that should be +returned by a get operation or modified by an update operation. +Field masks also have a custom JSON encoding (see below). + +# Field Masks in Projections + +When used in the context of a projection, a response message or +sub-message is filtered by the API to only contain those fields as +specified in the mask. For example, if the mask in the previous +example is applied to a response message as follows: + + f { + a : 22 + b { + d : 1 + x : 2 + } + y : 13 + } + z: 8 + +The result will not contain specific values for fields x,y and z +(their value will be set to the default, and omitted in proto text +output): + + + f { + a : 22 + b { + d : 1 + } + } + +A repeated field is not allowed except at the last position of a +paths string. + +If a FieldMask object is not present in a get operation, the +operation applies to all fields (as if a FieldMask of all fields +had been specified). + +Note that a field mask does not necessarily apply to the +top-level response message. In case of a REST get operation, the +field mask applies directly to the response, but in case of a REST +list operation, the mask instead applies to each individual message +in the returned resource list. In case of a REST custom method, +other definitions may be used. Where the mask applies will be +clearly documented together with its declaration in the API. In +any case, the effect on the returned resource/resources is required +behavior for APIs. + +# Field Masks in Update Operations + +A field mask in update operations specifies which fields of the +targeted resource are going to be updated. The API is required +to only change the values of the fields as specified in the mask +and leave the others untouched. If a resource is passed in to +describe the updated values, the API ignores the values of all +fields not covered by the mask. + +If a repeated field is specified for an update operation, the existing +repeated values in the target resource will be overwritten by the new values. +Note that a repeated field is only allowed in the last position of a `paths` +string. + +If a sub-message is specified in the last position of the field mask for an +update operation, then the existing sub-message in the target resource is +overwritten. Given the target message: + + f { + b { + d : 1 + x : 2 + } + c : 1 + } + +And an update message: + + f { + b { + d : 10 + } + } + +then if the field mask is: + + paths: "f.b" + +then the result will be: + + f { + b { + d : 10 + } + c : 1 + } + +However, if the update mask was: + + paths: "f.b.d" + +then the result would be: + + f { + b { + d : 10 + x : 2 + } + c : 1 + } + +In order to reset a field's value to the default, the field must +be in the mask and set to the default value in the provided resource. +Hence, in order to reset all fields of a resource, provide a default +instance of the resource and set all fields in the mask, or do +not provide a mask as described below. + +If a field mask is not present on update, the operation applies to +all fields (as if a field mask of all fields has been specified). +Note that in the presence of schema evolution, this may mean that +fields the client does not know and has therefore not filled into +the request will be reset to their default. If this is unwanted +behavior, a specific service may require a client to always specify +a field mask, producing an error if not. + +As with get operations, the location of the resource which +describes the updated values in the request message depends on the +operation kind. In any case, the effect of the field mask is +required to be honored by the API. + +## Considerations for HTTP REST + +The HTTP kind of an update operation which uses a field mask must +be set to PATCH instead of PUT in order to satisfy HTTP semantics +(PUT must only be used for full updates). + +# JSON Encoding of Field Masks + +In JSON, a field mask is encoded as a single string where paths are +separated by a comma. Fields name in each path are converted +to/from lower-camel naming conventions. + +As an example, consider the following message declarations: + + message Profile { + User user = 1; + Photo photo = 2; + } + message User { + string display_name = 1; + string address = 2; + } + +In proto a field mask for `Profile` may look as such: + + mask { + paths: "user.display_name" + paths: "photo" + } + +In JSON, the same mask is represented as below: + + { + mask: "user.displayName,photo" + } + +# Field Masks and Oneof Fields + +Field masks treat fields in oneofs just as regular fields. Consider the +following message: + + message SampleMessage { + oneof test_oneof { + string name = 4; + SubMessage sub_message = 9; + } + } + +The field mask can be: + + mask { + paths: "name" + } + +Or: + + mask { + paths: "sub_message" + } + +Note that oneof type names ("test_oneof" in this case) cannot be used in +paths. + +## Field Mask Verification + +The implementation of any API method which has a FieldMask type field in the +request should verify the included field paths, and return an +`INVALID_ARGUMENT` error if any path is duplicated or unmappable. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| paths | [string](#string) | repeated | The set of field mask paths. | + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/source_context.proto + + + + + +### SourceContext +`SourceContext` represents information about the source of a +protobuf element, like the file in which it is defined. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| file_name | [string](#string) | | The path-qualified name of the .proto file that contained the associated protobuf element. For example: `"google/protobuf/source_context.proto"`. | + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/struct.proto + + + + + +### ListValue +`ListValue` is a wrapper around a repeated field of values. + +The JSON representation for `ListValue` is JSON array. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| values | [Value](#google.protobuf.Value) | repeated | Repeated field of dynamically typed values. | + + + + + + + + +### Struct +`Struct` represents a structured data value, consisting of fields +which map to dynamically typed values. In some languages, `Struct` +might be supported by a native representation. For example, in +scripting languages like JS a struct is represented as an +object. The details of that representation are described together +with the proto support for the language. + +The JSON representation for `Struct` is JSON object. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| fields | [Struct.FieldsEntry](#google.protobuf.Struct.FieldsEntry) | repeated | Unordered map of dynamically typed values. | + + + + + + + + +### Struct.FieldsEntry + + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| key | [string](#string) | | | +| value | [Value](#google.protobuf.Value) | | | + + + + + + + + +### Value +`Value` represents a dynamically typed value which can be either +null, a number, a string, a boolean, a recursive struct value, or a +list of values. A producer of value is expected to set one of that +variants, absence of any variant indicates an error. + +The JSON representation for `Value` is JSON value. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| null_value | [NullValue](#google.protobuf.NullValue) | | Represents a null value. | +| number_value | [double](#double) | | Represents a double value. | +| string_value | [string](#string) | | Represents a string value. | +| bool_value | [bool](#bool) | | Represents a boolean value. | +| struct_value | [Struct](#google.protobuf.Struct) | | Represents a structured value. | +| list_value | [ListValue](#google.protobuf.ListValue) | | Represents a repeated `Value`. | + + + + + + + + + + +### NullValue +`NullValue` is a singleton enumeration to represent the null value for the +`Value` type union. + + The JSON representation for `NullValue` is JSON `null`. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| NULL_VALUE | 0 | Null value. | + + + + + + + + + + + +

    Top

    + +## google/protobuf/timestamp.proto + + + + + +### Timestamp +A Timestamp represents a point in time independent of any time zone +or calendar, represented as seconds and fractions of seconds at +nanosecond resolution in UTC Epoch time. It is encoded using the +Proleptic Gregorian Calendar which extends the Gregorian calendar +backwards to year one. It is encoded assuming all minutes are 60 +seconds long, i.e. leap seconds are "smeared" so that no leap second +table is needed for interpretation. Range is from +0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. +By restricting to that range, we ensure that we can convert to +and from RFC 3339 date strings. +See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). + +# Examples + +Example 1: Compute Timestamp from POSIX `time()`. + + Timestamp timestamp; + timestamp.set_seconds(time(NULL)); + timestamp.set_nanos(0); + +Example 2: Compute Timestamp from POSIX `gettimeofday()`. + + struct timeval tv; + gettimeofday(&tv, NULL); + + Timestamp timestamp; + timestamp.set_seconds(tv.tv_sec); + timestamp.set_nanos(tv.tv_usec * 1000); + +Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. + + FILETIME ft; + GetSystemTimeAsFileTime(&ft); + UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; + + // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z + // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. + Timestamp timestamp; + timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); + timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); + +Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. + + long millis = System.currentTimeMillis(); + + Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) + .setNanos((int) ((millis % 1000) * 1000000)).build(); + + +Example 5: Compute Timestamp from current time in Python. + + timestamp = Timestamp() + timestamp.GetCurrentTime() + +# JSON Mapping + +In JSON format, the Timestamp type is encoded as a string in the +[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the +format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" +where {year} is always expressed using four digits while {month}, {day}, +{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional +seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), +are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone +is required. A proto3 JSON serializer should always use UTC (as indicated by +"Z") when printing the Timestamp type and a proto3 JSON parser should be +able to accept both UTC and other timezones (as indicated by an offset). + +For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past +01:30 UTC on January 15, 2017. + +In JavaScript, one can convert a Date object to this format using the +standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString] +method. In Python, a standard `datetime.datetime` object can be converted +to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) +with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one +can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( +http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime-- +) to obtain a formatter capable of generating timestamps in this format. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| seconds | [int64](#int64) | | Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | +| nanos | [int32](#int32) | | Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive. | + + + + + + + + + + + + + + + + +

    Top

    + +## google/protobuf/type.proto + + + + + +### Enum +Enum type definition. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | Enum type name. | +| enumvalue | [EnumValue](#google.protobuf.EnumValue) | repeated | Enum value definitions. | +| options | [Option](#google.protobuf.Option) | repeated | Protocol buffer options. | +| source_context | [SourceContext](#google.protobuf.SourceContext) | | The source context. | +| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax. | + + + + + + + + +### EnumValue +Enum value definition. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | Enum value name. | +| number | [int32](#int32) | | Enum value number. | +| options | [Option](#google.protobuf.Option) | repeated | Protocol buffer options. | + + + + + + + + +### Field +A single field of a message type. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| kind | [Field.Kind](#google.protobuf.Field.Kind) | | The field type. | +| cardinality | [Field.Cardinality](#google.protobuf.Field.Cardinality) | | The field cardinality. | +| number | [int32](#int32) | | The field number. | +| name | [string](#string) | | The field name. | +| type_url | [string](#string) | | The field type URL, without the scheme, for message or enumeration types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. | +| oneof_index | [int32](#int32) | | The index of the field type in `Type.oneofs`, for message or enumeration types. The first type has index 1; zero means the type is not in the list. | +| packed | [bool](#bool) | | Whether to use alternative packed wire representation. | +| options | [Option](#google.protobuf.Option) | repeated | The protocol buffer options. | +| json_name | [string](#string) | | The field JSON name. | +| default_value | [string](#string) | | The string value of the default value of this field. Proto2 syntax only. | + + + + + + + + +### Option +A protocol buffer option, which can be attached to a message, field, +enumeration, etc. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The option's name. For protobuf built-in options (options defined in descriptor.proto), this is the short name. For example, `"map_entry"`. For custom options, it should be the fully-qualified name. For example, `"google.api.http"`. | +| value | [Any](#google.protobuf.Any) | | The option's value packed in an Any message. If the value is a primitive, the corresponding wrapper type defined in google/protobuf/wrappers.proto should be used. If the value is an enum, it should be stored as an int32 value using the google.protobuf.Int32Value type. | + + + + + + + + +### Type +A protocol buffer message type. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| name | [string](#string) | | The fully qualified message name. | +| fields | [Field](#google.protobuf.Field) | repeated | The list of fields. | +| oneofs | [string](#string) | repeated | The list of types appearing in `oneof` definitions in this type. | +| options | [Option](#google.protobuf.Option) | repeated | The protocol buffer options. | +| source_context | [SourceContext](#google.protobuf.SourceContext) | | The source context. | +| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax. | + + + + + + + + + + +### Field.Cardinality +Whether a field is optional, required, or repeated. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| CARDINALITY_UNKNOWN | 0 | For fields with unknown cardinality. | +| CARDINALITY_OPTIONAL | 1 | For optional fields. | +| CARDINALITY_REQUIRED | 2 | For required fields. Proto2 syntax only. | +| CARDINALITY_REPEATED | 3 | For repeated fields. | + + + + + +### Field.Kind +Basic field types. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| TYPE_UNKNOWN | 0 | Field type unknown. | +| TYPE_DOUBLE | 1 | Field type double. | +| TYPE_FLOAT | 2 | Field type float. | +| TYPE_INT64 | 3 | Field type int64. | +| TYPE_UINT64 | 4 | Field type uint64. | +| TYPE_INT32 | 5 | Field type int32. | +| TYPE_FIXED64 | 6 | Field type fixed64. | +| TYPE_FIXED32 | 7 | Field type fixed32. | +| TYPE_BOOL | 8 | Field type bool. | +| TYPE_STRING | 9 | Field type string. | +| TYPE_GROUP | 10 | Field type group. Proto2 syntax only, and deprecated. | +| TYPE_MESSAGE | 11 | Field type message. | +| TYPE_BYTES | 12 | Field type bytes. | +| TYPE_UINT32 | 13 | Field type uint32. | +| TYPE_ENUM | 14 | Field type enum. | +| TYPE_SFIXED32 | 15 | Field type sfixed32. | +| TYPE_SFIXED64 | 16 | Field type sfixed64. | +| TYPE_SINT32 | 17 | Field type sint32. | +| TYPE_SINT64 | 18 | Field type sint64. | + + + + + +### Syntax +The syntax in which a protocol buffer element is defined. + +| Name | Number | Description | +| ---- | ------ | ----------- | +| SYNTAX_PROTO2 | 0 | Syntax `proto2`. | +| SYNTAX_PROTO3 | 1 | Syntax `proto3`. | + + + + + + + + + + + +

    Top

    + +## google/protobuf/wrappers.proto + + + + + +### BoolValue +Wrapper message for `bool`. + +The JSON representation for `BoolValue` is JSON `true` and `false`. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [bool](#bool) | | The bool value. | + + + + + + + + +### BytesValue +Wrapper message for `bytes`. + +The JSON representation for `BytesValue` is JSON string. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [bytes](#bytes) | | The bytes value. | + + + + + + + + +### DoubleValue +Wrapper message for `double`. + +The JSON representation for `DoubleValue` is JSON number. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [double](#double) | | The double value. | + + + + + + + + +### FloatValue +Wrapper message for `float`. + +The JSON representation for `FloatValue` is JSON number. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [float](#float) | | The float value. | + + + + + + + + +### Int32Value +Wrapper message for `int32`. + +The JSON representation for `Int32Value` is JSON number. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [int32](#int32) | | The int32 value. | + + + + + + + + +### Int64Value +Wrapper message for `int64`. + +The JSON representation for `Int64Value` is JSON string. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [int64](#int64) | | The int64 value. | + + + + + + + + +### StringValue +Wrapper message for `string`. + +The JSON representation for `StringValue` is JSON string. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [string](#string) | | The string value. | + + + + + + + + +### UInt32Value +Wrapper message for `uint32`. + +The JSON representation for `UInt32Value` is JSON number. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [uint32](#uint32) | | The uint32 value. | + + + + + + + + +### UInt64Value +Wrapper message for `uint64`. + +The JSON representation for `UInt64Value` is JSON string. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| value | [uint64](#uint64) | | The uint64 value. | + + + + + + + + + + + + @@ -44,6 +2202,7 @@ Message backing the root of a Kroto+ configuration file. | extendable_messages | [ExtenableMessagesGenOptions](#krotoplus.compiler.ExtenableMessagesGenOptions) | repeated | Configuration entries for the 'Extendable Messages' code generator. | | insertions | [InsertionsGenOptions](#krotoplus.compiler.InsertionsGenOptions) | repeated | Configuration entries for the 'Protoc Insertions' code generator. | | generator_scripts | [GeneratorScriptsGenOptions](#krotoplus.compiler.GeneratorScriptsGenOptions) | repeated | Configuration entries for the 'Generator Scripts' code generator. | +| grpc_coroutines | [GrpcCoroutinesGenOptions](#krotoplus.compiler.GrpcCoroutinesGenOptions) | repeated | Configuration entries for the 'Grpc Coroutines' code generator. | @@ -107,6 +2266,21 @@ Configuration used by the 'Generator Scripts' code generator. + + +### GrpcCoroutinesGenOptions +Configuration used by the 'gRPC Coroutines' code generator. + + +| Field | Type | Label | Description | +| ----- | ---- | ----- | ----------- | +| filter | [FileFilter](#krotoplus.compiler.FileFilter) | | Filter used for limiting the input files that are processed by the code generator The default filter will match true against all input files. | + + + + + + ### GrpcStubExtsGenOptions diff --git a/example-grpc-client-server/README.md b/example-grpc-client-server/README.md new file mode 100644 index 0000000..cb0720a --- /dev/null +++ b/example-grpc-client-server/README.md @@ -0,0 +1,119 @@ +## Kotlin Coroutines gRPC Example + + +## Quick Start: +Run the following command to get started with a preconfigured template project. (_[kotlin-coroutines-gRPC-template](https://github.com/marcoferrer/kotlin-coroutines-gRPC-template)_) +```bash +git clone https://github.com/marcoferrer/kotlin-coroutines-gRPC-template && \ +cd kotlin-coroutines-gRPC-template && \ +./gradlew run +``` + +### Getting Started: Kroto+ Plugin +_[Template](https://github.com/marcoferrer/kotlin-coroutines-gRPC-template/tree/kroto-plus-template)_ +Add the following configuration to your existing Kroto configuration file. + +#### Asciipb (Proto Plain Text) +```asciipb +grpc_coroutines {} +``` +#### JSON +```json +{ + "grpcCoroutines": [] +} +``` + + +### Getting Started: Stand Alone Plugin +If you are not using any additional features from Kroto-Plus, then configuration can be simplified and use the stand alone version of the ```grpc-coroutines``` protoc plugin. + +#### Gradle Protobuf +_[Gradle Template](https://github.com/marcoferrer/kotlin-coroutines-gRPC-template)_ +```groovy +dependencies { + implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:$coroutines_version" + implementation "com.github.marcoferrer.krotoplus:kroto-plus-coroutines:$krotoplus_version" +} + +protobuf { + protoc { + artifact = "com.google.protobuf:protoc:$protobuf_version" + } + + plugins { + grpc { artifact = "io.grpc:protoc-gen-grpc-java:$grpc_version" } + coroutines { + artifact = "com.github.marcoferrer.krotoplus:protoc-gen-grpc-coroutines:$krotoplus_version:jvm8@jar" + } + } + + generateProtoTasks { + all().each { task -> + task.plugins { + grpc {} + coroutines {} + } + } + } +} +``` +#### Maven +```xml + + org.xolstice.maven.plugins + protobuf-maven-plugin + 0.6.1 + + com.google.protobuf:protoc:3.6.1:exe:${os.detected.classifier} + + + + compile + + + grpc-java + compile-custom + + grpc-java + io.grpc:protoc-gen-grpc-java:1.17.1:exe:${os.detected.classifier} + + + + + grpc-coroutines + + compile-custom + + + grpc-coroutines + com.github.marcoferrer.krotoplus:protoc-gen-grpc-coroutines:0.2.2-RC1:jar:jvm8 + + + + + +``` +Add generated sources to Kotlin plugin +```xml + + kotlin-maven-plugin + org.jetbrains.kotlin + ${kotlin.version} + + + compile + + compile + + + + ${project.basedir}/target/generated-sources/protobuf/grpc-java + ${project.basedir}/target/generated-sources/protobuf/grpc-coroutines + + + + + +``` +``` \ No newline at end of file diff --git a/example-project/build.gradle b/example-project/build.gradle index 8cec9d3..ed58aa2 100644 --- a/example-project/build.gradle +++ b/example-project/build.gradle @@ -3,8 +3,8 @@ buildscript { versions = [ "protobuf": '3.6.1', "grpc": '1.15.1', - "kotlin": '1.3.0', - "coroutines": '1.0.0', + "kotlin": '1.3.11', + "coroutines": '1.1.0', "krotoplus": '0.2.2-SNAPSHOT' ] } @@ -18,8 +18,8 @@ buildscript { plugins{ id 'idea' - id 'com.google.protobuf' version '0.8.6' - id "org.jetbrains.kotlin.jvm" version "1.3.0" + id 'com.google.protobuf' version '0.8.7' + id "org.jetbrains.kotlin.jvm" version "1.3.11" } group = 'com.github.marcoferrer.krotoplus' @@ -63,7 +63,8 @@ dependencies { implementation "com.github.marcoferrer.krotoplus:kroto-plus-message:${versions.krotoplus}" implementation "io.grpc:grpc-protobuf:${versions.grpc}", - "io.grpc:grpc-stub:${versions.grpc}" + "io.grpc:grpc-stub:${versions.grpc}", + "io.grpc:grpc-netty:${versions.grpc}" testImplementation "io.grpc:grpc-testing:${versions.grpc}" diff --git a/example-project/krotoPlusConfig.asciipb b/example-project/krotoPlusConfig.asciipb index e180b92..6dfe77b 100644 --- a/example-project/krotoPlusConfig.asciipb +++ b/example-project/krotoPlusConfig.asciipb @@ -18,6 +18,9 @@ proto_builders { } grpc_stub_exts { support_coroutines: true +} +grpc_coroutines { + } extendable_messages { filter { include_path: "jojo/bizarre/adventure/stand/*" } diff --git a/example-project/src/main/kotlin/krotoplus/example/DummyServices.kt b/example-project/src/main/kotlin/krotoplus/example/DummyServices.kt index b74663b..ef09d50 100644 --- a/example-project/src/main/kotlin/krotoplus/example/DummyServices.kt +++ b/example-project/src/main/kotlin/krotoplus/example/DummyServices.kt @@ -5,10 +5,14 @@ import io.grpc.Status import io.grpc.stub.StreamObserver import jojo.bizarre.adventure.character.CharacterProto import jojo.bizarre.adventure.stand.StandProto -import jojo.bizarre.adventure.stand.StandServiceGrpc +import jojo.bizarre.adventure.stand.StandServiceCoroutineGrpc import jojo.bizarre.adventure.stand.StandServiceProto +import kotlinx.coroutines.channels.ReceiveChannel +import kotlinx.coroutines.channels.SendChannel +import kotlinx.coroutines.channels.consumeEach +import kotlinx.coroutines.coroutineScope -class DummyStandService : StandServiceGrpc.StandServiceImplBase() { +class DummyStandService : StandServiceCoroutineGrpc.StandServiceImplBase() { fun getStandByName(name: String): StandProto.Stand? = when (name) { @@ -17,76 +21,46 @@ class DummyStandService : StandServiceGrpc.StandServiceImplBase() { else -> null } - - override fun getStandByCharacterName( - request: StandServiceProto.GetStandByCharacterNameRequest, - responseObserver: StreamObserver - ) { + override suspend fun getStandByCharacterName( + request: StandServiceProto.GetStandByCharacterNameRequest + ): StandProto.Stand = coroutineScope { getStandByName(request.name) - ?.let { responseObserver.onNext(it) } - ?: run { - responseObserver.onError(Status.NOT_FOUND.asException()) - return - } - - responseObserver.onCompleted() + ?: throw Status.NOT_FOUND.asException() } - override fun getStandByCharacter( - request: CharacterProto.Character, - responseObserver: StreamObserver - ) { - getStandByName(request.name) - ?.let { responseObserver.onNext(it) } - ?: run { - responseObserver.onError(Status.NOT_FOUND.asException()) - return - } - - responseObserver.onCompleted() + override suspend fun getStandByCharacter(request: CharacterProto.Character): StandProto.Stand = coroutineScope { + getStandByName(request.name) ?: throw Status.NOT_FOUND.asException() } - override fun getStandsForCharacters(responseObserver: StreamObserver): StreamObserver { + override suspend fun getStandsForCharacters( + requestChannel: ReceiveChannel, + responseChannel: SendChannel + ) { + coroutineScope { + requestChannel.consumeEach { character -> - return object : StreamObserver { - override fun onNext(value: CharacterProto.Character) { - println("Client Sent: ${value.name}") - getStandByName(value.name)?.let { - responseObserver.onNext(it) - responseObserver.onNext(it) - responseObserver.onNext(it) - } - ?: run { - responseObserver.onError(Status.NOT_FOUND.asException()) - return + getStandByName(character.name) + ?.let { stand -> + repeat(3) { + responseChannel.send(stand) + } } + ?: throw Status.NOT_FOUND.asException() } + } + } - override fun onError(t: Throwable?) { - println("Client Sent Error: ${t?.message}") - } - - override fun onCompleted() { - println("Client Called onComplete") - responseObserver.onCompleted() + override suspend fun getAllStandsStream(request: Empty, responseChannel: SendChannel) { + coroutineScope { + stands.values.forEach { + responseChannel.send(it) } } } - override fun getAllStandsStream(request: Empty?, responseObserver: StreamObserver) { - for ((_, stand) in stands) - responseObserver.onNext(stand) - - responseObserver.onCompleted() - } + override suspend fun getStandByName(request: StandServiceProto.GetStandByNameRequest): StandProto.Stand = + coroutineScope { + stands[request.name] ?: throw Status.NOT_FOUND.asException() + } - override fun getStandByName( - request: StandServiceProto.GetStandByNameRequest, - responseObserver: StreamObserver - ) { - stands[request.name]?.let { - responseObserver.onNext(it) - responseObserver.onCompleted() - } ?: responseObserver.onError(Status.NOT_FOUND.asException()) - } } \ No newline at end of file diff --git a/example-project/src/main/kotlin/krotoplus/example/Entities.kt b/example-project/src/main/kotlin/krotoplus/example/Entities.kt index 26e18bc..ecb0ca7 100644 --- a/example-project/src/main/kotlin/krotoplus/example/Entities.kt +++ b/example-project/src/main/kotlin/krotoplus/example/Entities.kt @@ -29,6 +29,11 @@ val attacks: Map = name = "EMERALD SPLASH" damage = 70 range = StandProto.Attack.Range.MEDIUM + }, + Attack { + name = "Gold Experience" + damage = 150 + range = StandProto.Attack.Range.CLOSE } ).associateBy { it.name } diff --git a/example-project/src/main/kotlin/krotoplus/example/StandService.kt b/example-project/src/main/kotlin/krotoplus/example/StandService.kt new file mode 100644 index 0000000..07cea8e --- /dev/null +++ b/example-project/src/main/kotlin/krotoplus/example/StandService.kt @@ -0,0 +1,60 @@ +package krotoplus.example + +import io.grpc.Status +import jojo.bizarre.adventure.character.CharacterProto +import jojo.bizarre.adventure.stand.* +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.* + +class StandService : StandServiceCoroutineGrpc.StandServiceImplBase(){ + + override suspend fun getStandByName( + request: StandServiceProto.GetStandByNameRequest + ): StandProto.Stand = coroutineScope { + val asyncAttack = async { + Attack { + name = "Life Shot" + damage = 120 + range = StandProto.Attack.Range.CLOSE + } + } + + if(request.name == "Gold Experience"){ + Stand { + name = "Gold Experience" + powerLevel = 575 + speed = 500 + addAttacks(asyncAttack.await()) + } + }else{ + throw Status.NOT_FOUND.asException() + } + } + + @ExperimentalCoroutinesApi + override suspend fun getStandsForCharacters( + requestChannel: ReceiveChannel, + responseChannel: SendChannel + ) { + coroutineScope { + + val requestIter = requestChannel.iterator() + + while (requestIter.hasNext()){ + + val requestValues = listOf( + requestIter.next(), + requestIter.next(), + requestIter.next() + ) + + responseChannel.send { + name = requestValues.joinToString() + } + } + + println("Server Finished") + } + } + +} \ No newline at end of file diff --git a/example-project/src/test/kotlin/krotoplus/example/TestSomeRandomClass.kt b/example-project/src/test/kotlin/krotoplus/example/TestSomeRandomClass.kt index d71be89..89a0c70 100644 --- a/example-project/src/test/kotlin/krotoplus/example/TestSomeRandomClass.kt +++ b/example-project/src/test/kotlin/krotoplus/example/TestSomeRandomClass.kt @@ -12,7 +12,7 @@ import jojo.bizarre.adventure.stand.MockStandService import jojo.bizarre.adventure.stand.StandProto import jojo.bizarre.adventure.stand.addAttacks import jojo.bizarre.adventure.stand.addMessage -import kotlinx.coroutines.runBlocking +import kotlinx.coroutines.* import org.junit.Rule import org.junit.Test import kotlin.test.BeforeTest diff --git a/example-project/src/test/kotlin/krotoplus/example/TestStandService.kt b/example-project/src/test/kotlin/krotoplus/example/TestStandService.kt new file mode 100644 index 0000000..44c4ab1 --- /dev/null +++ b/example-project/src/test/kotlin/krotoplus/example/TestStandService.kt @@ -0,0 +1,86 @@ +package krotoplus.example + +import com.github.marcoferrer.krotoplus.coroutines.* +import io.grpc.* +import io.grpc.testing.GrpcServerRule +import jojo.bizarre.adventure.stand.* +import org.junit.Rule +import org.junit.Test +import kotlin.test.assertEquals +import kotlin.test.BeforeTest +import kotlin.test.assertNotNull +import kotlin.test.fail +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.consumeEachIndexed + + +class TestStandService { + + @[Rule JvmField] + var grpcServerRule = GrpcServerRule().directExecutor() + + @BeforeTest + fun bindService() { + grpcServerRule.serviceRegistry?.addService(StandService()) + } + + @Test + fun `Test Unary Service Response`() = runBlocking { + val standStub = StandServiceGrpc.newStub(grpcServerRule.channel) + + standStub.getStandByName { name = "Gold Experience" }.let { response -> + + assertEquals("Gold Experience", response.name) + assertEquals(575, response.powerLevel) + assertEquals(500, response.speed) + response.attacksList.first().let { attack -> + assertEquals("Life Shot", attack.name) + assertEquals(120, attack.damage) + assertEquals(StandProto.Attack.Range.CLOSE, attack.range) + } + } + + try { + standStub.getStandByName { name = "Silver Chariot" } + fail("Exception was expected with status code: ${Status.NOT_FOUND.code}") + } catch (e: Throwable) { + val exception = e as? StatusRuntimeException + assertNotNull(exception) + assertEquals(Status.NOT_FOUND.code, exception.status.code) + } + } + + @Test + @ExperimentalCoroutinesApi + fun `Test Bidi Service Call`() { + runBlocking { + + val standStub = StandServiceCoroutineGrpc + .newStub(grpcServerRule.channel!!) + .withCoroutineContext() + + val (requestChannel, responseChannel) = standStub.getStandsForCharacters() + + launchProducerJob(requestChannel) { + repeat(300) { + val value = it + 1 + send { name = "test $value" } + println("-> Client Sent '$value'") + delay(2L) + } + } + + launch(Dispatchers.Default) { + var responseQty = 0 + + responseChannel.consumeEachIndexed { (index, response) -> + responseQty = index + println("<- Resp#: $index, Client Received '${response.toString().trim()}' ") + } + + assertEquals(99, responseQty) + } + } + } + +} \ No newline at end of file diff --git a/gradle.properties b/gradle.properties index e69de29..29e08e8 100644 --- a/gradle.properties +++ b/gradle.properties @@ -0,0 +1 @@ +kotlin.code.style=official \ No newline at end of file diff --git a/kroto-plus-coroutines/benchmark/README.md b/kroto-plus-coroutines/benchmark/README.md new file mode 100644 index 0000000..17eed6b --- /dev/null +++ b/kroto-plus-coroutines/benchmark/README.md @@ -0,0 +1 @@ +Benchmark Service Impl based on [grpc benchmark tools](https://github.com/grpc/grpc-java/tree/master/benchmarks) \ No newline at end of file diff --git a/kroto-plus-coroutines/benchmark/build.gradle b/kroto-plus-coroutines/benchmark/build.gradle new file mode 100644 index 0000000..0676cf2 --- /dev/null +++ b/kroto-plus-coroutines/benchmark/build.gradle @@ -0,0 +1,55 @@ +apply plugin: 'com.google.protobuf' +apply plugin: 'idea' +apply plugin: 'kotlin' + +compileKotlin { + kotlinOptions{ + jvmTarget = "1.8" + freeCompilerArgs += ["-Xuse-experimental=kotlin.Experimental"] + } +} + +dependencies { + implementation project(':kroto-plus-coroutines') + + implementation "org.jetbrains.kotlin:kotlin-stdlib-jdk8" + implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:${Versions.coroutines}" + + implementation "com.google.protobuf:protobuf-java:${Versions.protobuf}" + implementation "io.grpc:grpc-protobuf:${Versions.grpc}" + implementation "io.grpc:grpc-stub:${Versions.grpc}" + implementation "io.grpc:grpc-netty:${Versions.grpc}" + + implementation "io.grpc:grpc-benchmarks:${Versions.grpc}" + protobuf "io.grpc:grpc-benchmarks:${Versions.grpc}" +} + +compileJava.enabled = false + +protobuf { + protoc { artifact = "com.google.protobuf:protoc:${Versions.protobuf}"} + + //noinspection GroovyAssignabilityCheck + plugins { + kroto { + path = "${rootProject.projectDir}/protoc-gen-kroto-plus/build/libs/protoc-gen-kroto-plus-${project.version}-jvm8.jar" + } + } + + generateProtoTasks { + def krotoConfig = file("krotoPlusConfig.asciipb") + + all().each{ task -> + task.inputs.files krotoConfig + + task.builtins { + remove java + } + task.plugins { + kroto { + option "ConfigPath=$krotoConfig" + } + } + } + } +} diff --git a/kroto-plus-coroutines/benchmark/krotoPlusConfig.asciipb b/kroto-plus-coroutines/benchmark/krotoPlusConfig.asciipb new file mode 100644 index 0000000..ecb7d72 --- /dev/null +++ b/kroto-plus-coroutines/benchmark/krotoPlusConfig.asciipb @@ -0,0 +1,3 @@ +grpc_coroutines { + filter { exclude_path: "google/*" } +} diff --git a/kroto-plus-coroutines/benchmark/src/main/kotlin/BenchMarkService.kt b/kroto-plus-coroutines/benchmark/src/main/kotlin/BenchMarkService.kt new file mode 100644 index 0000000..7d3cdc4 --- /dev/null +++ b/kroto-plus-coroutines/benchmark/src/main/kotlin/BenchMarkService.kt @@ -0,0 +1,88 @@ +import com.google.protobuf.ByteString +import io.grpc.Status +import io.grpc.benchmarks.proto.BenchmarkServiceCoroutineGrpc +import io.grpc.benchmarks.proto.Messages +import kotlinx.coroutines.channels.* +import kotlinx.coroutines.coroutineScope + +class BenchMarkService : BenchmarkServiceCoroutineGrpc.BenchmarkServiceImplBase(){ + + private val BIDI_RESPONSE_BYTES = 100 + private val BIDI_RESPONSE = Messages.SimpleResponse + .newBuilder() + .setPayload( + Messages.Payload.newBuilder() + .setBody(ByteString.copyFrom(ByteArray(BIDI_RESPONSE_BYTES))).build() + ) + .build() + + override suspend fun unaryCall( + request: Messages.SimpleRequest + ): Messages.SimpleResponse = coroutineScope { + makeResponse(request) + } + + override suspend fun streamingCall( + requestChannel: ReceiveChannel, + responseChannel: SendChannel + ) { + coroutineScope { + requestChannel.mapTo(responseChannel){ makeResponse(it) } + } + } + + override suspend fun streamingFromClient( + requestChannel: ReceiveChannel + ): Messages.SimpleResponse = coroutineScope { + + val lastSeen = requestChannel + .toList() + .lastOrNull() + ?: throw Status.FAILED_PRECONDITION + .withDescription("never received any requests") + .asException() + + makeResponse(lastSeen) + } + + override suspend fun streamingFromServer( + request: Messages.SimpleRequest, + responseChannel: SendChannel + ) { + coroutineScope { + val response = makeResponse(request) + + while (!responseChannel.isClosedForSend) { + responseChannel.send(response) + } + } + } + + override suspend fun streamingBothWays( + requestChannel: ReceiveChannel, + responseChannel: SendChannel + ) { + coroutineScope { + while(!requestChannel.isClosedForReceive){ + responseChannel.send(BIDI_RESPONSE) + } + } + } +} + +// Copied from +// https://github.com/grpc/grpc-java/blob/847eae8d37af91ca2d9d4ebfff4d0ed4cd3f78bf/benchmarks/src/main/java/io/grpc/benchmarks/Utils.java#L249 +fun makeResponse(request: Messages.SimpleRequest): Messages.SimpleResponse { + if (request.responseSize > 0) { + if (Messages.PayloadType.COMPRESSABLE != request.responseType) { + throw Status.INTERNAL.augmentDescription("Error creating payload.").asRuntimeException() + } + + val body = ByteString.copyFrom(ByteArray(request.responseSize)) + val type = request.responseType + + val payload = Messages.Payload.newBuilder().setType(type).setBody(body).build() + return Messages.SimpleResponse.newBuilder().setPayload(payload).build() + } + return Messages.SimpleResponse.getDefaultInstance() +} \ No newline at end of file diff --git a/kroto-plus-coroutines/benchmark/src/main/kotlin/main.kt b/kroto-plus-coroutines/benchmark/src/main/kotlin/main.kt new file mode 100644 index 0000000..a6855f4 --- /dev/null +++ b/kroto-plus-coroutines/benchmark/src/main/kotlin/main.kt @@ -0,0 +1,36 @@ +import com.google.common.util.concurrent.UncaughtExceptionHandlers +import io.grpc.netty.NettyServerBuilder +import kotlinx.coroutines.Dispatchers + +import java.util.concurrent.* +import java.util.concurrent.ForkJoinPool.ForkJoinWorkerThreadFactory +import java.util.concurrent.ForkJoinPool.defaultForkJoinWorkerThreadFactory +import java.util.concurrent.atomic.AtomicInteger + +// TODO: add args to enabled direct executor +fun main(){ + +// ForkJoinPool.commonPool() +// Dispatchers.Default +// val fjpExecutor = ForkJoinPool( +// 4 /* parallelism*/, object : ForkJoinWorkerThreadFactory { +// +// private val num = AtomicInteger() +// override fun newThread(pool: ForkJoinPool): ForkJoinWorkerThread { +// val thread = defaultForkJoinWorkerThreadFactory.newThread(pool) +// thread.isDaemon = true +// thread.name = "grpc-server-app-" + "-" + num.getAndIncrement() +// return thread +// } +// }, UncaughtExceptionHandlers.systemExit(), true /* async */) + + val server = NettyServerBuilder + .forPort(8000) + .addService(BenchMarkService()) +// .executor(ForkJoinPool.commonPool()) + .directExecutor() + .build() + .apply { start() } + + server.awaitTermination() +} diff --git a/kroto-plus-coroutines/build.gradle b/kroto-plus-coroutines/build.gradle index 10abd7d..ec1edc7 100644 --- a/kroto-plus-coroutines/build.gradle +++ b/kroto-plus-coroutines/build.gradle @@ -1,15 +1,31 @@ -description = "Kroto+ Coroutine Support" +description = "Kroto+ Grpc Coroutine Support" apply from: "$rootDir/publishing.gradle" +def experimentalFlags = [ + "-Xuse-experimental=kotlin.Experimental", + "-Xuse-experimental=kotlinx.coroutines.ExperimentalCoroutinesApi", + "-Xuse-experimental=kotlinx.coroutines.ObsoleteCoroutinesApi" +] + compileKotlin { kotlinOptions { - freeCompilerArgs += ["-Xuse-experimental=kotlin.Experimental"] + // We're setting the jvm target to 1.6 to maintain + // compatibility with android runtime + jvmTarget = "1.6" + freeCompilerArgs += experimentalFlags + } +} +compileTestKotlin { + kotlinOptions { + jvmTarget = "1.8" + freeCompilerArgs += experimentalFlags } } dependencies { - implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:${versions.coroutines}" - implementation "io.grpc:grpc-protobuf:${versions.grpc}", - "io.grpc:grpc-stub:${versions.grpc}" + implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:${Versions.coroutines}" + implementation "io.grpc:grpc-protobuf:${Versions.grpc}", + "io.grpc:grpc-stub:${Versions.grpc}" + testImplementation "io.mockk:mockk:1.8.13.kotlin13" } \ No newline at end of file diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/Annotations.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/Annotations.kt index b739598..3dc13ba 100644 --- a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/Annotations.kt +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/Annotations.kt @@ -3,4 +3,7 @@ package com.github.marcoferrer.krotoplus.coroutines @Retention(value = AnnotationRetention.BINARY) @Experimental(level = Experimental.Level.WARNING) -public annotation class ExperimentalKrotoPlusCoroutinesApi \ No newline at end of file +public annotation class ExperimentalKrotoPlusCoroutinesApi + +@Retention(value = AnnotationRetention.SOURCE) +public annotation class KrotoPlusInternalApi \ No newline at end of file diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExts.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExts.kt new file mode 100644 index 0000000..2c2af7b --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExts.kt @@ -0,0 +1,110 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.MethodDescriptor +import io.grpc.Status +import io.grpc.StatusException +import io.grpc.StatusRuntimeException +import io.grpc.stub.ServerCallStreamObserver +import io.grpc.stub.StreamObserver +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.* +import java.util.concurrent.atomic.AtomicBoolean +import kotlin.coroutines.CoroutineContext +import kotlin.coroutines.EmptyCoroutineContext + +/** + * Launch a [Job] within a [ProducerScope] using the supplied channel as the Receiver. + * This is useful for emulating the behavior of [CoroutineScope.produce] using an existing + * channel. The supplied channel is then closed upon completion of the newly created Job. + * + * @param channel The channel that will be used as receiver of the [ProducerScope] + * @param context additional to [CoroutineScope.coroutineContext] context of the coroutine. + * @param block the coroutine code which will be invoked in the context of the [ProducerScope]. + * + * @return [Job] Returns a handle to the [Job] that is executing the [ProducerScope] block + */ +@ExperimentalCoroutinesApi +public suspend fun CoroutineScope.launchProducerJob( + channel: SendChannel, + context: CoroutineContext = EmptyCoroutineContext, + block: suspend ProducerScope.()->Unit +): Job = + launch(context) { newProducerScope(channel).block() } + .apply { invokeOnCompletion(channel.completionHandler) } + + +@ExperimentalCoroutinesApi +@ObsoleteCoroutinesApi +@KrotoPlusInternalApi +fun CoroutineScope.newSendChannelFromObserver( + observer: StreamObserver, + capacity: Int = 1 +): SendChannel = + CoroutineScope(coroutineContext + Dispatchers.Unconfined ) + .actor(capacity = capacity, start = CoroutineStart.LAZY) { + consumeEach { observer.onNext(it) } + } + .apply { invokeOnClose(observer.completionHandler) } + +@ObsoleteCoroutinesApi +@ExperimentalCoroutinesApi +internal fun CoroutineScope.newManagedServerResponseChannel( + responseObserver: ServerCallStreamObserver, + isMessagePreloaded: AtomicBoolean, + requestChannel: Channel = Channel() +): SendChannel { + + val responseChannel = newSendChannelFromObserver(responseObserver) + + responseObserver.apply { + enableManualFlowControl(requestChannel,isMessagePreloaded) + setOnCancelHandler { + responseChannel.close(Status.CANCELLED.asRuntimeException()) + } + } + + return responseChannel +} + +internal val StreamObserver<*>.completionHandler: CompletionHandler + get() = { + if(it != null) + onError(it.toRpcException()) else + onCompleted() + } + +internal val SendChannel<*>.completionHandler: CompletionHandler + get() = { + close(it?.toRpcException()) + } + +internal fun Throwable.toRpcException(): Throwable = + when (this) { + is StatusException, + is StatusRuntimeException -> this + else -> Status.fromThrowable(this).asRuntimeException( + Status.trailersFromThrowable(this) + ) + } + +internal fun MethodDescriptor<*, *>.getCoroutineName(): CoroutineName = + CoroutineName(fullMethodName) + +internal fun CoroutineScope.newRpcScope( + methodDescriptor: MethodDescriptor<*, *>, + grpcContext: io.grpc.Context = io.grpc.Context.current() +): CoroutineScope = CoroutineScope( + coroutineContext + + grpcContext.asContextElement() + + methodDescriptor.getCoroutineName() +) + +@ExperimentalCoroutinesApi +internal fun CoroutineScope.newProducerScope(channel: SendChannel): ProducerScope = + object : ProducerScope, + CoroutineScope by this, + SendChannel by channel { + + override val channel: SendChannel + get() = channel + } diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponse.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponse.kt new file mode 100644 index 0000000..811d9e1 --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponse.kt @@ -0,0 +1,59 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.stub.StreamObserver +import kotlinx.coroutines.CompletableDeferred + +class CompletableDeferredObserver internal constructor( + private val delegateObserver: StreamObserver, + private val delegateDeferred: CompletableDeferred = CompletableDeferred() +) : CompletableDeferred by delegateDeferred { + + override fun complete(value: RespT): Boolean = + delegateDeferred.complete(value).also { isCompleted -> + if(isCompleted){ + delegateObserver.onNext(value) + delegateObserver.onCompleted() + } + } + + override fun completeExceptionally(exception: Throwable): Boolean = + delegateDeferred.completeExceptionally(exception).also { isCompleted -> + if(isCompleted){ + delegateObserver.onError(exception) + } + } +} + + +fun CompletableDeferred.toStreamObserver(): StreamObserver = + object : StreamObserver { + + /** + * Since [CompletableDeferred] is a single value coroutine primitive, + * once [onNext] has been called we can be sure that we have completed + * our stream. + * + */ + override fun onNext(value: T) { + complete(value) + } + + override fun onError(t: Throwable) { + completeExceptionally(t) + } + + /** + * This method is intentionally left blank. + * + * Since this stream represents a single value, completion is marked by + * the first invocation of [onNext] + */ + override fun onCompleted() { + // NOOP + } + } + + +fun StreamObserver.toCompletableDeferred(): CompletableDeferredObserver = + CompletableDeferredObserver(delegateObserver = this) + diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CoroutineStub.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CoroutineStub.kt new file mode 100644 index 0000000..153c660 --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/CoroutineStub.kt @@ -0,0 +1,20 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.CallOptions +import io.grpc.stub.AbstractStub +import kotlin.coroutines.CoroutineContext + +val CALL_OPTION_COROUTINE_CONTEXT: CallOptions.Key = + CallOptions.Key.create("coroutineContext") + +val > T.coroutineContext: CoroutineContext? + get() = callOptions.getOption(CALL_OPTION_COROUTINE_CONTEXT) + +fun > T.withCoroutineContext(coroutineContext: CoroutineContext): T = + this.withOption(CALL_OPTION_COROUTINE_CONTEXT, coroutineContext) + +suspend fun > T.withCoroutineContext(): T = + this.withOption(CALL_OPTION_COROUTINE_CONTEXT, kotlin.coroutines.coroutineContext) + +fun CallOptions.withCoroutineContext(coroutineContext: CoroutineContext): CallOptions = + this.withOption(CALL_OPTION_COROUTINE_CONTEXT, coroutineContext) \ No newline at end of file diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControl.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControl.kt new file mode 100644 index 0000000..3457154 --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControl.kt @@ -0,0 +1,57 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.stub.CallStreamObserver +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.Channel +import java.util.concurrent.atomic.AtomicBoolean + +internal interface FlowControlledObserver { + + @ExperimentalCoroutinesApi + fun CoroutineScope.nextValueWithBackPressure( + value: T, + channel: Channel, + callStreamObserver: CallStreamObserver, + isMessagePreloaded: AtomicBoolean + ) { + try { + when { + !channel.isClosedForSend && channel.offer(value) -> callStreamObserver.request(1) + + !channel.isClosedForSend -> { + // We are setting isMessagePreloaded to true to prevent the + // onReadyHandler from requesting a new message while we have + // a message preloaded. + isMessagePreloaded.set(true) + launch { + channel.send(value) + callStreamObserver.request(1) + + // Allow the onReadyHandler to begin requesting messages again. + isMessagePreloaded.set(false) + } + } + } + } catch (e: Throwable) { + channel.close(e) + } + } +} + +@ExperimentalCoroutinesApi +internal fun CallStreamObserver.enableManualFlowControl( + targetChannel: Channel, + isMessagePreloaded: AtomicBoolean +) { + disableAutoInboundFlowControl() + setOnReadyHandler { + if ( + isReady && + !targetChannel.isFull && + !targetChannel.isClosedForSend && + isMessagePreloaded.compareAndSet(false, true) + ) { + request(1) + } + } +} diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/GrpcDispatcher.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/GrpcDispatcher.kt new file mode 100644 index 0000000..62ee6e4 --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/GrpcDispatcher.kt @@ -0,0 +1,52 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.ServerBuilder +import kotlinx.coroutines.CoroutineDispatcher +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.asCoroutineDispatcher +import java.util.concurrent.Executor +import kotlin.coroutines.CoroutineContext + +@ExperimentalKrotoPlusCoroutinesApi +public val Dispatchers.Grpc: CoroutineDispatcher + get() = GrpcDispatcherLoader.dispatcher + +@ExperimentalKrotoPlusCoroutinesApi +public fun > T.coroutineDispatcher(executor: Executor): T { + GrpcDispatcherLoader.initialize(executor.asCoroutineDispatcher()) + return this +} + +@ExperimentalKrotoPlusCoroutinesApi +public fun > T.coroutineDispatcher(dispatcher: CoroutineDispatcher): T { + GrpcDispatcherLoader.initialize(dispatcher) + return this +} + +@ExperimentalKrotoPlusCoroutinesApi +internal object GrpcDispatcherLoader { + + internal var dispatcher: CoroutineDispatcher = MissingGrpcCoroutineDispatcher + private set + + public val isInitialized: Boolean + get() = dispatcher != MissingGrpcCoroutineDispatcher + + public fun initialize(dispatcher: CoroutineDispatcher){ + require(!isInitialized){ + "Grpc dispatcher has already been initialized with an instance of ${dispatcher::class}" + } + this.dispatcher = dispatcher + } +} + +private object MissingGrpcCoroutineDispatcher : CoroutineDispatcher() { + + override fun dispatch(context: CoroutineContext, block: Runnable) = missing() + + private fun missing() { + throw IllegalStateException("Grpc coroutine dispatcher has not been initialized.") + } + + override fun toString(): String = "GrpcCoroutineDispatcher[missing]" +} \ No newline at end of file diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/InboundStreamChannel.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/InboundStreamChannel.kt index 4e0e916..d95d8da 100644 --- a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/InboundStreamChannel.kt +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/InboundStreamChannel.kt @@ -1,12 +1,12 @@ package com.github.marcoferrer.krotoplus.coroutines -import io.grpc.stub.StreamObserver -import kotlinx.coroutines.channels.Channel -import kotlinx.coroutines.channels.ReceiveChannel +import io.grpc.stub.* +import kotlinx.coroutines.channels.* +@Deprecated("Deprecated in favor of back-pressure supporting implementation. Use coroutine stub generator") class InboundStreamChannel( - capacity: Int = Channel.UNLIMITED, - private val channel: Channel = Channel(capacity) + capacity: Int = Channel.UNLIMITED, + val channel: Channel = Channel(capacity) ) : StreamObserver, ReceiveChannel by channel { override fun onNext(value: T) { diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/RpcBidiChannel.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/RpcBidiChannel.kt index eeb9486..a7b0d88 100644 --- a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/RpcBidiChannel.kt +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/RpcBidiChannel.kt @@ -1,5 +1,6 @@ package com.github.marcoferrer.krotoplus.coroutines +import com.github.marcoferrer.krotoplus.coroutines.client.ClientBidiCallChannel import kotlinx.coroutines.channels.ReceiveChannel import kotlinx.coroutines.channels.SendChannel @@ -10,14 +11,16 @@ import kotlinx.coroutines.channels.SendChannel ) typealias RpcBidiChannel = ClientBidiCallChannel -data class ClientBidiCallChannel( - val requestChannel: SendChannel, - val responseChannel: ReceiveChannel -) : SendChannel by requestChannel, - ReceiveChannel by responseChannel +@Deprecated( + "ClientBidiCallChannel has been moved", + ReplaceWith("com.github.marcoferrer.krotoplus.coroutines.client.ClientBidiCallChannel") +) +typealias ClientBidiCallChannel = com.github.marcoferrer.krotoplus.coroutines.client.ClientBidiCallChannel +@Deprecated("Deprecated in favor of using kroto generated base impl.") data class ServerBidiCallChannel( val requestChannel: ReceiveChannel, val responseChannel: SendChannel ) : SendChannel by responseChannel, - ReceiveChannel by requestChannel \ No newline at end of file + ReceiveChannel by requestChannel + diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt index bdad772..7842bf0 100644 --- a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/ServiceStubRpcBuilders.kt @@ -1,13 +1,10 @@ package com.github.marcoferrer.krotoplus.coroutines -import io.grpc.CallOptions -import kotlinx.coroutines.channels.actor +import com.github.marcoferrer.krotoplus.coroutines.client.ClientBidiCallChannel import io.grpc.stub.AbstractStub import io.grpc.stub.StreamObserver import kotlinx.coroutines.* -import kotlinx.coroutines.channels.SendChannel -import kotlinx.coroutines.channels.consumeEach -import kotlin.coroutines.CoroutineContext +import kotlin.coroutines.EmptyCoroutineContext suspend inline fun , reified R> T.suspendingUnaryCallObserver( @@ -29,47 +26,14 @@ inline fun , ReqT, RespT> T.bidiCallChannel( val responseObserverChannel = InboundStreamChannel() val requestObserver = block(responseObserverChannel) - val requestObserverChannel = requestObserver.toSendChannel(coroutineContext?.get(Job)) - return ClientBidiCallChannel(requestObserverChannel, responseObserverChannel) -} - - -/** - * Marked as [ObsoleteCoroutinesApi] due to usage of [CoroutineScope.actor] - * Marked as [ExperimentalCoroutinesApi] due to usage of [Dispatchers.Unconfined] - */ -@ExperimentalCoroutinesApi -@ObsoleteCoroutinesApi -fun StreamObserver.toSendChannel(parent: Job? = null): SendChannel { + val requestObserverChannel = CoroutineScope(coroutineContext ?: EmptyCoroutineContext) + .newSendChannelFromObserver(requestObserver) - val streamObserver = this@toSendChannel - val context = parent - ?.let { it + Dispatchers.Unconfined } ?: Dispatchers.Unconfined - - return GlobalScope.actor(context, start = CoroutineStart.LAZY) { - try { - channel.consumeEach { streamObserver.onNext(it) } - streamObserver.onCompleted() - } catch (e: Throwable) { - streamObserver.onError(e) - } - } + return ClientBidiCallChannel( + requestObserverChannel, + responseObserverChannel + ) } -@ExperimentalKrotoPlusCoroutinesApi -val CALL_OPTION_COROUTINE_CONTEXT: CallOptions.Key = - CallOptions.Key.create("coroutineContext") - -@ExperimentalKrotoPlusCoroutinesApi -val > T.coroutineContext: CoroutineContext? - get() = callOptions.getOption(CALL_OPTION_COROUTINE_CONTEXT) - -@ExperimentalKrotoPlusCoroutinesApi -fun > T.withCoroutineContext(coroutineContext: CoroutineContext): T = - this.withOption(CALL_OPTION_COROUTINE_CONTEXT, coroutineContext) - -@ExperimentalKrotoPlusCoroutinesApi -suspend fun > T.withCoroutineContext(): T = - this.withOption(CALL_OPTION_COROUTINE_CONTEXT, kotlin.coroutines.coroutineContext) diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientCalls.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientCalls.kt new file mode 100644 index 0000000..acce46d --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientCalls.kt @@ -0,0 +1,77 @@ +package com.github.marcoferrer.krotoplus.coroutines.client + +import com.github.marcoferrer.krotoplus.coroutines.* +import io.grpc.MethodDescriptor +import io.grpc.stub.AbstractStub +import io.grpc.stub.ClientCalls.* +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.ReceiveChannel + + +public suspend fun > T.clientCallUnary( + request: ReqT, + method: MethodDescriptor +): RespT = suspendCancellableCoroutine { cont: CancellableContinuation -> + asyncUnaryCall( + channel.newCall(method, callOptions), + request, + SuspendingUnaryObserver(cont) + ) +} + +public fun T.clientCallServerStreaming( + request: ReqT, + method: MethodDescriptor +): ReceiveChannel + where T : CoroutineScope, T : AbstractStub { + + val rpcScope = newRpcScope(method, io.grpc.Context.current()) + val rpcContext = rpcScope.coroutineContext + val responseObserverChannel = ClientResponseObserverChannel(rpcContext) + + asyncServerStreamingCall( + channel.newCall(method, callOptions.withCoroutineContext(rpcContext)), + request, + responseObserverChannel + ) + + return responseObserverChannel +} + +@ObsoleteCoroutinesApi +public fun T.clientCallBidiStreaming( + method: MethodDescriptor +): ClientBidiCallChannel + where T : CoroutineScope, T : AbstractStub { + + val rpcScope = newRpcScope(method, io.grpc.Context.current()) + val rpcContext = rpcScope.coroutineContext + val responseChannel = ClientResponseObserverChannel(rpcContext) + val requestObserver = asyncBidiStreamingCall( + channel.newCall(method, callOptions.withCoroutineContext(rpcContext)), + responseChannel + ) + val requestChannel = rpcScope.newSendChannelFromObserver(requestObserver) + + return ClientBidiCallChannel(requestChannel, responseChannel) +} + +@ObsoleteCoroutinesApi +public fun T.clientCallClientStreaming( + method: MethodDescriptor +): ClientStreamingCallChannel + where T : CoroutineScope, T : AbstractStub { + + val rpcScope = newRpcScope(method, io.grpc.Context.current()) + val rpcContext = rpcScope.coroutineContext + val completableResponse = CompletableDeferred() + val requestObserver = asyncClientStreamingCall( + channel.newCall(method, callOptions.withCoroutineContext(rpcContext)), completableResponse.toStreamObserver() + ) + val requestChannel = rpcScope.newSendChannelFromObserver(requestObserver) + return ClientStreamingCallChannel( + requestChannel, + completableResponse + ) +} + diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientChannels.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientChannels.kt new file mode 100644 index 0000000..3046321 --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientChannels.kt @@ -0,0 +1,64 @@ +package com.github.marcoferrer.krotoplus.coroutines.client + +import com.github.marcoferrer.krotoplus.coroutines.FlowControlledObserver +import com.github.marcoferrer.krotoplus.coroutines.enableManualFlowControl +import io.grpc.stub.ClientCallStreamObserver +import io.grpc.stub.ClientResponseObserver +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Deferred +import kotlinx.coroutines.ExperimentalCoroutinesApi +import kotlinx.coroutines.channels.Channel +import kotlinx.coroutines.channels.ReceiveChannel +import kotlinx.coroutines.channels.SendChannel +import java.util.concurrent.atomic.AtomicBoolean +import kotlin.coroutines.CoroutineContext + + +data class ClientBidiCallChannel( + val requestChannel: SendChannel, + val responseChannel: ReceiveChannel +) : SendChannel by requestChannel, + ReceiveChannel by responseChannel + + +data class ClientStreamingCallChannel( + val requestChannel: SendChannel = Channel(), + val response: Deferred +) : SendChannel by requestChannel + + +class ClientResponseObserverChannel( + override val coroutineContext: CoroutineContext, + private val responseChannelDelegate: Channel = Channel(capacity = 1) +) : ClientResponseObserver, + FlowControlledObserver, + ReceiveChannel by responseChannelDelegate, + CoroutineScope { + + private val isMessagePreloaded = AtomicBoolean() + + lateinit var requestStream: ClientCallStreamObserver + + @ExperimentalCoroutinesApi + override fun beforeStart(requestStream: ClientCallStreamObserver) { + this.requestStream = requestStream.apply { + enableManualFlowControl(responseChannelDelegate,isMessagePreloaded) + } + } + + @ExperimentalCoroutinesApi + override fun onNext(value: RespT) = nextValueWithBackPressure( + value = value, + channel = responseChannelDelegate, + callStreamObserver = requestStream, + isMessagePreloaded = isMessagePreloaded + ) + + override fun onError(t: Throwable) { + responseChannelDelegate.close(t) + } + + override fun onCompleted() { + responseChannelDelegate.close() + } +} \ No newline at end of file diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ResponseExts.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ResponseExts.kt new file mode 100644 index 0000000..6619b27 --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ResponseExts.kt @@ -0,0 +1,33 @@ +package com.github.marcoferrer.krotoplus.coroutines.server + +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.* + + +suspend fun CompletableDeferred.respondWith(block: suspend CoroutineScope.() -> T) { + coroutineScope { + try { + complete(block()) + } catch (e: Throwable) { + completeExceptionally(e) + } + } +} + +@ObsoleteCoroutinesApi +@ExperimentalCoroutinesApi +suspend fun SendChannel.respondWith(block: suspend ProducerScope.() -> Unit) { + coroutineScope { + val destinationChannel = this@respondWith + produce { + try{ + block() + }catch (e:Throwable){ + destinationChannel.close(e) + } + destinationChannel.close() + }.also { + it.toChannel(destinationChannel) + } + } +} diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerCalls.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerCalls.kt new file mode 100644 index 0000000..e7aa40d --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerCalls.kt @@ -0,0 +1,127 @@ +package com.github.marcoferrer.krotoplus.coroutines.server + +import com.github.marcoferrer.krotoplus.coroutines.* +import io.grpc.MethodDescriptor +import io.grpc.Status +import io.grpc.StatusRuntimeException +import io.grpc.stub.ServerCallStreamObserver +import io.grpc.stub.StreamObserver +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.* +import java.util.concurrent.atomic.AtomicBoolean + + +public fun CoroutineScope.serverCallUnary( + methodDescriptor: MethodDescriptor, + responseObserver: StreamObserver, + block: suspend () -> RespT +) { + newRpcScope(methodDescriptor, io.grpc.Context.current()) + .launch { responseObserver.onNext(block()) } + .invokeOnCompletion(responseObserver.completionHandler) +} + +@ExperimentalCoroutinesApi +@ObsoleteCoroutinesApi +public fun CoroutineScope.serverCallServerStreaming( + methodDescriptor: MethodDescriptor, + responseObserver: StreamObserver, + block: suspend (SendChannel) -> Unit +) { + val rpcScope = newRpcScope(methodDescriptor) + + val responseChannel = newSendChannelFromObserver(responseObserver) + + rpcScope.launch { block(responseChannel) } + .invokeOnCompletion { + responseChannel.close(it?.toRpcException()) + } +} + +@ExperimentalCoroutinesApi +fun CoroutineScope.serverCallClientStreaming( + methodDescriptor: MethodDescriptor, + responseObserver: StreamObserver, + block: suspend (ReceiveChannel) -> RespT +): StreamObserver { + + val rpcScope = newRpcScope(methodDescriptor, io.grpc.Context.current()) + + val isMessagePreloaded = AtomicBoolean(false) + val requestChannelDelegate = Channel(capacity = 1) + val serverCallObserver = (responseObserver as ServerCallStreamObserver) + .apply { enableManualFlowControl(requestChannelDelegate, isMessagePreloaded) } + + val requestChannel = ServerRequestStreamChannel( + coroutineContext = rpcScope.coroutineContext, + delegateChannel = requestChannelDelegate, + callStreamObserver = serverCallObserver, + isMessagePreloaded = isMessagePreloaded, + onErrorHandler = { + rpcScope.cancel() + responseObserver.onError(it.toRpcException()) + } + ) + + rpcScope + .launch { responseObserver.onNext(block(requestChannel)) } + .invokeOnCompletion(responseObserver.completionHandler) + + return requestChannel +} + + +@ObsoleteCoroutinesApi +@ExperimentalCoroutinesApi +public fun CoroutineScope.serverCallBidiStreaming( + methodDescriptor: MethodDescriptor, + responseObserver: StreamObserver, + block: suspend (ReceiveChannel, SendChannel) -> Unit +): StreamObserver { + + val rpcScope = newRpcScope(methodDescriptor, io.grpc.Context.current()) + + val isMessagePreloaded = AtomicBoolean(false) + val serverCallObserver = responseObserver as ServerCallStreamObserver + val requestChannelDelegate = Channel(capacity = 1) + val responseChannel = rpcScope.newManagedServerResponseChannel( + responseObserver = serverCallObserver, + requestChannel = requestChannelDelegate, + isMessagePreloaded = isMessagePreloaded + ) + val requestChannel = ServerRequestStreamChannel( + coroutineContext = rpcScope.coroutineContext, + delegateChannel = requestChannelDelegate, + callStreamObserver = serverCallObserver, + isMessagePreloaded = isMessagePreloaded, + onErrorHandler = { + // In the event of a request error, we + // need to close the responseChannel before + // cancelling the rpcScope. + responseChannel.close(it) + rpcScope.cancel() + } + ) + + rpcScope + .launch { block(requestChannel, responseChannel) } + .invokeOnCompletion(responseChannel.completionHandler) + + return requestChannel +} + + +private fun MethodDescriptor<*, *>.getUnimplementedException(): StatusRuntimeException = + Status.UNIMPLEMENTED + .withDescription("Method $fullMethodName is unimplemented") + .asRuntimeException() + +public fun serverCallUnimplementedUnary( + methodDescriptor: MethodDescriptor<*, *> +): T { + throw methodDescriptor.getUnimplementedException() +} + +public fun serverCallUnimplementedStream(methodDescriptor: MethodDescriptor<*, *>, responseChannel: SendChannel<*>) { + responseChannel.close(methodDescriptor.getUnimplementedException()) +} diff --git a/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerChannels.kt b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerChannels.kt new file mode 100644 index 0000000..3044504 --- /dev/null +++ b/kroto-plus-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerChannels.kt @@ -0,0 +1,41 @@ +package com.github.marcoferrer.krotoplus.coroutines.server + +import com.github.marcoferrer.krotoplus.coroutines.FlowControlledObserver +import io.grpc.stub.CallStreamObserver +import io.grpc.stub.StreamObserver +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.ExperimentalCoroutinesApi +import kotlinx.coroutines.channels.Channel +import kotlinx.coroutines.channels.ReceiveChannel +import java.util.concurrent.atomic.AtomicBoolean +import kotlin.coroutines.CoroutineContext + +@ExperimentalCoroutinesApi +class ServerRequestStreamChannel( + override val coroutineContext: CoroutineContext, + private val delegateChannel: Channel, + private val isMessagePreloaded: AtomicBoolean, + private val callStreamObserver: CallStreamObserver, + private val onErrorHandler: ((Throwable) -> Unit)? = null +) : ReceiveChannel by delegateChannel, + FlowControlledObserver, + StreamObserver, + CoroutineScope { + + @ExperimentalCoroutinesApi + override fun onNext(value: ReqT) = nextValueWithBackPressure( + value, + delegateChannel, + callStreamObserver, + isMessagePreloaded + ) + + override fun onError(t: Throwable) { + delegateChannel.close(t) + onErrorHandler?.invoke(t) + } + + override fun onCompleted() { + delegateChannel.close() + } +} \ No newline at end of file diff --git a/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExtsTest.kt b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExtsTest.kt new file mode 100644 index 0000000..3994cec --- /dev/null +++ b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CallChannelExtsTest.kt @@ -0,0 +1,73 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.Status +import io.grpc.stub.StreamObserver +import io.mockk.* +import kotlinx.coroutines.GlobalScope +import kotlinx.coroutines.runBlocking +import org.junit.Test +import kotlin.test.assertEquals +import kotlin.test.assertTrue + + +class NewSendChannelFromObserverTests { + + @Test + fun `Test channel send to observer success`() = runBlocking { + + val observer = mockk>().apply { + every { onNext(allAny()) } just Runs + every { onCompleted() } just Runs + } + + GlobalScope.newSendChannelFromObserver(observer).apply { + repeat(3){ send(it) } + close() + } + + verify(exactly = 3) { observer.onNext(allAny()) } + } + + @Test + fun `Test channel close with error`() = runBlocking { + + val statusException = Status.INVALID_ARGUMENT.asException() + val observer = mockk>().apply { + every { onNext(allAny()) } just Runs + every { onError(statusException) } just Runs + } + + GlobalScope.newSendChannelFromObserver(observer).apply { + send("") + close(statusException) + } + + verify(exactly = 1) { observer.onNext(allAny()) } + verify(exactly = 1) { observer.onError(statusException) } + } + + @Test + fun `Test channel close when observer onNext error `() = runBlocking { + + val statusException = Status.UNKNOWN.asException() + val observer = mockk>().apply { + every { onNext(allAny()) } throws statusException + every { onError(statusException) } just Runs + } + + GlobalScope.newSendChannelFromObserver(observer).apply { + + val send1Result = runCatching { send("") } + assertTrue(send1Result.isSuccess, "Error during observer.onNext should not fail channel.send") + assertTrue(isClosedForSend,"Channel should be closed after onNext error") + + val send2Result = runCatching { send("") } + assertTrue(send2Result.isFailure, "Expecting error after sending a value to failed channel") + assertEquals(statusException,send2Result.exceptionOrNull()) + } + + verify(exactly = 1) { observer.onNext(allAny()) } + verify(exactly = 1) { observer.onError(statusException) } + verify(inverse = true) { observer.onCompleted() } + } +} \ No newline at end of file diff --git a/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponseTest.kt b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponseTest.kt new file mode 100644 index 0000000..0fd2234 --- /dev/null +++ b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/CompletableDeferredResponseTest.kt @@ -0,0 +1,2 @@ +package com.github.marcoferrer.krotoplus.coroutines + diff --git a/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/EnableManualFlowControlTests.kt b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/EnableManualFlowControlTests.kt new file mode 100644 index 0000000..39c3bd1 --- /dev/null +++ b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/EnableManualFlowControlTests.kt @@ -0,0 +1,156 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.stub.CallStreamObserver +import io.mockk.* +import kotlinx.coroutines.channels.Channel +import org.junit.Test +import java.util.concurrent.atomic.AtomicBoolean + + +class EnableManualFlowControlTests { + + @Test + fun `Test observer not ready`(){ + + val onReadyHandler = slot() + val targetChannel = mockk>() + val observer = mockk>().apply { + every { isReady } returns false + every { setOnReadyHandler(capture(onReadyHandler)) } just Runs + every { disableAutoInboundFlowControl() } just Runs + } + + observer.enableManualFlowControl(targetChannel, AtomicBoolean()) + + onReadyHandler.captured.run() + + verify(exactly = 1) { observer.isReady } + verify(exactly = 1) { observer.disableAutoInboundFlowControl() } + verify(exactly = 1) { observer.setOnReadyHandler(any()) } + verify(inverse = true) { observer.request(any()) } + } + + @Test + fun `Test channel is full`(){ + + val onReadyHandler = slot() + val targetChannel = mockk>().apply { + every { isFull } returns true + } + val observer = mockk>().apply { + every { isReady } returns true + every { setOnReadyHandler(capture(onReadyHandler)) } just Runs + every { disableAutoInboundFlowControl() } just Runs + } + + observer.enableManualFlowControl(targetChannel, AtomicBoolean()) + + onReadyHandler.captured.run() + + verify(exactly = 1) { observer.isReady } + verify(exactly = 1) { observer.disableAutoInboundFlowControl() } + verify(exactly = 1) { observer.setOnReadyHandler(any()) } + verify(inverse = true) { observer.request(any()) } + + verify(exactly = 1) { targetChannel.isFull } + verify(inverse = true) { targetChannel.isClosedForSend } + } + + + @Test + fun `Test channel is closed for send`(){ + + val onReadyHandler = slot() + val isMessagePreloaded = mockk() + val targetChannel = mockk>().apply { + every { isFull } returns false + every { isClosedForSend } returns true + } + val observer = mockk>().apply { + every { isReady } returns true + every { setOnReadyHandler(capture(onReadyHandler)) } just Runs + every { disableAutoInboundFlowControl() } just Runs + } + + observer.enableManualFlowControl(targetChannel,isMessagePreloaded) + + onReadyHandler.captured.run() + + verify(exactly = 1) { observer.isReady } + verify(exactly = 1) { observer.disableAutoInboundFlowControl() } + verify(exactly = 1) { observer.setOnReadyHandler(any()) } + verify(inverse = true) { observer.request(any()) } + + verify(exactly = 1) { targetChannel.isFull } + verify(exactly = 1) { targetChannel.isClosedForSend } + + verify(inverse = true) { isMessagePreloaded.compareAndSet(any(),any()) } + } + + + @Test + fun `Test message is preloaded for target channel`(){ + + val onReadyHandler = slot() + val isMessagePreloaded = mockk().apply { + every { compareAndSet(false,true) } returns false + } + val targetChannel = mockk>().apply { + every { isFull } returns false + every { isClosedForSend } returns false + } + val observer = mockk>().apply { + every { isReady } returns true + every { setOnReadyHandler(capture(onReadyHandler)) } just Runs + every { disableAutoInboundFlowControl() } just Runs + } + + observer.enableManualFlowControl(targetChannel,isMessagePreloaded) + + onReadyHandler.captured.run() + + verify(exactly = 1) { observer.isReady } + verify(exactly = 1) { observer.disableAutoInboundFlowControl() } + verify(exactly = 1) { observer.setOnReadyHandler(any()) } + verify(inverse = true) { observer.request(any()) } + + verify(exactly = 1) { targetChannel.isFull } + verify(exactly = 1) { targetChannel.isClosedForSend } + + verify(exactly = 1) { isMessagePreloaded.compareAndSet(false,true) } + } + + + @Test + fun `Test ready to request new message from observer`(){ + + val onReadyHandler = slot() + val isMessagePreloaded = mockk().apply { + every { compareAndSet(false,true) } returns true + } + val targetChannel = mockk>().apply { + every { isFull } returns false + every { isClosedForSend } returns false + } + val observer = mockk>().apply { + every { isReady } returns true + every { setOnReadyHandler(capture(onReadyHandler)) } just Runs + every { disableAutoInboundFlowControl() } just Runs + every { request(1) } just Runs + } + + observer.enableManualFlowControl(targetChannel,isMessagePreloaded) + + onReadyHandler.captured.run() + + verify(exactly = 1) { observer.isReady } + verify(exactly = 1) { observer.disableAutoInboundFlowControl() } + verify(exactly = 1) { observer.setOnReadyHandler(any()) } + verify(exactly = 1) { observer.request(1) } + + verify(exactly = 1) { targetChannel.isFull } + verify(exactly = 1) { targetChannel.isClosedForSend } + + verify(exactly = 1) { isMessagePreloaded.compareAndSet(false,true) } + } +} \ No newline at end of file diff --git a/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControlledObserverTests.kt b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControlledObserverTests.kt new file mode 100644 index 0000000..8f65d65 --- /dev/null +++ b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/FlowControlledObserverTests.kt @@ -0,0 +1,91 @@ +package com.github.marcoferrer.krotoplus.coroutines + +import io.grpc.stub.CallStreamObserver +import io.mockk.* +import kotlinx.coroutines.* +import kotlinx.coroutines.channels.Channel +import kotlinx.coroutines.channels.SendChannel +import org.junit.Test +import java.util.concurrent.atomic.AtomicBoolean + + +class NextValueWithBackPressureTests { + + private val mockObserver = object: FlowControlledObserver{} + + @Test + fun `Test channel is closed`() { + + val observer = mockk>() + val isMessagePreloaded = mockk() + val mockScope = mockk() + val channel = mockk>().apply { + every { isClosedForSend } returns true + } + + with(mockObserver){ + mockScope.nextValueWithBackPressure(1,channel, observer, isMessagePreloaded) + } + + verify { isMessagePreloaded wasNot Called } + verify(atLeast = 1) { channel.isClosedForSend } + verify(inverse = true) { channel.offer(any()) } + coVerify(inverse = true) { channel.send(any()) } + } + + @Test + fun `Test channel accepts value`() { + + val observer = mockk>().apply { + every { request(1) } just Runs + } + val mockScope = mockk() + val isMessagePreloaded = mockk() + val channel = mockk>().apply { + every { isClosedForSend } returns false + every { offer(1) } returns true + } + + with(mockObserver){ + mockScope.nextValueWithBackPressure(1,channel, observer, isMessagePreloaded) + } + + verify { isMessagePreloaded wasNot Called } + verify(atLeast = 1) { channel.isClosedForSend } + verify(exactly = 1) { channel.offer(any()) } + verify(exactly = 1) { observer.request(1) } + coVerify(inverse = true) { channel.send(any()) } + } + + @Test + fun `Test channel buffer is full and preload value`() { + + val observer = mockk>().apply { + every { request(1) } just Runs + } + val isMessagePreloaded = mockk().apply { + every { set(allAny()) } just Runs + } + val channel = spyk(Channel(capacity = 1)) + + runBlocking { + channel.offer(0) + assert(channel.isFull){ "Target channel will not cause preload" } + with(mockObserver) { + nextValueWithBackPressure(1, channel, observer, isMessagePreloaded) + } + channel.receive() + } + + verifyOrder { + isMessagePreloaded.set(true) + isMessagePreloaded.set(false) + } + verify { channel.offer(any()) } + verify(atLeast = 1) { channel.isClosedForSend } + verify(exactly = 1) { observer.request(1) } + coVerify(exactly = 1) { channel.send(any()) } + } +} + + diff --git a/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/SuspendingUnaryObserverTest.kt b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/SuspendingUnaryObserverTest.kt new file mode 100644 index 0000000..0fd2234 --- /dev/null +++ b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/SuspendingUnaryObserverTest.kt @@ -0,0 +1,2 @@ +package com.github.marcoferrer.krotoplus.coroutines + diff --git a/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientResponseObserverChannelTest.kt b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientResponseObserverChannelTest.kt new file mode 100644 index 0000000..b8b7e67 --- /dev/null +++ b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/client/ClientResponseObserverChannelTest.kt @@ -0,0 +1,2 @@ +package com.github.marcoferrer.krotoplus.coroutines.client + diff --git a/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerRequestStreamChannelTest.kt b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerRequestStreamChannelTest.kt new file mode 100644 index 0000000..3898c1f --- /dev/null +++ b/kroto-plus-coroutines/src/test/kotlin/com/github/marcoferrer/krotoplus/coroutines/server/ServerRequestStreamChannelTest.kt @@ -0,0 +1,2 @@ +package com.github.marcoferrer.krotoplus.coroutines.server + diff --git a/kroto-plus-test/build.gradle b/kroto-plus-test/build.gradle index ea6f5e6..d7038f9 100644 --- a/kroto-plus-test/build.gradle +++ b/kroto-plus-test/build.gradle @@ -3,7 +3,7 @@ description = "Kroto+ Test Support" apply from: "$rootDir/publishing.gradle" dependencies { - implementation "io.grpc:grpc-testing:${versions.grpc}" - implementation "com.google.protobuf:protobuf-java:${versions.protobuf}" + implementation "io.grpc:grpc-testing:${Versions.grpc}" + implementation "com.google.protobuf:protobuf-java:${Versions.protobuf}" implementation project(":kroto-plus-message") } \ No newline at end of file diff --git a/protoc-gen-grpc-coroutines/build.gradle b/protoc-gen-grpc-coroutines/build.gradle new file mode 100644 index 0000000..570437e --- /dev/null +++ b/protoc-gen-grpc-coroutines/build.gradle @@ -0,0 +1,57 @@ +apply plugin: 'org.springframework.boot' +apply from: "$rootDir/publishing.gradle" + +description 'Kroto+ Proto-c Grpc Coroutines Plugin' + +def mainClassName = 'com.github.marcoferrer.krotoplus.GrpcCoroutinesMain' + +sourceCompatibility = 1.8 +targetCompatibility = 1.8 + +dependencies{ + implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:${Versions.coroutines}" + implementation "io.grpc:grpc-protobuf:${Versions.grpc}" + implementation "com.google.protobuf:protobuf-java:${Versions.protobuf}" + + implementation project(':protoc-gen-kroto-plus') + +} + +bootJar { + launchScript() + classifier = 'jvm8' + + dependsOn jar + from(jar) { into '/BOOT-INF/lib' } + + manifest { + attributes 'Start-Class': mainClassName + attributes 'Implementation-Title' : 'Kroto+ Proto-c Grpc Coroutines Plugin' + attributes 'Implementation-Version': project.version + } +} + +jar.enabled = true + +artifacts { + archives bootJar +} + +publishing { + publications { + mavenPublication(MavenPublication) { + artifact bootJar { + classifier "jvm8" + } + } + } +} + +idea { + module { + inheritOutputDirs = false + outputDir = file("$buildDir/classes/kotlin/main") + testOutputDir = file("$buildDir/classes/kotlin/test") + } +} + diff --git a/protoc-gen-grpc-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/GrpcCoroutinesMain.kt b/protoc-gen-grpc-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/GrpcCoroutinesMain.kt new file mode 100644 index 0000000..c1a61bb --- /dev/null +++ b/protoc-gen-grpc-coroutines/src/main/kotlin/com/github/marcoferrer/krotoplus/GrpcCoroutinesMain.kt @@ -0,0 +1,21 @@ +@file:JvmName("GrpcCoroutinesMain") + +package com.github.marcoferrer.krotoplus + +import com.github.marcoferrer.krotoplus.config.CompilerConfig +import com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions +import com.github.marcoferrer.krotoplus.generators.GrpcCoroutinesGenerator +import com.github.marcoferrer.krotoplus.generators.initializeContext + +fun main(args: Array) { + + initializeContext( + CompilerConfig.newBuilder() + .addGrpcCoroutines(GrpcCoroutinesGenOptions.getDefaultInstance()) + .build() + ) + + GrpcCoroutinesGenerator().writeTo(System.out) + + System.out.flush() +} \ No newline at end of file diff --git a/protoc-gen-kroto-plus/build.gradle b/protoc-gen-kroto-plus/build.gradle index 310e8cb..6ae303a 100644 --- a/protoc-gen-kroto-plus/build.gradle +++ b/protoc-gen-kroto-plus/build.gradle @@ -19,9 +19,9 @@ sourceCompatibility = 1.8 targetCompatibility = 1.8 dependencies{ - implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:${versions.coroutines}" - implementation "io.grpc:grpc-protobuf:${versions.grpc}" - implementation "com.google.protobuf:protobuf-java:${versions.protobuf}" + implementation "org.jetbrains.kotlinx:kotlinx-coroutines-core:${Versions.coroutines}" + implementation "io.grpc:grpc-protobuf:${Versions.grpc}" + implementation "com.google.protobuf:protobuf-java:${Versions.protobuf}" implementation "org.jetbrains.kotlin:kotlin-reflect" implementation ("com.squareup:kotlinpoet:0.7.0") { exclude group: 'org.jetbrains.kotlin' @@ -31,12 +31,12 @@ dependencies{ implementation "org.jetbrains.kotlin:kotlin-script-util" implementation "org.jetbrains.kotlin:kotlin-script-runtime" implementation "org.jetbrains.kotlin:kotlin-compiler-embeddable" - implementation "com.google.protobuf:protobuf-java-util:${versions.protobuf}" + implementation "com.google.protobuf:protobuf-java-util:${Versions.protobuf}" } protobuf { - protoc { artifact = "com.google.protobuf:protoc:${versions.protobuf}" } + protoc { artifact = "com.google.protobuf:protoc:${Versions.protobuf}" } generateProtoTasks { all().each { task -> diff --git a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfig.java b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfig.java index a1eec03..eec8e46 100644 --- a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfig.java +++ b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfig.java @@ -26,6 +26,7 @@ private CompilerConfig() { extendableMessages_ = java.util.Collections.emptyList(); insertions_ = java.util.Collections.emptyList(); generatorScripts_ = java.util.Collections.emptyList(); + grpcCoroutines_ = java.util.Collections.emptyList(); } @java.lang.Override @@ -106,6 +107,15 @@ private CompilerConfig( input.readMessage(com.github.marcoferrer.krotoplus.config.GeneratorScriptsGenOptions.parser(), extensionRegistry)); break; } + case 210: { + if (!((mutable_bitField0_ & 0x00000040) == 0x00000040)) { + grpcCoroutines_ = new java.util.ArrayList(); + mutable_bitField0_ |= 0x00000040; + } + grpcCoroutines_.add( + input.readMessage(com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.parser(), extensionRegistry)); + break; + } default: { if (!parseUnknownFieldProto3( input, unknownFields, extensionRegistry, tag)) { @@ -139,6 +149,9 @@ private CompilerConfig( if (((mutable_bitField0_ & 0x00000020) == 0x00000020)) { generatorScripts_ = java.util.Collections.unmodifiableList(generatorScripts_); } + if (((mutable_bitField0_ & 0x00000040) == 0x00000040)) { + grpcCoroutines_ = java.util.Collections.unmodifiableList(grpcCoroutines_); + } this.unknownFields = unknownFields.build(); makeExtensionsImmutable(); } @@ -486,6 +499,61 @@ public com.github.marcoferrer.krotoplus.config.GeneratorScriptsGenOptionsOrBuild return generatorScripts_.get(index); } + public static final int GRPC_COROUTINES_FIELD_NUMBER = 26; + private java.util.List grpcCoroutines_; + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public java.util.List getGrpcCoroutinesList() { + return grpcCoroutines_; + } + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public java.util.List + getGrpcCoroutinesOrBuilderList() { + return grpcCoroutines_; + } + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public int getGrpcCoroutinesCount() { + return grpcCoroutines_.size(); + } + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions getGrpcCoroutines(int index) { + return grpcCoroutines_.get(index); + } + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptionsOrBuilder getGrpcCoroutinesOrBuilder( + int index) { + return grpcCoroutines_.get(index); + } + private byte memoizedIsInitialized = -1; @java.lang.Override public final boolean isInitialized() { @@ -518,6 +586,9 @@ public void writeTo(com.google.protobuf.CodedOutputStream output) for (int i = 0; i < generatorScripts_.size(); i++) { output.writeMessage(25, generatorScripts_.get(i)); } + for (int i = 0; i < grpcCoroutines_.size(); i++) { + output.writeMessage(26, grpcCoroutines_.get(i)); + } unknownFields.writeTo(output); } @@ -551,6 +622,10 @@ public int getSerializedSize() { size += com.google.protobuf.CodedOutputStream .computeMessageSize(25, generatorScripts_.get(i)); } + for (int i = 0; i < grpcCoroutines_.size(); i++) { + size += com.google.protobuf.CodedOutputStream + .computeMessageSize(26, grpcCoroutines_.get(i)); + } size += unknownFields.getSerializedSize(); memoizedSize = size; return size; @@ -579,6 +654,8 @@ public boolean equals(final java.lang.Object obj) { .equals(other.getInsertionsList()); result = result && getGeneratorScriptsList() .equals(other.getGeneratorScriptsList()); + result = result && getGrpcCoroutinesList() + .equals(other.getGrpcCoroutinesList()); result = result && unknownFields.equals(other.unknownFields); return result; } @@ -614,6 +691,10 @@ public int hashCode() { hash = (37 * hash) + GENERATOR_SCRIPTS_FIELD_NUMBER; hash = (53 * hash) + getGeneratorScriptsList().hashCode(); } + if (getGrpcCoroutinesCount() > 0) { + hash = (37 * hash) + GRPC_COROUTINES_FIELD_NUMBER; + hash = (53 * hash) + getGrpcCoroutinesList().hashCode(); + } hash = (29 * hash) + unknownFields.hashCode(); memoizedHashCode = hash; return hash; @@ -752,6 +833,7 @@ private void maybeForceBuilderInitialization() { getExtendableMessagesFieldBuilder(); getInsertionsFieldBuilder(); getGeneratorScriptsFieldBuilder(); + getGrpcCoroutinesFieldBuilder(); } } @java.lang.Override @@ -793,6 +875,12 @@ public Builder clear() { } else { generatorScriptsBuilder_.clear(); } + if (grpcCoroutinesBuilder_ == null) { + grpcCoroutines_ = java.util.Collections.emptyList(); + bitField0_ = (bitField0_ & ~0x00000040); + } else { + grpcCoroutinesBuilder_.clear(); + } return this; } @@ -874,6 +962,15 @@ public com.github.marcoferrer.krotoplus.config.CompilerConfig buildPartial() { } else { result.generatorScripts_ = generatorScriptsBuilder_.build(); } + if (grpcCoroutinesBuilder_ == null) { + if (((bitField0_ & 0x00000040) == 0x00000040)) { + grpcCoroutines_ = java.util.Collections.unmodifiableList(grpcCoroutines_); + bitField0_ = (bitField0_ & ~0x00000040); + } + result.grpcCoroutines_ = grpcCoroutines_; + } else { + result.grpcCoroutines_ = grpcCoroutinesBuilder_.build(); + } onBuilt(); return result; } @@ -1078,6 +1175,32 @@ public Builder mergeFrom(com.github.marcoferrer.krotoplus.config.CompilerConfig } } } + if (grpcCoroutinesBuilder_ == null) { + if (!other.grpcCoroutines_.isEmpty()) { + if (grpcCoroutines_.isEmpty()) { + grpcCoroutines_ = other.grpcCoroutines_; + bitField0_ = (bitField0_ & ~0x00000040); + } else { + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.addAll(other.grpcCoroutines_); + } + onChanged(); + } + } else { + if (!other.grpcCoroutines_.isEmpty()) { + if (grpcCoroutinesBuilder_.isEmpty()) { + grpcCoroutinesBuilder_.dispose(); + grpcCoroutinesBuilder_ = null; + grpcCoroutines_ = other.grpcCoroutines_; + bitField0_ = (bitField0_ & ~0x00000040); + grpcCoroutinesBuilder_ = + com.google.protobuf.GeneratedMessageV3.alwaysUseFieldBuilders ? + getGrpcCoroutinesFieldBuilder() : null; + } else { + grpcCoroutinesBuilder_.addAllMessages(other.grpcCoroutines_); + } + } + } this.mergeUnknownFields(other.unknownFields); onChanged(); return this; @@ -2979,6 +3102,318 @@ public com.github.marcoferrer.krotoplus.config.GeneratorScriptsGenOptions.Builde } return generatorScriptsBuilder_; } + + private java.util.List grpcCoroutines_ = + java.util.Collections.emptyList(); + private void ensureGrpcCoroutinesIsMutable() { + if (!((bitField0_ & 0x00000040) == 0x00000040)) { + grpcCoroutines_ = new java.util.ArrayList(grpcCoroutines_); + bitField0_ |= 0x00000040; + } + } + + private com.google.protobuf.RepeatedFieldBuilderV3< + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptionsOrBuilder> grpcCoroutinesBuilder_; + + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public java.util.List getGrpcCoroutinesList() { + if (grpcCoroutinesBuilder_ == null) { + return java.util.Collections.unmodifiableList(grpcCoroutines_); + } else { + return grpcCoroutinesBuilder_.getMessageList(); + } + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public int getGrpcCoroutinesCount() { + if (grpcCoroutinesBuilder_ == null) { + return grpcCoroutines_.size(); + } else { + return grpcCoroutinesBuilder_.getCount(); + } + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions getGrpcCoroutines(int index) { + if (grpcCoroutinesBuilder_ == null) { + return grpcCoroutines_.get(index); + } else { + return grpcCoroutinesBuilder_.getMessage(index); + } + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder setGrpcCoroutines( + int index, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions value) { + if (grpcCoroutinesBuilder_ == null) { + if (value == null) { + throw new NullPointerException(); + } + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.set(index, value); + onChanged(); + } else { + grpcCoroutinesBuilder_.setMessage(index, value); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder setGrpcCoroutines( + int index, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder builderForValue) { + if (grpcCoroutinesBuilder_ == null) { + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.set(index, builderForValue.build()); + onChanged(); + } else { + grpcCoroutinesBuilder_.setMessage(index, builderForValue.build()); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder addGrpcCoroutines(com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions value) { + if (grpcCoroutinesBuilder_ == null) { + if (value == null) { + throw new NullPointerException(); + } + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.add(value); + onChanged(); + } else { + grpcCoroutinesBuilder_.addMessage(value); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder addGrpcCoroutines( + int index, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions value) { + if (grpcCoroutinesBuilder_ == null) { + if (value == null) { + throw new NullPointerException(); + } + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.add(index, value); + onChanged(); + } else { + grpcCoroutinesBuilder_.addMessage(index, value); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder addGrpcCoroutines( + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder builderForValue) { + if (grpcCoroutinesBuilder_ == null) { + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.add(builderForValue.build()); + onChanged(); + } else { + grpcCoroutinesBuilder_.addMessage(builderForValue.build()); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder addGrpcCoroutines( + int index, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder builderForValue) { + if (grpcCoroutinesBuilder_ == null) { + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.add(index, builderForValue.build()); + onChanged(); + } else { + grpcCoroutinesBuilder_.addMessage(index, builderForValue.build()); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder addAllGrpcCoroutines( + java.lang.Iterable values) { + if (grpcCoroutinesBuilder_ == null) { + ensureGrpcCoroutinesIsMutable(); + com.google.protobuf.AbstractMessageLite.Builder.addAll( + values, grpcCoroutines_); + onChanged(); + } else { + grpcCoroutinesBuilder_.addAllMessages(values); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder clearGrpcCoroutines() { + if (grpcCoroutinesBuilder_ == null) { + grpcCoroutines_ = java.util.Collections.emptyList(); + bitField0_ = (bitField0_ & ~0x00000040); + onChanged(); + } else { + grpcCoroutinesBuilder_.clear(); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public Builder removeGrpcCoroutines(int index) { + if (grpcCoroutinesBuilder_ == null) { + ensureGrpcCoroutinesIsMutable(); + grpcCoroutines_.remove(index); + onChanged(); + } else { + grpcCoroutinesBuilder_.remove(index); + } + return this; + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder getGrpcCoroutinesBuilder( + int index) { + return getGrpcCoroutinesFieldBuilder().getBuilder(index); + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptionsOrBuilder getGrpcCoroutinesOrBuilder( + int index) { + if (grpcCoroutinesBuilder_ == null) { + return grpcCoroutines_.get(index); } else { + return grpcCoroutinesBuilder_.getMessageOrBuilder(index); + } + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public java.util.List + getGrpcCoroutinesOrBuilderList() { + if (grpcCoroutinesBuilder_ != null) { + return grpcCoroutinesBuilder_.getMessageOrBuilderList(); + } else { + return java.util.Collections.unmodifiableList(grpcCoroutines_); + } + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder addGrpcCoroutinesBuilder() { + return getGrpcCoroutinesFieldBuilder().addBuilder( + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.getDefaultInstance()); + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder addGrpcCoroutinesBuilder( + int index) { + return getGrpcCoroutinesFieldBuilder().addBuilder( + index, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.getDefaultInstance()); + } + /** + * 
    +     * Configuration entries for the 'Grpc Coroutines' code generator.
+     *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + public java.util.List + getGrpcCoroutinesBuilderList() { + return getGrpcCoroutinesFieldBuilder().getBuilderList(); + } + private com.google.protobuf.RepeatedFieldBuilderV3< + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptionsOrBuilder> + getGrpcCoroutinesFieldBuilder() { + if (grpcCoroutinesBuilder_ == null) { + grpcCoroutinesBuilder_ = new com.google.protobuf.RepeatedFieldBuilderV3< + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptionsOrBuilder>( + grpcCoroutines_, + ((bitField0_ & 0x00000040) == 0x00000040), + getParentForChildren(), + isClean()); + grpcCoroutines_ = null; + } + return grpcCoroutinesBuilder_; + } @java.lang.Override public final Builder setUnknownFields( final com.google.protobuf.UnknownFieldSet unknownFields) { diff --git a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfigOrBuilder.java b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfigOrBuilder.java index 2fe5a0a..2a30d1a 100644 --- a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfigOrBuilder.java +++ b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/CompilerConfigOrBuilder.java @@ -270,4 +270,48 @@ com.github.marcoferrer.krotoplus.config.InsertionsGenOptionsOrBuilder getInserti */ com.github.marcoferrer.krotoplus.config.GeneratorScriptsGenOptionsOrBuilder getGeneratorScriptsOrBuilder( int index); + + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + java.util.List + getGrpcCoroutinesList(); + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions getGrpcCoroutines(int index); + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + int getGrpcCoroutinesCount(); + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + java.util.List + getGrpcCoroutinesOrBuilderList(); + /** + * 
    +   * Configuration entries for the 'Grpc Coroutines' code generator.
+   *
    + * + * repeated .krotoplus.compiler.GrpcCoroutinesGenOptions grpc_coroutines = 26; + */ + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptionsOrBuilder getGrpcCoroutinesOrBuilder( + int index); } diff --git a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/Config.java b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/Config.java index 9273fde..41d70c5 100644 --- a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/Config.java +++ b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/Config.java @@ -29,6 +29,11 @@ public static void registerAllExtensions( static final com.google.protobuf.GeneratedMessageV3.FieldAccessorTable internal_static_krotoplus_compiler_GrpcStubExtsGenOptions_fieldAccessorTable; + static final com.google.protobuf.Descriptors.Descriptor + internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_descriptor; + static final + com.google.protobuf.GeneratedMessageV3.FieldAccessorTable + internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_fieldAccessorTable; static final com.google.protobuf.Descriptors.Descriptor internal_static_krotoplus_compiler_ProtoBuildersGenOptions_descriptor; static final @@ -70,7 +75,7 @@ public static void registerAllExtensions( java.lang.String[] descriptorData = { "\n\037krotoplus/compiler/config.proto\022\022kroto" + "plus.compiler\032 google/protobuf/descripto" + - "r.proto\"\263\003\n\016CompilerConfig\022B\n\016grpc_stub_" + + "r.proto\"\372\003\n\016CompilerConfig\022B\n\016grpc_stub_" + "exts\030\024 \003(\0132*.krotoplus.compiler.GrpcStub" + "ExtsGenOptions\022A\n\rmock_services\030\025 \003(\0132*." + "krotoplus.compiler.MockServicesGenOption" + @@ -81,39 +86,42 @@ public static void registerAllExtensions( "ns\030\030 \003(\0132(.krotoplus.compiler.Insertions" + "GenOptions\022I\n\021generator_scripts\030\031 \003(\0132.." + "krotoplus.compiler.GeneratorScriptsGenOp" + - "tions\"8\n\nFileFilter\022\024\n\014include_path\030\001 \003(" + - "\t\022\024\n\014exclude_path\030\002 \003(\t\"d\n\026GrpcStubExtsG" + - "enOptions\022.\n\006filter\030\001 \001(\0132\036.krotoplus.co" + - "mpiler.FileFilter\022\032\n\022support_coroutines\030" + - "\002 \001(\010\"{\n\027ProtoBuildersGenOptions\022.\n\006filt" + - "er\030\001 \001(\0132\036.krotoplus.compiler.FileFilter" + - "\022\027\n\017unwrap_builders\030\002 \001(\010\022\027\n\017use_dsl_mar" + - "kers\030\003 \001(\010\"x\n\032GeneratorScriptsGenOptions" + + "tions\022E\n\017grpc_coroutines\030\032 \003(\0132,.krotopl" + + "us.compiler.GrpcCoroutinesGenOptions\"8\n\n" + + "FileFilter\022\024\n\014include_path\030\001 \003(\t\022\024\n\014excl" + + "ude_path\030\002 \003(\t\"d\n\026GrpcStubExtsGenOptions" + + "\022.\n\006filter\030\001 \001(\0132\036.krotoplus.compiler.Fi" + + "leFilter\022\032\n\022support_coroutines\030\002 \001(\010\"J\n\030" + + "GrpcCoroutinesGenOptions\022.\n\006filter\030\001 \001(\013" + + "2\036.krotoplus.compiler.FileFilter\"{\n\027Prot" + + "oBuildersGenOptions\022.\n\006filter\030\001 \001(\0132\036.kr" + + "otoplus.compiler.FileFilter\022\027\n\017unwrap_bu" + + "ilders\030\002 \001(\010\022\027\n\017use_dsl_markers\030\003 \001(\010\"x\n" + + "\032GeneratorScriptsGenOptions\022.\n\006filter\030\001 " + + "\001(\0132\036.krotoplus.compiler.FileFilter\022\023\n\013s" + + "cript_path\030\002 \003(\t\022\025\n\rscript_bundle\030\003 \001(\t\"" + + "\302\001\n\033ExtenableMessagesGenOptions\022.\n\006filte" + + "r\030\001 \001(\0132\036.krotoplus.compiler.FileFilter\022" + + "\034\n\024companion_field_name\030\002 \001(\t\022\034\n\024compani" + + "on_class_name\030\003 \001(\t\022\031\n\021companion_extends" + + "\030\004 \001(\t\022\034\n\024companion_implements\030\005 \001(\t\"\376\001\n" + + "\024InsertionsGenOptions\022.\n\006filter\030\001 \001(\0132\036." + + "krotoplus.compiler.FileFilter\022=\n\005entry\030\002" + + " \003(\0132..krotoplus.compiler.InsertionsGenO" + + "ptions.Entry\032w\n\005Entry\0221\n\005point\030\001 \001(\0162\".k" + + "rotoplus.compiler.InsertionPoint\022\017\n\007cont" + + "ent\030\002 \003(\t\022\023\n\013script_path\030\003 \003(\t\022\025\n\rscript" + + "_bundle\030\004 \001(\t\"\275\001\n\026MockServicesGenOptions" + "\022.\n\006filter\030\001 \001(\0132\036.krotoplus.compiler.Fi" + - "leFilter\022\023\n\013script_path\030\002 \003(\t\022\025\n\rscript_" + - "bundle\030\003 \001(\t\"\302\001\n\033ExtenableMessagesGenOpt" + - "ions\022.\n\006filter\030\001 \001(\0132\036.krotoplus.compile" + - "r.FileFilter\022\034\n\024companion_field_name\030\002 \001" + - "(\t\022\034\n\024companion_class_name\030\003 \001(\t\022\031\n\021comp" + - "anion_extends\030\004 \001(\t\022\034\n\024companion_impleme" + - "nts\030\005 \001(\t\"\376\001\n\024InsertionsGenOptions\022.\n\006fi" + - "lter\030\001 \001(\0132\036.krotoplus.compiler.FileFilt" + - "er\022=\n\005entry\030\002 \003(\0132..krotoplus.compiler.I" + - "nsertionsGenOptions.Entry\032w\n\005Entry\0221\n\005po" + - "int\030\001 \001(\0162\".krotoplus.compiler.Insertion" + - "Point\022\017\n\007content\030\002 \003(\t\022\023\n\013script_path\030\003 " + - "\003(\t\022\025\n\rscript_bundle\030\004 \001(\t\"\275\001\n\026MockServi" + - "cesGenOptions\022.\n\006filter\030\001 \001(\0132\036.krotoplu" + - "s.compiler.FileFilter\022\033\n\023implement_as_ob" + - "ject\030\002 \001(\010\022\035\n\025generate_service_list\030\003 \001(" + - "\010\022\034\n\024service_list_package\030\004 \001(\t\022\031\n\021servi" + - "ce_list_name\030\005 \001(\t*\257\001\n\016InsertionPoint\022\013\n" + - "\007UNKNOWN\020\000\022\025\n\021INTERFACE_EXTENDS\020\001\022\026\n\022MES" + - "SAGE_IMPLEMENTS\020\002\022\026\n\022BUILDER_IMPLEMENTS\020" + - "\003\022\021\n\rBUILDER_SCOPE\020\004\022\017\n\013CLASS_SCOPE\020\005\022\016\n" + - "\nENUM_SCOPE\020\006\022\025\n\021OUTER_CLASS_SCOPE\020\007B+\n\'" + - "com.github.marcoferrer.krotoplus.configP" + - "\001b\006proto3" + "leFilter\022\033\n\023implement_as_object\030\002 \001(\010\022\035\n" + + "\025generate_service_list\030\003 \001(\010\022\034\n\024service_" + + "list_package\030\004 \001(\t\022\031\n\021service_list_name\030" + + "\005 \001(\t*\257\001\n\016InsertionPoint\022\013\n\007UNKNOWN\020\000\022\025\n" + + "\021INTERFACE_EXTENDS\020\001\022\026\n\022MESSAGE_IMPLEMEN" + + "TS\020\002\022\026\n\022BUILDER_IMPLEMENTS\020\003\022\021\n\rBUILDER_" + + "SCOPE\020\004\022\017\n\013CLASS_SCOPE\020\005\022\016\n\nENUM_SCOPE\020\006" + + "\022\025\n\021OUTER_CLASS_SCOPE\020\007B+\n\'com.github.ma" + + "rcoferrer.krotoplus.configP\001b\006proto3" }; com.google.protobuf.Descriptors.FileDescriptor.InternalDescriptorAssigner assigner = new com.google.protobuf.Descriptors.FileDescriptor. InternalDescriptorAssigner() { @@ -133,7 +141,7 @@ public com.google.protobuf.ExtensionRegistry assignDescriptors( internal_static_krotoplus_compiler_CompilerConfig_fieldAccessorTable = new com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( internal_static_krotoplus_compiler_CompilerConfig_descriptor, - new java.lang.String[] { "GrpcStubExts", "MockServices", "ProtoBuilders", "ExtendableMessages", "Insertions", "GeneratorScripts", }); + new java.lang.String[] { "GrpcStubExts", "MockServices", "ProtoBuilders", "ExtendableMessages", "Insertions", "GeneratorScripts", "GrpcCoroutines", }); internal_static_krotoplus_compiler_FileFilter_descriptor = getDescriptor().getMessageTypes().get(1); internal_static_krotoplus_compiler_FileFilter_fieldAccessorTable = new @@ -146,26 +154,32 @@ public com.google.protobuf.ExtensionRegistry assignDescriptors( com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( internal_static_krotoplus_compiler_GrpcStubExtsGenOptions_descriptor, new java.lang.String[] { "Filter", "SupportCoroutines", }); - internal_static_krotoplus_compiler_ProtoBuildersGenOptions_descriptor = + internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_descriptor = getDescriptor().getMessageTypes().get(3); + internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_fieldAccessorTable = new + com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( + internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_descriptor, + new java.lang.String[] { "Filter", }); + internal_static_krotoplus_compiler_ProtoBuildersGenOptions_descriptor = + getDescriptor().getMessageTypes().get(4); internal_static_krotoplus_compiler_ProtoBuildersGenOptions_fieldAccessorTable = new com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( internal_static_krotoplus_compiler_ProtoBuildersGenOptions_descriptor, new java.lang.String[] { "Filter", "UnwrapBuilders", "UseDslMarkers", }); internal_static_krotoplus_compiler_GeneratorScriptsGenOptions_descriptor = - getDescriptor().getMessageTypes().get(4); + getDescriptor().getMessageTypes().get(5); internal_static_krotoplus_compiler_GeneratorScriptsGenOptions_fieldAccessorTable = new com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( internal_static_krotoplus_compiler_GeneratorScriptsGenOptions_descriptor, new java.lang.String[] { "Filter", "ScriptPath", "ScriptBundle", }); internal_static_krotoplus_compiler_ExtenableMessagesGenOptions_descriptor = - getDescriptor().getMessageTypes().get(5); + getDescriptor().getMessageTypes().get(6); internal_static_krotoplus_compiler_ExtenableMessagesGenOptions_fieldAccessorTable = new com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( internal_static_krotoplus_compiler_ExtenableMessagesGenOptions_descriptor, new java.lang.String[] { "Filter", "CompanionFieldName", "CompanionClassName", "CompanionExtends", "CompanionImplements", }); internal_static_krotoplus_compiler_InsertionsGenOptions_descriptor = - getDescriptor().getMessageTypes().get(6); + getDescriptor().getMessageTypes().get(7); internal_static_krotoplus_compiler_InsertionsGenOptions_fieldAccessorTable = new com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( internal_static_krotoplus_compiler_InsertionsGenOptions_descriptor, @@ -177,7 +191,7 @@ public com.google.protobuf.ExtensionRegistry assignDescriptors( internal_static_krotoplus_compiler_InsertionsGenOptions_Entry_descriptor, new java.lang.String[] { "Point", "Content", "ScriptPath", "ScriptBundle", }); internal_static_krotoplus_compiler_MockServicesGenOptions_descriptor = - getDescriptor().getMessageTypes().get(7); + getDescriptor().getMessageTypes().get(8); internal_static_krotoplus_compiler_MockServicesGenOptions_fieldAccessorTable = new com.google.protobuf.GeneratedMessageV3.FieldAccessorTable( internal_static_krotoplus_compiler_MockServicesGenOptions_descriptor, diff --git a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptions.java b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptions.java new file mode 100644 index 0000000..6b87ca7 --- /dev/null +++ b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptions.java @@ -0,0 +1,663 @@ +// Generated by the protocol buffer compiler. DO NOT EDIT! +// source: krotoplus/compiler/config.proto + +package com.github.marcoferrer.krotoplus.config; + +/** + * 
    + * Configuration used by the 'gRPC Coroutines' code generator.
+ *
    + * + * Protobuf type {@code krotoplus.compiler.GrpcCoroutinesGenOptions} + */ +public final class GrpcCoroutinesGenOptions extends + com.google.protobuf.GeneratedMessageV3 implements + // @@protoc_insertion_point(message_implements:krotoplus.compiler.GrpcCoroutinesGenOptions) + GrpcCoroutinesGenOptionsOrBuilder { +private static final long serialVersionUID = 0L; + // Use GrpcCoroutinesGenOptions.newBuilder() to construct. + private GrpcCoroutinesGenOptions(com.google.protobuf.GeneratedMessageV3.Builder builder) { + super(builder); + } + private GrpcCoroutinesGenOptions() { + } + + @java.lang.Override + public final com.google.protobuf.UnknownFieldSet + getUnknownFields() { + return this.unknownFields; + } + private GrpcCoroutinesGenOptions( + com.google.protobuf.CodedInputStream input, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws com.google.protobuf.InvalidProtocolBufferException { + this(); + if (extensionRegistry == null) { + throw new java.lang.NullPointerException(); + } + int mutable_bitField0_ = 0; + com.google.protobuf.UnknownFieldSet.Builder unknownFields = + com.google.protobuf.UnknownFieldSet.newBuilder(); + try { + boolean done = false; + while (!done) { + int tag = input.readTag(); + switch (tag) { + case 0: + done = true; + break; + case 10: { + com.github.marcoferrer.krotoplus.config.FileFilter.Builder subBuilder = null; + if (filter_ != null) { + subBuilder = filter_.toBuilder(); + } + filter_ = input.readMessage(com.github.marcoferrer.krotoplus.config.FileFilter.parser(), extensionRegistry); + if (subBuilder != null) { + subBuilder.mergeFrom(filter_); + filter_ = subBuilder.buildPartial(); + } + + break; + } + default: { + if (!parseUnknownFieldProto3( + input, unknownFields, extensionRegistry, tag)) { + done = true; + } + break; + } + } + } + } catch (com.google.protobuf.InvalidProtocolBufferException e) { + throw e.setUnfinishedMessage(this); + } catch (java.io.IOException e) { + throw new com.google.protobuf.InvalidProtocolBufferException( + e).setUnfinishedMessage(this); + } finally { + this.unknownFields = unknownFields.build(); + makeExtensionsImmutable(); + } + } + public static final com.google.protobuf.Descriptors.Descriptor + getDescriptor() { + return com.github.marcoferrer.krotoplus.config.Config.internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_descriptor; + } + + @java.lang.Override + protected com.google.protobuf.GeneratedMessageV3.FieldAccessorTable + internalGetFieldAccessorTable() { + return com.github.marcoferrer.krotoplus.config.Config.internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_fieldAccessorTable + .ensureFieldAccessorsInitialized( + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.class, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder.class); + } + + public static final int FILTER_FIELD_NUMBER = 1; + private com.github.marcoferrer.krotoplus.config.FileFilter filter_; + /** + * 
    +   * Filter used for limiting the input files that are processed by the code generator
+   * The default filter will match true against all input files.
+   *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public boolean hasFilter() { + return filter_ != null; + } + /** + * 
    +   * Filter used for limiting the input files that are processed by the code generator
+   * The default filter will match true against all input files.
+   *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public com.github.marcoferrer.krotoplus.config.FileFilter getFilter() { + return filter_ == null ? com.github.marcoferrer.krotoplus.config.FileFilter.getDefaultInstance() : filter_; + } + /** + * 
    +   * Filter used for limiting the input files that are processed by the code generator
+   * The default filter will match true against all input files.
+   *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public com.github.marcoferrer.krotoplus.config.FileFilterOrBuilder getFilterOrBuilder() { + return getFilter(); + } + + private byte memoizedIsInitialized = -1; + @java.lang.Override + public final boolean isInitialized() { + byte isInitialized = memoizedIsInitialized; + if (isInitialized == 1) return true; + if (isInitialized == 0) return false; + + memoizedIsInitialized = 1; + return true; + } + + @java.lang.Override + public void writeTo(com.google.protobuf.CodedOutputStream output) + throws java.io.IOException { + if (filter_ != null) { + output.writeMessage(1, getFilter()); + } + unknownFields.writeTo(output); + } + + @java.lang.Override + public int getSerializedSize() { + int size = memoizedSize; + if (size != -1) return size; + + size = 0; + if (filter_ != null) { + size += com.google.protobuf.CodedOutputStream + .computeMessageSize(1, getFilter()); + } + size += unknownFields.getSerializedSize(); + memoizedSize = size; + return size; + } + + @java.lang.Override + public boolean equals(final java.lang.Object obj) { + if (obj == this) { + return true; + } + if (!(obj instanceof com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions)) { + return super.equals(obj); + } + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions other = (com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions) obj; + + boolean result = true; + result = result && (hasFilter() == other.hasFilter()); + if (hasFilter()) { + result = result && getFilter() + .equals(other.getFilter()); + } + result = result && unknownFields.equals(other.unknownFields); + return result; + } + + @java.lang.Override + public int hashCode() { + if (memoizedHashCode != 0) { + return memoizedHashCode; + } + int hash = 41; + hash = (19 * hash) + getDescriptor().hashCode(); + if (hasFilter()) { + hash = (37 * hash) + FILTER_FIELD_NUMBER; + hash = (53 * hash) + getFilter().hashCode(); + } + hash = (29 * hash) + unknownFields.hashCode(); + memoizedHashCode = hash; + return hash; + } + + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + java.nio.ByteBuffer data) + throws com.google.protobuf.InvalidProtocolBufferException { + return PARSER.parseFrom(data); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + java.nio.ByteBuffer data, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws com.google.protobuf.InvalidProtocolBufferException { + return PARSER.parseFrom(data, extensionRegistry); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + com.google.protobuf.ByteString data) + throws com.google.protobuf.InvalidProtocolBufferException { + return PARSER.parseFrom(data); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + com.google.protobuf.ByteString data, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws com.google.protobuf.InvalidProtocolBufferException { + return PARSER.parseFrom(data, extensionRegistry); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom(byte[] data) + throws com.google.protobuf.InvalidProtocolBufferException { + return PARSER.parseFrom(data); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + byte[] data, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws com.google.protobuf.InvalidProtocolBufferException { + return PARSER.parseFrom(data, extensionRegistry); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom(java.io.InputStream input) + throws java.io.IOException { + return com.google.protobuf.GeneratedMessageV3 + .parseWithIOException(PARSER, input); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + java.io.InputStream input, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws java.io.IOException { + return com.google.protobuf.GeneratedMessageV3 + .parseWithIOException(PARSER, input, extensionRegistry); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseDelimitedFrom(java.io.InputStream input) + throws java.io.IOException { + return com.google.protobuf.GeneratedMessageV3 + .parseDelimitedWithIOException(PARSER, input); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseDelimitedFrom( + java.io.InputStream input, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws java.io.IOException { + return com.google.protobuf.GeneratedMessageV3 + .parseDelimitedWithIOException(PARSER, input, extensionRegistry); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + com.google.protobuf.CodedInputStream input) + throws java.io.IOException { + return com.google.protobuf.GeneratedMessageV3 + .parseWithIOException(PARSER, input); + } + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parseFrom( + com.google.protobuf.CodedInputStream input, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws java.io.IOException { + return com.google.protobuf.GeneratedMessageV3 + .parseWithIOException(PARSER, input, extensionRegistry); + } + + @java.lang.Override + public Builder newBuilderForType() { return newBuilder(); } + public static Builder newBuilder() { + return DEFAULT_INSTANCE.toBuilder(); + } + public static Builder newBuilder(com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions prototype) { + return DEFAULT_INSTANCE.toBuilder().mergeFrom(prototype); + } + @java.lang.Override + public Builder toBuilder() { + return this == DEFAULT_INSTANCE + ? new Builder() : new Builder().mergeFrom(this); + } + + @java.lang.Override + protected Builder newBuilderForType( + com.google.protobuf.GeneratedMessageV3.BuilderParent parent) { + Builder builder = new Builder(parent); + return builder; + } + /** + * 
    +   * Configuration used by the 'gRPC Coroutines' code generator.
+   *
    + * + * Protobuf type {@code krotoplus.compiler.GrpcCoroutinesGenOptions} + */ + public static final class Builder extends + com.google.protobuf.GeneratedMessageV3.Builder implements + // @@protoc_insertion_point(builder_implements:krotoplus.compiler.GrpcCoroutinesGenOptions) + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptionsOrBuilder { + public static final com.google.protobuf.Descriptors.Descriptor + getDescriptor() { + return com.github.marcoferrer.krotoplus.config.Config.internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_descriptor; + } + + @java.lang.Override + protected com.google.protobuf.GeneratedMessageV3.FieldAccessorTable + internalGetFieldAccessorTable() { + return com.github.marcoferrer.krotoplus.config.Config.internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_fieldAccessorTable + .ensureFieldAccessorsInitialized( + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.class, com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.Builder.class); + } + + // Construct using com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.newBuilder() + private Builder() { + maybeForceBuilderInitialization(); + } + + private Builder( + com.google.protobuf.GeneratedMessageV3.BuilderParent parent) { + super(parent); + maybeForceBuilderInitialization(); + } + private void maybeForceBuilderInitialization() { + if (com.google.protobuf.GeneratedMessageV3 + .alwaysUseFieldBuilders) { + } + } + @java.lang.Override + public Builder clear() { + super.clear(); + if (filterBuilder_ == null) { + filter_ = null; + } else { + filter_ = null; + filterBuilder_ = null; + } + return this; + } + + @java.lang.Override + public com.google.protobuf.Descriptors.Descriptor + getDescriptorForType() { + return com.github.marcoferrer.krotoplus.config.Config.internal_static_krotoplus_compiler_GrpcCoroutinesGenOptions_descriptor; + } + + @java.lang.Override + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions getDefaultInstanceForType() { + return com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.getDefaultInstance(); + } + + @java.lang.Override + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions build() { + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions result = buildPartial(); + if (!result.isInitialized()) { + throw newUninitializedMessageException(result); + } + return result; + } + + @java.lang.Override + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions buildPartial() { + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions result = new com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions(this); + if (filterBuilder_ == null) { + result.filter_ = filter_; + } else { + result.filter_ = filterBuilder_.build(); + } + onBuilt(); + return result; + } + + @java.lang.Override + public Builder clone() { + return (Builder) super.clone(); + } + @java.lang.Override + public Builder setField( + com.google.protobuf.Descriptors.FieldDescriptor field, + java.lang.Object value) { + return (Builder) super.setField(field, value); + } + @java.lang.Override + public Builder clearField( + com.google.protobuf.Descriptors.FieldDescriptor field) { + return (Builder) super.clearField(field); + } + @java.lang.Override + public Builder clearOneof( + com.google.protobuf.Descriptors.OneofDescriptor oneof) { + return (Builder) super.clearOneof(oneof); + } + @java.lang.Override + public Builder setRepeatedField( + com.google.protobuf.Descriptors.FieldDescriptor field, + int index, java.lang.Object value) { + return (Builder) super.setRepeatedField(field, index, value); + } + @java.lang.Override + public Builder addRepeatedField( + com.google.protobuf.Descriptors.FieldDescriptor field, + java.lang.Object value) { + return (Builder) super.addRepeatedField(field, value); + } + @java.lang.Override + public Builder mergeFrom(com.google.protobuf.Message other) { + if (other instanceof com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions) { + return mergeFrom((com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions)other); + } else { + super.mergeFrom(other); + return this; + } + } + + public Builder mergeFrom(com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions other) { + if (other == com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions.getDefaultInstance()) return this; + if (other.hasFilter()) { + mergeFilter(other.getFilter()); + } + this.mergeUnknownFields(other.unknownFields); + onChanged(); + return this; + } + + @java.lang.Override + public final boolean isInitialized() { + return true; + } + + @java.lang.Override + public Builder mergeFrom( + com.google.protobuf.CodedInputStream input, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws java.io.IOException { + com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions parsedMessage = null; + try { + parsedMessage = PARSER.parsePartialFrom(input, extensionRegistry); + } catch (com.google.protobuf.InvalidProtocolBufferException e) { + parsedMessage = (com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions) e.getUnfinishedMessage(); + throw e.unwrapIOException(); + } finally { + if (parsedMessage != null) { + mergeFrom(parsedMessage); + } + } + return this; + } + + private com.github.marcoferrer.krotoplus.config.FileFilter filter_ = null; + private com.google.protobuf.SingleFieldBuilderV3< + com.github.marcoferrer.krotoplus.config.FileFilter, com.github.marcoferrer.krotoplus.config.FileFilter.Builder, com.github.marcoferrer.krotoplus.config.FileFilterOrBuilder> filterBuilder_; + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public boolean hasFilter() { + return filterBuilder_ != null || filter_ != null; + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public com.github.marcoferrer.krotoplus.config.FileFilter getFilter() { + if (filterBuilder_ == null) { + return filter_ == null ? com.github.marcoferrer.krotoplus.config.FileFilter.getDefaultInstance() : filter_; + } else { + return filterBuilder_.getMessage(); + } + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public Builder setFilter(com.github.marcoferrer.krotoplus.config.FileFilter value) { + if (filterBuilder_ == null) { + if (value == null) { + throw new NullPointerException(); + } + filter_ = value; + onChanged(); + } else { + filterBuilder_.setMessage(value); + } + + return this; + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public Builder setFilter( + com.github.marcoferrer.krotoplus.config.FileFilter.Builder builderForValue) { + if (filterBuilder_ == null) { + filter_ = builderForValue.build(); + onChanged(); + } else { + filterBuilder_.setMessage(builderForValue.build()); + } + + return this; + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public Builder mergeFilter(com.github.marcoferrer.krotoplus.config.FileFilter value) { + if (filterBuilder_ == null) { + if (filter_ != null) { + filter_ = + com.github.marcoferrer.krotoplus.config.FileFilter.newBuilder(filter_).mergeFrom(value).buildPartial(); + } else { + filter_ = value; + } + onChanged(); + } else { + filterBuilder_.mergeFrom(value); + } + + return this; + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public Builder clearFilter() { + if (filterBuilder_ == null) { + filter_ = null; + onChanged(); + } else { + filter_ = null; + filterBuilder_ = null; + } + + return this; + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public com.github.marcoferrer.krotoplus.config.FileFilter.Builder getFilterBuilder() { + + onChanged(); + return getFilterFieldBuilder().getBuilder(); + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + public com.github.marcoferrer.krotoplus.config.FileFilterOrBuilder getFilterOrBuilder() { + if (filterBuilder_ != null) { + return filterBuilder_.getMessageOrBuilder(); + } else { + return filter_ == null ? + com.github.marcoferrer.krotoplus.config.FileFilter.getDefaultInstance() : filter_; + } + } + /** + * 
    +     * Filter used for limiting the input files that are processed by the code generator
+     * The default filter will match true against all input files.
+     *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + private com.google.protobuf.SingleFieldBuilderV3< + com.github.marcoferrer.krotoplus.config.FileFilter, com.github.marcoferrer.krotoplus.config.FileFilter.Builder, com.github.marcoferrer.krotoplus.config.FileFilterOrBuilder> + getFilterFieldBuilder() { + if (filterBuilder_ == null) { + filterBuilder_ = new com.google.protobuf.SingleFieldBuilderV3< + com.github.marcoferrer.krotoplus.config.FileFilter, com.github.marcoferrer.krotoplus.config.FileFilter.Builder, com.github.marcoferrer.krotoplus.config.FileFilterOrBuilder>( + getFilter(), + getParentForChildren(), + isClean()); + filter_ = null; + } + return filterBuilder_; + } + @java.lang.Override + public final Builder setUnknownFields( + final com.google.protobuf.UnknownFieldSet unknownFields) { + return super.setUnknownFieldsProto3(unknownFields); + } + + @java.lang.Override + public final Builder mergeUnknownFields( + final com.google.protobuf.UnknownFieldSet unknownFields) { + return super.mergeUnknownFields(unknownFields); + } + + + // @@protoc_insertion_point(builder_scope:krotoplus.compiler.GrpcCoroutinesGenOptions) + } + + // @@protoc_insertion_point(class_scope:krotoplus.compiler.GrpcCoroutinesGenOptions) + private static final com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions DEFAULT_INSTANCE; + static { + DEFAULT_INSTANCE = new com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions(); + } + + public static com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions getDefaultInstance() { + return DEFAULT_INSTANCE; + } + + private static final com.google.protobuf.Parser + PARSER = new com.google.protobuf.AbstractParser() { + @java.lang.Override + public GrpcCoroutinesGenOptions parsePartialFrom( + com.google.protobuf.CodedInputStream input, + com.google.protobuf.ExtensionRegistryLite extensionRegistry) + throws com.google.protobuf.InvalidProtocolBufferException { + return new GrpcCoroutinesGenOptions(input, extensionRegistry); + } + }; + + public static com.google.protobuf.Parser parser() { + return PARSER; + } + + @java.lang.Override + public com.google.protobuf.Parser getParserForType() { + return PARSER; + } + + @java.lang.Override + public com.github.marcoferrer.krotoplus.config.GrpcCoroutinesGenOptions getDefaultInstanceForType() { + return DEFAULT_INSTANCE; + } + +} + diff --git a/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptionsOrBuilder.java b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptionsOrBuilder.java new file mode 100644 index 0000000..559309a --- /dev/null +++ b/protoc-gen-kroto-plus/src/main/generated/com/github/marcoferrer/krotoplus/config/GrpcCoroutinesGenOptionsOrBuilder.java @@ -0,0 +1,37 @@ +// Generated by the protocol buffer compiler. DO NOT EDIT! +// source: krotoplus/compiler/config.proto + +package com.github.marcoferrer.krotoplus.config; + +public interface GrpcCoroutinesGenOptionsOrBuilder extends + // @@protoc_insertion_point(interface_extends:krotoplus.compiler.GrpcCoroutinesGenOptions) + com.google.protobuf.MessageOrBuilder { + + /** + * 
    +   * Filter used for limiting the input files that are processed by the code generator
+   * The default filter will match true against all input files.
+   *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + boolean hasFilter(); + /** + * 
    +   * Filter used for limiting the input files that are processed by the code generator
+   * The default filter will match true against all input files.
+   *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + com.github.marcoferrer.krotoplus.config.FileFilter getFilter(); + /** + * 
    +   * Filter used for limiting the input files that are processed by the code generator
+   * The default filter will match true against all input files.
+   *
    + * + * .krotoplus.compiler.FileFilter filter = 1; + */ + com.github.marcoferrer.krotoplus.config.FileFilterOrBuilder getFilterOrBuilder(); +} diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/KrotoPlusProtoCMain.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/KrotoPlusProtoCMain.kt index 9ea8c4d..d173f3d 100644 --- a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/KrotoPlusProtoCMain.kt +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/KrotoPlusProtoCMain.kt @@ -16,6 +16,7 @@ fun main(args: Array) = runBlocking { val generators = listOf( GrpcStubExtsGenerator, + GrpcCoroutinesGenerator, ProtoBuildersGenerator, ExtendableMessagesGenerator, MockServicesGenerator, diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/Generator.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/Generator.kt index d6aaffe..f9b41a0 100644 --- a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/Generator.kt +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/Generator.kt @@ -1,5 +1,6 @@ package com.github.marcoferrer.krotoplus.generators +import com.github.marcoferrer.krotoplus.config.CompilerConfig import com.github.marcoferrer.krotoplus.script.ScriptManager import com.google.protobuf.compiler.PluginProtos import com.squareup.kotlinpoet.FileSpec @@ -39,17 +40,23 @@ val ScriptTemplateWithArgs.context: GeneratorContext val ScriptManager.context: GeneratorContext get() = contextInstance -internal fun initializeContext() { +fun initializeContext(compilerConfig: CompilerConfig? = null) { + compilerConfigOverride = compilerConfig contextInstance } +private var compilerConfigOverride: CompilerConfig? = null + private val contextInstance by lazy { val inputStream = System.getProperty("krotoplus.debug.request.src") ?.let { File(it).inputStream() } ?: System.`in` val protoRequest = PluginProtos.CodeGeneratorRequest.parseFrom(inputStream) - GeneratorContext(protoRequest) + + compilerConfigOverride + ?.let { GeneratorContext(protoRequest, config = it) } + ?: GeneratorContext(protoRequest) } diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcCoroutinesGenerator.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcCoroutinesGenerator.kt new file mode 100644 index 0000000..40aebc1 --- /dev/null +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcCoroutinesGenerator.kt @@ -0,0 +1,687 @@ +package com.github.marcoferrer.krotoplus.generators + +import com.github.marcoferrer.krotoplus.generators.Generator.Companion.AutoGenerationDisclaimer +import com.github.marcoferrer.krotoplus.proto.* +import com.github.marcoferrer.krotoplus.utils.* +import com.google.protobuf.compiler.PluginProtos +import com.squareup.kotlinpoet.* +import io.grpc.MethodDescriptor.* +import java.lang.IllegalStateException + + +object GrpcCoroutinesGenerator : Generator { + + override val isEnabled: Boolean + get() = context.config.grpcCoroutinesList.isNotEmpty() + + private const val serviceDelegateName = "ServiceDelegate" + + private val ProtoService.outerObjectName: String + get() = "${name}CoroutineGrpc" + + private val ProtoService.baseImplName: String + get() = "${name}ImplBase" + + private val ProtoService.serviceDelegateClassName: ClassName + get() = ClassName(protoFile.javaPackage, outerObjectName, baseImplName, serviceDelegateName) + + private val ProtoService.serviceJavaBaseImplClassName: ClassName + get() = enclosingServiceClassName.nestedClass("${name}ImplBase") + + private val ProtoService.stubName: String + get() = "${name}CoroutineStub" + + private val ProtoService.stubClassName: ClassName + get() = ClassName(protoFile.javaPackage, outerObjectName, stubName) + + + override fun invoke(): PluginProtos.CodeGeneratorResponse { + val responseBuilder = PluginProtos.CodeGeneratorResponse.newBuilder() + + val sendChannelMessageTypes = mutableListOf() + + for (service in context.schema.protoServices) { + + for (options in context.config.grpcCoroutinesList) { + + if (options.filter.matches(service.protoFile.name)) { + service.buildGrpcFileSpec()?.let { + responseBuilder.addFile(it.toResponseFileProto()) + } + + + sendChannelMessageTypes += service.getSendChannelMessageTypes() + } + } + } + + sendChannelMessageTypes + .buildSendChannelExtFiles() + .forEach { + responseBuilder.addFile(it.toResponseFileProto()) + } + + return responseBuilder.build() + } + + private fun ProtoService.buildGrpcFileSpec(): FileSpec? { + + val fileSpecBuilder = FileSpec + .builder(protoFile.javaPackage, outerObjectName) + .addComment(AutoGenerationDisclaimer) + .addType(buildOuterObject()) + + return fileSpecBuilder.build() + .takeIf { it.members.isNotEmpty() } + } + + private fun ProtoService.buildOuterObject(): TypeSpec = + TypeSpec.objectBuilder(outerObjectName) + .addAnnotation(protoFile.getGeneratedAnnotationSpec()) + .addFunction(buildNewStubMethod()) + .addType(buildClientStubImpl()) + .addType(buildServiceBaseImpl()) + .build() + + private fun ProtoService.buildServiceBaseImpl(): TypeSpec { + + val delegateValName = "delegate" + + val baseImplBuilder = TypeSpec.classBuilder(baseImplName) + .addModifiers(KModifier.ABSTRACT) + .addSuperinterface(CommonClassNames.bindableService) + .addSuperinterface(CommonClassNames.coroutineScope) + .addProperty( + PropertySpec + .builder("coroutineContext", CommonClassNames.coroutineContext) + .addModifiers(KModifier.OVERRIDE) + .addAnnotation(CommonClassNames.experimentalCoroutinesApi) + .getter( + FunSpec.getterBuilder() + .addCode("return %T.Default", CommonClassNames.dispatchers) + .build() + ) + .build() + ) + .addProperty( + PropertySpec + .builder(delegateValName, serviceDelegateClassName) + .addModifiers(KModifier.PRIVATE) + .initializer("%T()", serviceDelegateClassName) + .build() + ) + .addFunction( + FunSpec.builder("bindService") + .addModifiers(KModifier.OVERRIDE) + .returns(ClassName("io.grpc", "ServerServiceDefinition")) + .addCode("return %N.bindService()", delegateValName) + .build() + ) + .addFunctions(buildBaseImplRpcMethods()) + .addFunctions(buildResponseLambdaOverloads()) + .addType(buildServiceBaseImplDelegate()) + + return baseImplBuilder.build() + } + + + fun ProtoService.buildServiceBaseImplDelegate(): TypeSpec = + TypeSpec.classBuilder(serviceDelegateName) + .addModifiers(KModifier.PRIVATE, KModifier.INNER) + .superclass(serviceJavaBaseImplClassName) + .addFunctions(buildBaseImplRpcMethodDelegates()) + .build() + + fun ProtoMethod.buildUnaryBaseImpl(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.SUSPEND, KModifier.OPEN) + .addParameter( + ParameterSpec.builder("request", requestClassName) + .build() + ) + .returns(responseClassName) + .addCode( + CodeBlock.builder() + .addStatement( + "return %T(%T.%N())", + CommonClassNames.ServerCalls.serverCallUnimplementedUnary, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ).build() + ) + .build() + + + fun ProtoMethod.buildUnaryBaseImplDelegate(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.OVERRIDE) + .addParameter("request", requestClassName) + .addParameter( + "responseObserver", ParameterizedTypeName + .get(CommonClassNames.streamObserver, responseClassName) + ) + .addCode( + CodeBlock.builder() + .addStatement( + "%T(%T.%N(),responseObserver) {", + CommonClassNames.ServerCalls.serverCallUnary, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ) + .indent() + .addStatement("%N(request)", functionName) + .unindent() + .addStatement("}") + .build() + ) + .build() + + fun ProtoMethod.buildClientStreamingBaseImpl(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.SUSPEND, KModifier.OPEN) + .addParameter( + ParameterSpec.builder( + "requestChannel", ParameterizedTypeName + .get(CommonClassNames.receiveChannel, requestClassName) + ) + .build() + ) + .returns(responseClassName) + .addCode( + CodeBlock.builder() + .addStatement( + "return %T(%T.%N())", + CommonClassNames.ServerCalls.serverCallUnimplementedUnary, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ).build() + ) + .build() + + fun ProtoMethod.buildClientStreamingMethodBaseImplDelegate(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.OVERRIDE) + .addAnnotation(CommonClassNames.experimentalCoroutinesApi) + .returns(ParameterizedTypeName.get(CommonClassNames.streamObserver, requestClassName)) + .addParameter( + "responseObserver", ParameterizedTypeName + .get(CommonClassNames.streamObserver, responseClassName) + ) + .addCode( + CodeBlock.builder() + .addStatement( + "val requestObserver = %T(%T.%N(),responseObserver) { requestChannel: %T ->", + CommonClassNames.ServerCalls.serverCallClientStreaming, + protoService.enclosingServiceClassName, + methodDefinitionGetterName, + ParameterizedTypeName.get(CommonClassNames.receiveChannel, requestClassName) + ) + .indent() + .addStatement("%N(requestChannel)", functionName) + .unindent() + .addStatement("}") + .addStatement("return requestObserver") + .build() + ) + .build() + + fun ProtoMethod.buildServerStreamingBaseImpl(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.SUSPEND, KModifier.OPEN) + .addParameter( + ParameterSpec.builder("request", requestClassName) + .build() + ) + .addParameter( + ParameterSpec.builder( + "responseChannel", ParameterizedTypeName + .get(CommonClassNames.sendChannel, responseClassName) + ).build() + ) + .addCode( + CodeBlock.builder() + .addStatement( + "%T(%T.%N(),responseChannel)", + CommonClassNames.ServerCalls.serverCallUnimplementedStream, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ).build() + ) + .build() + + + fun ProtoMethod.buildServerStreamingMethodBaseImplDelegate(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.OVERRIDE) + .addAnnotation(CommonClassNames.obsoleteCoroutinesApi) + .addAnnotation(CommonClassNames.experimentalCoroutinesApi) + .addParameter("request", requestClassName) + .addParameter( + "responseObserver", ParameterizedTypeName + .get(CommonClassNames.streamObserver, responseClassName) + ) + .addCode( + CodeBlock.builder() + .addStatement( + "%T(%T.%N(),responseObserver) { responseChannel: %T ->", + CommonClassNames.ServerCalls.serverCallServerStreaming, + protoService.enclosingServiceClassName, + methodDefinitionGetterName, + ParameterizedTypeName.get(CommonClassNames.sendChannel, responseClassName) + ) + .indent() + .addStatement("%N(request, responseChannel)", functionName) + .unindent() + .addStatement("}") + .build() + ) + .build() + + fun ProtoMethod.buildBidiBaseImpl(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.SUSPEND, KModifier.OPEN) + .addParameter( + ParameterSpec.builder("requestChannel", ParameterizedTypeName + .get(CommonClassNames.receiveChannel, requestClassName)) + .build() + ) + .addParameter( + ParameterSpec.builder( + "responseChannel", ParameterizedTypeName + .get(CommonClassNames.sendChannel, responseClassName) + ).build() + ) + .addCode( + CodeBlock.builder() + .addStatement( + "%T(%T.%N(),responseChannel)", + CommonClassNames.ServerCalls.serverCallUnimplementedStream, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ).build() + ) + .build() + + + fun ProtoMethod.buildBidiMethodBaseImplDelegate(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.OVERRIDE) + .addAnnotation(CommonClassNames.obsoleteCoroutinesApi) + .addAnnotation(CommonClassNames.experimentalCoroutinesApi) + .returns(ParameterizedTypeName.get(CommonClassNames.streamObserver, requestClassName)) + .addParameter( + "responseObserver", ParameterizedTypeName + .get(CommonClassNames.streamObserver, responseClassName) + ) + .addCode( + CodeBlock.builder() + .addStatement( + "val requestChannel = %T(%T.%N(),responseObserver) { requestChannel: %T, responseChannel: %T ->", + CommonClassNames.ServerCalls.serverCallBidiStreaming, + protoService.enclosingServiceClassName, + methodDefinitionGetterName, + ParameterizedTypeName.get(CommonClassNames.receiveChannel, requestClassName), + ParameterizedTypeName.get(CommonClassNames.sendChannel, responseClassName) + ) + .indent() + .addStatement("%N(requestChannel, responseChannel)", functionName) + .unindent() + .addStatement("}") + .addStatement("return requestChannel") + .build() + ) + .build() + + fun ProtoService.buildBaseImplRpcMethods(): List = + methodDefinitions.map { method -> + when(method.type){ + MethodType.UNARY -> method.buildUnaryBaseImpl() + MethodType.CLIENT_STREAMING -> method.buildClientStreamingBaseImpl() + MethodType.SERVER_STREAMING -> method.buildServerStreamingBaseImpl() + MethodType.BIDI_STREAMING -> method.buildBidiBaseImpl() + MethodType.UNKNOWN -> throw IllegalStateException("Unknown method type") + } + } + + fun ProtoService.buildBaseImplRpcMethodDelegates(): List = + methodDefinitions.map { method -> + when(method.type){ + MethodType.UNARY -> method.buildUnaryBaseImplDelegate() + MethodType.CLIENT_STREAMING -> method.buildClientStreamingMethodBaseImplDelegate() + MethodType.SERVER_STREAMING -> method.buildServerStreamingMethodBaseImplDelegate() + MethodType.BIDI_STREAMING -> method.buildBidiMethodBaseImplDelegate() + MethodType.UNKNOWN -> throw IllegalStateException("Unknown method type") + } + } + + fun ProtoService.buildResponseLambdaOverloads(): List = + methodDefinitions.partition { it.isUnary || it.isClientStream } + .let { (completableResponseMethods, streamingResponseMethods) -> + + mutableListOf().apply { +// completableResponseMethods +// .distinctBy { it.responseType } +// .mapTo(this) { it.buildCompletableDeferredLambdaExt() } + + streamingResponseMethods + .distinctBy { it.responseType } + .mapTo(this) { it.buildChannelLambdaExt() } + } + } + + fun ProtoMethod.buildCompletableDeferredLambdaExt(): FunSpec { + + val receiverClassName = ParameterizedTypeName + .get(CommonClassNames.completableDeferred, responseClassName) + + val jvmNameSuffix = responseType.canonicalJavaName + .replace(responseType.javaPackage.orEmpty(), "") + .replace(".", "") + + return FunSpec.builder("complete") + .addModifiers(KModifier.INLINE) + .receiver(receiverClassName) + .addParameter( + "block", LambdaTypeName.get( + receiver = (responseType as ProtoMessage).builderClassName, + returnType = UNIT + ) + ) + .returns(BOOLEAN) + .addAnnotation( + AnnotationSpec + .builder(JvmName::class.asClassName()) + .addMember("\"complete$jvmNameSuffix\"") + .build() + ) + .addCode( + CodeBlock.builder() + .addStatement("val response = %T.newBuilder().apply(block).build()", responseClassName) + .addStatement("return complete(response)") + .build() + ) + .build() + } + + fun ProtoMethod.buildChannelLambdaExt(): FunSpec { + + val receiverClassName = ParameterizedTypeName + .get(CommonClassNames.sendChannel, responseClassName) + + val jvmNameSuffix = responseType.canonicalJavaName + .replace(responseType.javaPackage.orEmpty(), "") + .replace(".", "") + + return FunSpec.builder("send") + .addModifiers(KModifier.INLINE, KModifier.SUSPEND) + .receiver(receiverClassName) + .addParameter( + "block", LambdaTypeName.get( + receiver = (responseType as ProtoMessage).builderClassName, + returnType = UNIT + ) + ) + .addAnnotation( + AnnotationSpec + .builder(JvmName::class.asClassName()) + .addMember("\"send$jvmNameSuffix\"") + .build() + ) + .addCode( + CodeBlock.builder() + .addStatement("val response = %T.newBuilder().apply(block).build()", responseClassName) + .addStatement("send(response)") + .build() + ) + .build() + } + + fun ProtoService.buildClientStubImpl(): TypeSpec { + + val paramNameChannel = "channel" + val paramNameCallOptions = "callOptions" + + return TypeSpec.classBuilder(stubName) + .superclass( + ParameterizedTypeName.get( + ClassName("io.grpc.stub", "AbstractStub"), + stubClassName + ) + ) + .addSuperinterface(CommonClassNames.coroutineScope) + .addSuperclassConstructorParameter(paramNameChannel) + .addSuperclassConstructorParameter(paramNameCallOptions) + .primaryConstructor(FunSpec + .constructorBuilder() + .addModifiers(KModifier.PRIVATE) + .addParameter(paramNameChannel,CommonClassNames.grpcChannel) + .addParameter( + ParameterSpec + .builder(paramNameCallOptions,CommonClassNames.grpcCallOptions) + .defaultValue("%T.DEFAULT",CommonClassNames.grpcCallOptions) + .build() + ) + .build() + ) + .addProperty( + PropertySpec + .builder("coroutineContext", CommonClassNames.coroutineContext) + .addModifiers(KModifier.OVERRIDE) + .addAnnotation(CommonClassNames.experimentalCoroutinesApi) + .getter( + FunSpec.getterBuilder() + .addCode( + "return callOptions.getOption(%T) ?: %T.Unconfined", + ClassName(CommonPackages.krotoCoroutineLib,"CALL_OPTION_COROUTINE_CONTEXT"), + CommonClassNames.dispatchers + ) + .build() + ) + .build() + ) + .addFunction(FunSpec + .builder("build") + .addModifiers(KModifier.OVERRIDE) + .addParameter(paramNameChannel, CommonClassNames.grpcChannel ) + .addParameter(paramNameCallOptions, CommonClassNames.grpcCallOptions ) + .returns(stubClassName) + .addStatement("return %T(channel,callOptions)",stubClassName) + .build() + ) + .addFunctions(buildClientStubRpcMethods()) + .addFunctions(buildClientStubRpcRequestOverloads()) + .companionObject(buildClientStubCompanion()) + .build() + + } + + fun ProtoService.buildClientStubCompanion(): TypeSpec = + TypeSpec.companionObjectBuilder() + .addFunction( + FunSpec.builder("newStub") + .returns(stubClassName) + .addParameter("channel", CommonClassNames.grpcChannel) + .addCode("return %T(channel)", stubClassName) + .build() + ) + .addProperty( + PropertySpec.builder("SERVICE_NAME", String::class.asClassName()) + .addModifiers(KModifier.CONST) + .initializer("%T.SERVICE_NAME", enclosingServiceClassName) + .build() + ) + .build() + + fun ProtoService.buildNewStubMethod(): FunSpec = + FunSpec.builder("newStub") + .returns(stubClassName) + .addParameter("channel",CommonClassNames.grpcChannel) + .addCode("return %T.newStub(channel)",stubClassName) + .build() + + fun ProtoService.buildClientStubRpcMethods(): List = + methodDefinitions.map { method -> + when(method.type){ + MethodType.UNARY -> method.buildStubUnaryMethod() + MethodType.CLIENT_STREAMING -> method.buildStubClientStreamingMethod() + MethodType.SERVER_STREAMING -> method.buildStubServerStreamingMethod() + MethodType.BIDI_STREAMING -> method.buildStubBidiStreamingMethod() + MethodType.UNKNOWN -> throw IllegalStateException("Unknown method type") + } + } + + fun ProtoMethod.buildStubBidiStreamingMethod(): FunSpec = + FunSpec.builder(functionName) + .addAnnotation(buildRpcMethodAnnotation()) + .addAnnotation(CommonClassNames.obsoleteCoroutinesApi) + .returns(ParameterizedTypeName.get( + CommonClassNames.ClientChannels.clientBidiCallChannel, + requestClassName, + responseClassName) + ) + .addStatement( + "return %T(%T.%N())", + CommonClassNames.ClientCalls.clientCallBidiStreaming, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ) + .build() + + fun ProtoMessage.buildSendChannelLambdaExt(suffix: String = ""): FunSpec { + + val jvmNameSuffix = canonicalJavaName + .replace(javaPackage.orEmpty(), "") + .replace(".", "") + suffix + + return FunSpec.builder("send") + .addModifiers(KModifier.INLINE, KModifier.SUSPEND) + .addAnnotation( + AnnotationSpec + .builder(JvmName::class.asClassName()) + .addMember("\"send$jvmNameSuffix\"") + .build() + ) + .receiver(ParameterizedTypeName.get(CommonClassNames.sendChannel, className)) + .addParameter( + "block", LambdaTypeName.get( + receiver = className.nestedClass("Builder"), + returnType = UNIT + ) + ) + .addStatement("val request = %T.newBuilder().apply(block).build()", className) + .addStatement("send(request)") + .build() + } + + fun ProtoService.buildSendChannelOverloads(): List = + getSendChannelMessageTypes() + .map { it.buildSendChannelLambdaExt() } + + fun ProtoService.getSendChannelMessageTypes(): List = + methodDefinitions + .asSequence() + .filter { it.isClientStream || it.isBidi } + .distinctBy { it.requestType } + .mapNotNull { (it.requestType as? ProtoMessage) } + .toList() + + fun List.buildSendChannelExtFiles(): List = + distinct() + .groupBy( { it.protoFile }, { it.buildSendChannelLambdaExt() }) + .map { (protoFile, funSpecs) -> + + FileSpec.builder(protoFile.javaPackage,"${protoFile.javaOuterClassname}GrpcExts") + .addFunctions(funSpecs) + .build() + } + + fun ProtoService.buildClientStubRpcRequestOverloads(): List = + methodDefinitions.mapNotNull { + when(it.type){ + MethodType.UNARY -> it.buildStubUnaryMethodOverload() + MethodType.SERVER_STREAMING -> it.buildStubServerStreamingMethodOverload() + else -> null + } + } + + fun ProtoMethod.buildRpcMethodAnnotation(): AnnotationSpec = + AnnotationSpec.builder(ClassName("io.grpc.stub.annotations","RpcMethod")) + .addMember("fullMethodName = \"\$SERVICE_NAME/${descriptorProto.name}\"") + .addMember("requestType = %T::class", requestClassName) + .addMember("responseType = %T::class", responseClassName) + .addMember("methodType = %T.%N", MethodType::class, type.name) + .build() + + fun ProtoMethod.buildStubUnaryMethod(): FunSpec = + FunSpec.builder(functionName) + .addAnnotation(buildRpcMethodAnnotation()) + .addModifiers(KModifier.SUSPEND) + .returns(responseClassName) + .addParameter("request",requestClassName) + .addStatement( + "return %T(request, %T.%N())", + CommonClassNames.ClientCalls.clientCallUnary, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ) + .build() + + fun ProtoMethod.buildStubUnaryMethodOverload(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.SUSPEND, KModifier.INLINE) + .returns(responseClassName) + .addParameter("block", LambdaTypeName.get( + receiver = requestClassName.nestedClass("Builder"), + returnType = UNIT + )) + .addStatement("val request = %T.newBuilder().apply(block).build()",requestClassName) + .addStatement("return %N(request)",functionName) + .build() + + + fun ProtoMethod.buildStubServerStreamingMethodOverload(): FunSpec = + FunSpec.builder(functionName) + .addModifiers(KModifier.INLINE) + .returns(ParameterizedTypeName.get(CommonClassNames.receiveChannel,responseClassName)) + .addParameter("block", LambdaTypeName.get( + receiver = requestClassName.nestedClass("Builder"), + returnType = UNIT + )) + .addStatement("val request = %T.newBuilder().apply(block).build()",requestClassName) + .addStatement("return %N(request)",functionName) + .build() + + fun ProtoMethod.buildStubClientStreamingMethod(): FunSpec = + FunSpec.builder(functionName) + .addAnnotation(buildRpcMethodAnnotation()) + .addAnnotation(CommonClassNames.obsoleteCoroutinesApi) + .returns(ParameterizedTypeName.get( + CommonClassNames.ClientChannels.clientStreamingCallChannel, + requestClassName, + responseClassName) + ) + .addStatement( + "return %T(%T.%N())", + CommonClassNames.ClientCalls.clientCallClientStreaming, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ) + .build() + + + fun ProtoMethod.buildStubServerStreamingMethod(): FunSpec = + FunSpec.builder(functionName) + .addAnnotation(buildRpcMethodAnnotation()) +// .addAnnotation(CommonClassNames.obsoleteCoroutinesApi) + .returns(ParameterizedTypeName.get(CommonClassNames.receiveChannel, responseClassName)) + .addParameter("request",requestClassName) + .addStatement( + "return %T(request, %T.%N())", + CommonClassNames.ClientCalls.clientCallServerStreaming, + protoService.enclosingServiceClassName, + methodDefinitionGetterName + ) + .build() + +} + diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcStubExtsGenerator.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcStubExtsGenerator.kt index c07d145..93e9e74 100644 --- a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcStubExtsGenerator.kt +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/generators/GrpcStubExtsGenerator.kt @@ -4,6 +4,7 @@ import com.github.marcoferrer.krotoplus.config.GrpcStubExtsGenOptions import com.github.marcoferrer.krotoplus.generators.Generator.Companion.AutoGenerationDisclaimer import com.github.marcoferrer.krotoplus.proto.ProtoMethod import com.github.marcoferrer.krotoplus.proto.ProtoService +import com.github.marcoferrer.krotoplus.utils.CommonClassNames import com.github.marcoferrer.krotoplus.utils.matches import com.google.protobuf.compiler.PluginProtos import com.squareup.kotlinpoet.* @@ -183,8 +184,8 @@ object GrpcStubExtsGenerator : Generator { FunSpec.builder(method.functionName) .receiver(method.protoService.asyncStubClassName) - .addAnnotation(ClassName("kotlinx.coroutines", "ObsoleteCoroutinesApi")) - .addAnnotation(ClassName("kotlinx.coroutines", "ExperimentalCoroutinesApi")) + .addAnnotation(CommonClassNames.obsoleteCoroutinesApi) + .addAnnotation(CommonClassNames.experimentalCoroutinesApi) .addAnnotation( ClassName( "com.github.marcoferrer.krotoplus.coroutines", diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/proto/ProtoMethod.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/proto/ProtoMethod.kt index b06ba5f..e9ebaf2 100644 --- a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/proto/ProtoMethod.kt +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/proto/ProtoMethod.kt @@ -1,6 +1,10 @@ package com.github.marcoferrer.krotoplus.proto import com.google.protobuf.DescriptorProtos +import com.squareup.kotlinpoet.AnnotationSpec +import com.squareup.kotlinpoet.ClassName +import com.squareup.kotlinpoet.asClassName +import io.grpc.MethodDescriptor class ProtoMethod( override val descriptorProto: DescriptorProtos.MethodDescriptorProto, @@ -9,6 +13,8 @@ class ProtoMethod( val functionName = descriptorProto.name.decapitalize() + val methodDefinitionGetterName = "get${descriptorProto.name}Method" + val requestType = protoService.protoFile.schema.protoTypes[descriptorProto.inputType] ?: throw IllegalStateException("${descriptorProto.inputType} was not found in schema type map.") @@ -31,4 +37,12 @@ class ProtoMethod( val isClientStream get() = descriptorProto.clientStreaming && !descriptorProto.serverStreaming + val type: MethodDescriptor.MethodType + get() = when{ + isUnary -> MethodDescriptor.MethodType.UNARY + isBidi -> MethodDescriptor.MethodType.BIDI_STREAMING + isServerStream -> MethodDescriptor.MethodType.SERVER_STREAMING + isClientStream -> MethodDescriptor.MethodType.CLIENT_STREAMING + else -> throw IllegalStateException("Unknown method type") + } } \ No newline at end of file diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/CommonNames.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/CommonNames.kt new file mode 100644 index 0000000..34ad3f1 --- /dev/null +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/CommonNames.kt @@ -0,0 +1,61 @@ +package com.github.marcoferrer.krotoplus.utils + +import com.github.marcoferrer.krotoplus.utils.CommonPackages.kotlinxCoroutines +import com.github.marcoferrer.krotoplus.utils.CommonPackages.krotoCoroutineLib +import com.squareup.kotlinpoet.ClassName +import com.squareup.kotlinpoet.asClassName +import io.grpc.BindableService +import kotlinx.coroutines.CompletableDeferred +import kotlinx.coroutines.CoroutineScope +import kotlinx.coroutines.Dispatchers +import kotlinx.coroutines.channels.ReceiveChannel +import kotlinx.coroutines.channels.SendChannel +import kotlin.coroutines.CoroutineContext + + +object CommonClassNames{ + + val bindableService: ClassName = BindableService::class.asClassName() + val coroutineScope: ClassName = CoroutineScope::class.asClassName() + val coroutineContext: ClassName = CoroutineContext::class.asClassName() + val receiveChannel: ClassName = ReceiveChannel::class.asClassName() + val sendChannel: ClassName = SendChannel::class.asClassName() + val dispatchers: ClassName = Dispatchers::class.asClassName() + val completableDeferred: ClassName = CompletableDeferred::class.asClassName() + val streamObserver: ClassName = ClassName("io.grpc.stub", "StreamObserver") + val serverCalls = ClassName(krotoCoroutineLib,"ServerCalls") + val launch: ClassName = ClassName(kotlinxCoroutines,"launch") + val grpcChannel: ClassName = ClassName("io.grpc","Channel") + val grpcCallOptions: ClassName = ClassName("io.grpc","CallOptions") + val grpcContextElement: ClassName = ClassName(krotoCoroutineLib,"GrpcContextElement") + val obsoleteCoroutinesApi: ClassName = ClassName(kotlinxCoroutines, "ObsoleteCoroutinesApi") + val experimentalCoroutinesApi: ClassName = ClassName(kotlinxCoroutines, "ExperimentalCoroutinesApi") + + object ClientCalls { + val clientCallUnary: ClassName = ClassName("$krotoCoroutineLib.client", "clientCallUnary") + val clientCallServerStreaming: ClassName = ClassName("$krotoCoroutineLib.client", "clientCallServerStreaming") + val clientCallBidiStreaming: ClassName = ClassName("$krotoCoroutineLib.client", "clientCallBidiStreaming") + val clientCallClientStreaming: ClassName = ClassName("$krotoCoroutineLib.client", "clientCallClientStreaming") + } + + object ClientChannels { + val clientBidiCallChannel: ClassName = ClassName("$krotoCoroutineLib.client", "ClientBidiCallChannel") + val clientStreamingCallChannel: ClassName = ClassName("$krotoCoroutineLib.client", "ClientStreamingCallChannel") + } + + object ServerCalls { + + val serverCallUnary = ClassName("$krotoCoroutineLib.server","serverCallUnary") + val serverCallClientStreaming = ClassName("$krotoCoroutineLib.server","serverCallClientStreaming") + val serverCallServerStreaming = ClassName("$krotoCoroutineLib.server","serverCallServerStreaming") + val serverCallBidiStreaming = ClassName("$krotoCoroutineLib.server","serverCallBidiStreaming") + val serverCallUnimplementedUnary = ClassName("$krotoCoroutineLib.server","serverCallUnimplementedUnary") + val serverCallUnimplementedStream = ClassName("$krotoCoroutineLib.server","serverCallUnimplementedStream") + } +} + +object CommonPackages { + + const val krotoCoroutineLib = "com.github.marcoferrer.krotoplus.coroutines" + const val kotlinxCoroutines = "kotlinx.coroutines" +} \ No newline at end of file diff --git a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/Memoize.kt b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/Memoize.kt index 9bcdcca..157e677 100644 --- a/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/Memoize.kt +++ b/protoc-gen-kroto-plus/src/main/kotlin/com/github/marcoferrer/krotoplus/utils/Memoize.kt @@ -7,4 +7,14 @@ class Memoize1(val f: (T) -> R) : (T) -> R { } } -fun ((T) -> R).memoize(): (T) -> R = Memoize1(this) \ No newline at end of file +class MemoizeExt1(val f: T.() -> R){ + private val values = mutableMapOf() + operator fun T.invoke(): R { + return values.getOrPut(this) { this.f() } + } +} + + +fun ((T) -> R).memoize(): (T) -> R = Memoize1(this) + +fun (T.() -> R).memoizeExt(): MemoizeExt1 = MemoizeExt1(this) \ No newline at end of file diff --git a/protoc-gen-kroto-plus/src/main/proto/krotoplus/compiler/config.proto b/protoc-gen-kroto-plus/src/main/proto/krotoplus/compiler/config.proto index 08a4135..ee227e1 100644 --- a/protoc-gen-kroto-plus/src/main/proto/krotoplus/compiler/config.proto +++ b/protoc-gen-kroto-plus/src/main/proto/krotoplus/compiler/config.proto @@ -33,6 +33,8 @@ message CompilerConfig { // Configuration entries for the 'Generator Scripts' code generator. repeated GeneratorScriptsGenOptions generator_scripts = 25; + // Configuration entries for the 'Grpc Coroutines' code generator. + repeated GrpcCoroutinesGenOptions grpc_coroutines = 26; } // Represent a filter used for including and excluding source files from @@ -69,6 +71,15 @@ message GrpcStubExtsGenOptions{ } +// Configuration used by the 'gRPC Coroutines' code generator. +message GrpcCoroutinesGenOptions { + + // Filter used for limiting the input files that are processed by the code generator + // The default filter will match true against all input files. + FileFilter filter = 1; + +} + // Configuration used by the 'Proto Builders' code generator. message ProtoBuildersGenOptions { diff --git a/settings.gradle b/settings.gradle index dca14c1..35b8a5d 100644 --- a/settings.gradle +++ b/settings.gradle @@ -8,9 +8,11 @@ pluginManagement{ } include 'protoc-gen-kroto-plus' +include 'protoc-gen-grpc-coroutines' include 'protoc-gen-kroto-plus:docs' include 'kroto-plus-message' include 'kroto-plus-coroutines' +include 'kroto-plus-coroutines:benchmark' include 'kroto-plus-gradle-plugin' include 'kroto-plus-gradle-plugin:gen-config-dsl' include 'kroto-plus-test' \ No newline at end of file From f3c02676275cef5c11546dac4c684794f4a56814 Mon Sep 17 00:00:00 2001 From: Marco Ferrer <35935108+marcoferrer@users.noreply.github.com> Date: Thu, 3 Jan 2019 23:13:06 -0500 Subject: [PATCH 6/6] update changelog and readme for RC1 --- CHANGELOG.md | 9 +- README.md | 14 +- build.gradle | 2 +- docs/html/kroto-plus-config.html | 3857 +---------------------- docs/markdown/kroto-plus-config.md | 2157 ------------- example-project/build.gradle | 2 +- protoc-gen-kroto-plus/docs/build.gradle | 15 +- 7 files changed, 40 insertions(+), 6016 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 622675f..219a045 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,10 +9,17 @@ _2018-01-03_ #### Coroutines * New: Benchmark implementation of gRPC coroutines * New: Experimental global dispatcher ```Dispatchers.Grpc``` -* New: ```SendChannel``` utility api ```CoroutineScope.launchProducerJob``` +* New: ```SendChannel``` utility api ```CoroutineScope.launchProducerJob``` +* Fix: Lowered byte code target for Android compatibility * Deprecated: ```InboundStreamChannel``` in favor of new stub APIs * Deprecated: ```ServerBidiCallChannel``` in favor of new stub APIs +#### Proto Builders (DSL) +* Fix: Nested messages are now tagged with ```@DslMarker``` annotation + +#### Community Scripts +* New: ```grpc-gateway``` entry point generation script + ## Version 0.2.1 _2018-11-02_ * Fix: Address regression in file filter matching diff --git a/README.md b/README.md index 9b15b23..1b6005d 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,7 @@ ### Community Contributions are Welcomed -## Quick Start: +## Quick Start: gRPC Coroutines Run the following command to get started with a preconfigured template project. (_[kotlin-coroutines-gRPC-template](https://github.com/marcoferrer/kotlin-coroutines-gRPC-template)_) ```bash git clone https://github.com/marcoferrer/kotlin-coroutines-gRPC-template && \ @@ -17,15 +17,12 @@ cd kotlin-coroutines-gRPC-template && \ ./gradlew run ``` -## Version 0.2.1 +## Version 0.2.2-RC1 * [CHANGELOG](https://github.com/marcoferrer/kroto-plus/blob/master/CHANGELOG.md) * Most notable changes - * Update to Kotlin 1.3.0 - * Update to Coroutines 1.0.0 - * Builder DSL support and safety via Kotlin's ```@DslMarker``` annotation + * Full Client & Server Stub Generation 🎉 ## Coming Soon - * Full Client & Server Stub Generation 🎉 * New gradle configuration dsl * Windows executable @@ -86,6 +83,11 @@ The generated extensions allow composition of proto messages in a dsl style. Sup } ``` +### gRPC Coroutines Client & Server +#### [Configuration Options]() +__Docs Coming Soon__ + + ### gRPC Stub Extensions #### [Configuration Options](https://github.com/marcoferrer/kroto-plus/blob/master/protoc-gen-kroto-plus/src/main/proto/krotoplus/compiler/config.proto#L61) diff --git a/build.gradle b/build.gradle index 27459da..8012bae 100644 --- a/build.gradle +++ b/build.gradle @@ -23,7 +23,7 @@ buildscript { } plugins{ - id 'com.google.protobuf' version '0.8.7' apply false + id 'com.google.protobuf' version '0.8.6' apply false id 'org.jetbrains.kotlin.jvm' version '1.3.11' apply false id "com.jfrog.bintray" version "1.8.4" apply false id "com.jfrog.artifactory" version "4.8.1" apply false diff --git a/docs/html/kroto-plus-config.html b/docs/html/kroto-plus-config.html index 688aa1f..4775ecc 100644 --- a/docs/html/kroto-plus-config.html +++ b/docs/html/kroto-plus-config.html @@ -175,456 +175,52 @@

    Table of Contents

  • - google/protobuf/any.proto -
      - -
    • - MAny -
      • - - - - -
    -
    • - - -
  • - google/protobuf/api.proto - -
    • - - -
  • - google/protobuf/compiler/plugin.proto - -
    • - - -
  • - google/protobuf/descriptor.proto - -
    • - - -
  • - google/protobuf/duration.proto - -
    • - - -
  • - google/protobuf/empty.proto - -
    • - - -
  • - google/protobuf/field_mask.proto - -
    • - - -
  • - google/protobuf/source_context.proto - -
    • - - -
  • - google/protobuf/struct.proto + krotoplus/compiler/config.proto -
    • - - -
  • - google/protobuf/timestamp.proto - -
    • - - -
  • - google/protobuf/type.proto - -
    • - - -
  • - google/protobuf/wrappers.proto - -
    • - - -
  • - krotoplus/compiler/config.proto -
      - -
    • - MCompilerConfig -
      • - -
    • - MExtenableMessagesGenOptions -
      • - -
    • - MFileFilter -
      • - -
    • - MGeneratorScriptsGenOptions -
      • - -
    • - MGrpcCoroutinesGenOptions -
      • - -
    • - MGrpcStubExtsGenOptions -
      • - -
    • - MInsertionsGenOptions -
      • - -
    • - MInsertionsGenOptions.Entry -
      • - -
    • - MMockServicesGenOptions -
      • - -
    • - MProtoBuildersGenOptions -
      • - - -
    • - EInsertionPoint + EInsertionPoint
      • @@ -638,3435 +234,6 @@

      Table of Contents

      -
      -

      google/protobuf/any.proto

      Top -
      -

      - - -

      Any

      -

      `Any` contains an arbitrary serialized protocol buffer message along with a

      URL that describes the type of the serialized message.

      Protobuf library provides support to pack/unpack Any values in the form

      of utility functions or additional generated methods of the Any type.

      Example 1: Pack and unpack a message in C++.

      Foo foo = ...;

      Any any;

      any.PackFrom(foo);

      ...

      if (any.UnpackTo(&foo)) {

      ...

      }

      Example 2: Pack and unpack a message in Java.

      Foo foo = ...;

      Any any = Any.pack(foo);

      ...

      if (any.is(Foo.class)) {

      foo = any.unpack(Foo.class);

      }

      Example 3: Pack and unpack a message in Python.

      foo = Foo(...)

      any = Any()

      any.Pack(foo)

      ...

      if any.Is(Foo.DESCRIPTOR):

      any.Unpack(foo)

      ...

      Example 4: Pack and unpack a message in Go

      foo := &pb.Foo{...}

      any, err := ptypes.MarshalAny(foo)

      ...

      foo := &pb.Foo{}

      if err := ptypes.UnmarshalAny(any, foo); err != nil {

      ...

      }

      The pack methods provided by protobuf library will by default use

      'type.googleapis.com/full.type.name' as the type URL and the unpack

      methods only use the fully qualified type name after the last '/'

      in the type URL, for example "foo.bar.com/x/y.z" will yield type

      name "y.z".

      JSON

      ====

      The JSON representation of an `Any` value uses the regular

      representation of the deserialized, embedded message, with an

      additional field `@type` which contains the type URL. Example:

      package google.profile;

      message Person {

      string first_name = 1;

      string last_name = 2;

      }

      {

      "@type": "type.googleapis.com/google.profile.Person",

      "firstName": ,

      "lastName":

      }

      If the embedded message type is well-known and has a custom JSON

      representation, that representation will be embedded adding a field

      `value` which holds the custom JSON in addition to the `@type`

      field. Example (for message [google.protobuf.Duration][]):

      {

      "@type": "type.googleapis.com/google.protobuf.Duration",

      "value": "1.212s"

      }

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      type_urlstring

      A URL/resource name that uniquely identifies the type of the serialized -protocol buffer message. The last segment of the URL's path must represent -the fully qualified name of the type (as in -`path/google.protobuf.Duration`). The name should be in a canonical form -(e.g., leading "." is not accepted). - -In practice, teams usually precompile into the binary all types that they -expect it to use in the context of Any. However, for URLs which use the -scheme `http`, `https`, or no scheme, one can optionally set up a type -server that maps type URLs to message definitions as follows: - -* If no scheme is provided, `https` is assumed. -* An HTTP GET on the URL must yield a [google.protobuf.Type][] - value in binary format, or produce an error. -* Applications are allowed to cache lookup results based on the - URL, or have them precompiled into a binary to avoid any - lookup. Therefore, binary compatibility needs to be preserved - on changes to types. (Use versioned type names to manage - breaking changes.) - -Note: this functionality is not currently available in the official -protobuf release, and it is not used for type URLs beginning with -type.googleapis.com. - -Schemes other than `http`, `https` (or the empty scheme) might be -used with implementation specific semantics.

      valuebytes

      Must be a valid serialized protocol buffer of the above specified type.

      - - - - - - - - - - - - -
      -

      google/protobuf/api.proto

      Top -
      -

      - - -

      Api

      -

      Api is a light-weight descriptor for an API Interface.

      Interfaces are also described as "protocol buffer services" in some contexts,

      such as by the "service" keyword in a .proto file, but they are different

      from API Services, which represent a concrete implementation of an interface

      as opposed to simply a description of methods and bindings. They are also

      sometimes simply referred to as "APIs" in other contexts, such as the name of

      this message itself. See https://cloud.google.com/apis/design/glossary for

      detailed terminology.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestring

      The fully qualified name of this interface, including package name -followed by the interface's simple name.

      methodsMethodrepeated

      The methods of this interface, in unspecified order.

      optionsOptionrepeated

      Any metadata attached to the interface.

      versionstring

      A version string for this interface. If specified, must have the form -`major-version.minor-version`, as in `1.10`. If the minor version is -omitted, it defaults to zero. If the entire version field is empty, the -major version is derived from the package name, as outlined below. If the -field is not empty, the version in the package name will be verified to be -consistent with what is provided here. - -The versioning schema uses [semantic -versioning](http://semver.org) where the major version number -indicates a breaking change and the minor version an additive, -non-breaking change. Both version numbers are signals to users -what to expect from different versions, and should be carefully -chosen based on the product plan. - -The major version is also reflected in the package name of the -interface, which must end in `v<major-version>`, as in -`google.feature.v1`. For major versions 0 and 1, the suffix can -be omitted. Zero major versions must only be used for -experimental, non-GA interfaces.

      source_contextSourceContext

      Source context for the protocol buffer service represented by this -message.

      mixinsMixinrepeated

      Included interfaces. See [Mixin][].

      syntaxSyntax

      The source syntax of the service.

      - - - - -

      Method

      -

      Method represents a method of an API interface.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestring

      The simple name of this method.

      request_type_urlstring

      A URL of the input message type.

      request_streamingbool

      If true, the request is streamed.

      response_type_urlstring

      The URL of the output message type.

      response_streamingbool

      If true, the response is streamed.

      optionsOptionrepeated

      Any metadata attached to the method.

      syntaxSyntax

      The source syntax of this method.

      - - - - -

      Mixin

      -

      Declares an API Interface to be included in this interface. The including

      interface must redeclare all the methods from the included interface, but

      documentation and options are inherited as follows:

      - If after comment and whitespace stripping, the documentation

      string of the redeclared method is empty, it will be inherited

      from the original method.

      - Each annotation belonging to the service config (http,

      visibility) which is not set in the redeclared method will be

      inherited.

      - If an http annotation is inherited, the path pattern will be

      modified as follows. Any version prefix will be replaced by the

      version of the including interface plus the [root][] path if

      specified.

      Example of a simple mixin:

      package google.acl.v1;

      service AccessControl {

      // Get the underlying ACL object.

      rpc GetAcl(GetAclRequest) returns (Acl) {

      option (google.api.http).get = "/v1/{resource=**}:getAcl";

      }

      }

      package google.storage.v2;

      service Storage {

      rpc GetAcl(GetAclRequest) returns (Acl);

      // Get a data record.

      rpc GetData(GetDataRequest) returns (Data) {

      option (google.api.http).get = "/v2/{resource=**}";

      }

      }

      Example of a mixin configuration:

      apis:

      - name: google.storage.v2.Storage

      mixins:

      - name: google.acl.v1.AccessControl

      The mixin construct implies that all methods in `AccessControl` are

      also declared with same name and request/response types in

      `Storage`. A documentation generator or annotation processor will

      see the effective `Storage.GetAcl` method after inherting

      documentation and annotations as follows:

      service Storage {

      // Get the underlying ACL object.

      rpc GetAcl(GetAclRequest) returns (Acl) {

      option (google.api.http).get = "/v2/{resource=**}:getAcl";

      }

      ...

      }

      Note how the version in the path pattern changed from `v1` to `v2`.

      If the `root` field in the mixin is specified, it should be a

      relative path under which inherited HTTP paths are placed. Example:

      apis:

      - name: google.storage.v2.Storage

      mixins:

      - name: google.acl.v1.AccessControl

      root: acls

      This implies the following inherited HTTP annotation:

      service Storage {

      // Get the underlying ACL object.

      rpc GetAcl(GetAclRequest) returns (Acl) {

      option (google.api.http).get = "/v2/acls/{resource=**}:getAcl";

      }

      ...

      }

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestring

      The fully qualified name of the interface which is included.

      rootstring

      If non-empty specifies a path under which inherited HTTP paths -are rooted.

      - - - - - - - - - - - - -
      -

      google/protobuf/compiler/plugin.proto

      Top -
      -

      - - -

      CodeGeneratorRequest

      -

      An encoded CodeGeneratorRequest is written to the plugin's stdin.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      file_to_generatestringrepeated

      The .proto files that were explicitly listed on the command-line. The -code generator should generate code only for these files. Each file's -descriptor will be included in proto_file, below.

      parameterstringoptional

      The generator parameter passed on the command-line.

      proto_filegoogle.protobuf.FileDescriptorProtorepeated

      FileDescriptorProtos for all files in files_to_generate and everything -they import. The files will appear in topological order, so each file -appears before any file that imports it. - -protoc guarantees that all proto_files will be written after -the fields above, even though this is not technically guaranteed by the -protobuf wire format. This theoretically could allow a plugin to stream -in the FileDescriptorProtos and handle them one by one rather than read -the entire set into memory at once. However, as of this writing, this -is not similarly optimized on protoc's end -- it will store all fields in -memory at once before sending them to the plugin. - -Type names of fields and extensions in the FileDescriptorProto are always -fully qualified.

      compiler_versionVersionoptional

      The version number of protocol compiler.

      - - - - -

      CodeGeneratorResponse

      -

      The plugin writes an encoded CodeGeneratorResponse to stdout.

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      errorstringoptional

      Error message. If non-empty, code generation failed. The plugin process -should exit with status code zero even if it reports an error in this way. - -This should be used to indicate errors in .proto files which prevent the -code generator from generating correct code. Errors which indicate a -problem in protoc itself -- such as the input CodeGeneratorRequest being -unparseable -- should be reported by writing a message to stderr and -exiting with a non-zero status code.

      fileCodeGeneratorResponse.Filerepeated

      - - - - -

      CodeGeneratorResponse.File

      -

      Represents a single generated file.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      The file name, relative to the output directory. The name must not -contain "." or ".." components and must be relative, not be absolute (so, -the file cannot lie outside the output directory). "/" must be used as -the path separator, not "\". - -If the name is omitted, the content will be appended to the previous -file. This allows the generator to break large files into small chunks, -and allows the generated text to be streamed back to protoc so that large -files need not reside completely in memory at one time. Note that as of -this writing protoc does not optimize for this -- it will read the entire -CodeGeneratorResponse before writing files to disk.

      insertion_pointstringoptional

      If non-empty, indicates that the named file should already exist, and the -content here is to be inserted into that file at a defined insertion -point. This feature allows a code generator to extend the output -produced by another code generator. The original generator may provide -insertion points by placing special annotations in the file that look -like: - @@protoc_insertion_point(NAME) -The annotation can have arbitrary text before and after it on the line, -which allows it to be placed in a comment. NAME should be replaced with -an identifier naming the point -- this is what other generators will use -as the insertion_point. Code inserted at this point will be placed -immediately above the line containing the insertion point (thus multiple -insertions to the same point will come out in the order they were added). -The double-@ is intended to make it unlikely that the generated code -could contain things that look like insertion points by accident. - -For example, the C++ code generator places the following line in the -.pb.h files that it generates: - // @@protoc_insertion_point(namespace_scope) -This line appears within the scope of the file's package namespace, but -outside of any particular class. Another plugin can then specify the -insertion_point "namespace_scope" to generate additional classes or -other declarations that should be placed in this scope. - -Note that if the line containing the insertion point begins with -whitespace, the same whitespace will be added to every line of the -inserted text. This is useful for languages like Python, where -indentation matters. In these languages, the insertion point comment -should be indented the same amount as any inserted code will need to be -in order to work correctly in that context. - -The code generator that generates the initial file and the one which -inserts into it must both run as part of a single invocation of protoc. -Code generators are executed in the order in which they appear on the -command line. - -If |insertion_point| is present, |name| must also be present.

      contentstringoptional

      The file contents.

      - - - - -

      Version

      -

      The version number of protocol compiler.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      majorint32optional

      minorint32optional

      patchint32optional

      suffixstringoptional

      A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should -be empty for mainline stable releases.

      - - - - - - - - - - - - -
      -

      google/protobuf/descriptor.proto

      Top -
      -

      - - -

      DescriptorProto

      -

      Describes a message type.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      fieldFieldDescriptorProtorepeated

      extensionFieldDescriptorProtorepeated

      nested_typeDescriptorProtorepeated

      enum_typeEnumDescriptorProtorepeated

      extension_rangeDescriptorProto.ExtensionRangerepeated

      oneof_declOneofDescriptorProtorepeated

      optionsMessageOptionsoptional

      reserved_rangeDescriptorProto.ReservedRangerepeated

      reserved_namestringrepeated

      Reserved field names, which may not be used by fields in the same message. -A given name may only be reserved once.

      - - - - -

      DescriptorProto.ExtensionRange

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      startint32optional

      endint32optional

      optionsExtensionRangeOptionsoptional

      - - - - -

      DescriptorProto.ReservedRange

      -

      Range of reserved tag numbers. Reserved tag numbers may not be used by

      fields or extension ranges in the same message. Reserved ranges may

      not overlap.

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      startint32optional

      Inclusive.

      endint32optional

      Exclusive.

      - - - - -

      EnumDescriptorProto

      -

      Describes an enum type.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      valueEnumValueDescriptorProtorepeated

      optionsEnumOptionsoptional

      reserved_rangeEnumDescriptorProto.EnumReservedRangerepeated

      Range of reserved numeric values. Reserved numeric values may not be used -by enum values in the same enum declaration. Reserved ranges may not -overlap.

      reserved_namestringrepeated

      Reserved enum value names, which may not be reused. A given name may only -be reserved once.

      - - - - -

      EnumDescriptorProto.EnumReservedRange

      -

      Range of reserved numeric values. Reserved values may not be used by

      entries in the same enum. Reserved ranges may not overlap.

      Note that this is distinct from DescriptorProto.ReservedRange in that it

      is inclusive such that it can appropriately represent the entire int32

      domain.

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      startint32optional

      Inclusive.

      endint32optional

      Inclusive.

      - - - - -

      EnumOptions

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      allow_aliasbooloptional

      Set this option to true to allow mapping different tag names to the same -value.

      deprecatedbooloptional

      Is this enum deprecated? -Depending on the target platform, this can emit Deprecated annotations -for the enum, or it will be completely ignored; in the very least, this -is a formalization for deprecating enums. Default: false

      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      EnumValueDescriptorProto

      -

      Describes a value within an enum.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      numberint32optional

      optionsEnumValueOptionsoptional

      - - - - -

      EnumValueOptions

      -

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      deprecatedbooloptional

      Is this enum value deprecated? -Depending on the target platform, this can emit Deprecated annotations -for the enum value, or it will be completely ignored; in the very least, -this is a formalization for deprecating enum values. Default: false

      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      ExtensionRangeOptions

      -

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      FieldDescriptorProto

      -

      Describes a field within a message.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      numberint32optional

      labelFieldDescriptorProto.Labeloptional

      typeFieldDescriptorProto.Typeoptional

      If type_name is set, this need not be set. If both this and type_name -are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP.

      type_namestringoptional

      For message and enum types, this is the name of the type. If the name -starts with a '.', it is fully-qualified. Otherwise, C++-like scoping -rules are used to find the type (i.e. first the nested types within this -message are searched, then within the parent, on up to the root -namespace).

      extendeestringoptional

      For extensions, this is the name of the type being extended. It is -resolved in the same manner as type_name.

      default_valuestringoptional

      For numeric types, contains the original text representation of the value. -For booleans, "true" or "false". -For strings, contains the default text contents (not escaped in any way). -For bytes, contains the C escaped value. All bytes >= 128 are escaped. -TODO(kenton): Base-64 encode?

      oneof_indexint32optional

      If set, gives the index of a oneof in the containing type's oneof_decl -list. This field is a member of that oneof.

      json_namestringoptional

      JSON name of this field. The value is set by protocol compiler. If the -user has set a "json_name" option on this field, that option's value -will be used. Otherwise, it's deduced from the field's name by converting -it to camelCase.

      optionsFieldOptionsoptional

      - - - - -

      FieldOptions

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      ctypeFieldOptions.CTypeoptional

      The ctype option instructs the C++ code generator to use a different -representation of the field than it normally would. See the specific -options below. This option is not yet implemented in the open source -release -- sorry, we'll try to include it in a future version! Default: STRING

      packedbooloptional

      The packed option can be enabled for repeated primitive fields to enable -a more efficient representation on the wire. Rather than repeatedly -writing the tag and type for each element, the entire array is encoded as -a single length-delimited blob. In proto3, only explicit setting it to -false will avoid using packed encoding.

      jstypeFieldOptions.JSTypeoptional

      The jstype option determines the JavaScript type used for values of the -field. The option is permitted only for 64 bit integral and fixed types -(int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING -is represented as JavaScript string, which avoids loss of precision that -can happen when a large value is converted to a floating point JavaScript. -Specifying JS_NUMBER for the jstype causes the generated JavaScript code to -use the JavaScript "number" type. The behavior of the default option -JS_NORMAL is implementation dependent. - -This option is an enum to permit additional types to be added, e.g. -goog.math.Integer. Default: JS_NORMAL

      lazybooloptional

      Should this field be parsed lazily? Lazy applies only to message-type -fields. It means that when the outer message is initially parsed, the -inner message's contents will not be parsed but instead stored in encoded -form. The inner message will actually be parsed when it is first accessed. - -This is only a hint. Implementations are free to choose whether to use -eager or lazy parsing regardless of the value of this option. However, -setting this option true suggests that the protocol author believes that -using lazy parsing on this field is worth the additional bookkeeping -overhead typically needed to implement it. - -This option does not affect the public interface of any generated code; -all method signatures remain the same. Furthermore, thread-safety of the -interface is not affected by this option; const methods remain safe to -call from multiple threads concurrently, while non-const methods continue -to require exclusive access. - - -Note that implementations may choose not to check required fields within -a lazy sub-message. That is, calling IsInitialized() on the outer message -may return true even if the inner message has missing required fields. -This is necessary because otherwise the inner message would have to be -parsed in order to perform the check, defeating the purpose of lazy -parsing. An implementation which chooses not to check required fields -must be consistent about it. That is, for any particular sub-message, the -implementation must either *always* check its required fields, or *never* -check its required fields, regardless of whether or not the message has -been parsed. Default: false

      deprecatedbooloptional

      Is this field deprecated? -Depending on the target platform, this can emit Deprecated annotations -for accessors, or it will be completely ignored; in the very least, this -is a formalization for deprecating fields. Default: false

      weakbooloptional

      For Google-internal migration only. Do not use. Default: false

      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      FileDescriptorProto

      -

      Describes a complete .proto file.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      file name, relative to root of source tree

      packagestringoptional

      e.g. "foo", "foo.bar", etc.

      dependencystringrepeated

      Names of files imported by this file.

      public_dependencyint32repeated

      Indexes of the public imported files in the dependency list above.

      weak_dependencyint32repeated

      Indexes of the weak imported files in the dependency list. -For Google-internal migration only. Do not use.

      message_typeDescriptorProtorepeated

      All top-level definitions in this file.

      enum_typeEnumDescriptorProtorepeated

      serviceServiceDescriptorProtorepeated

      extensionFieldDescriptorProtorepeated

      optionsFileOptionsoptional

      source_code_infoSourceCodeInfooptional

      This field contains optional information about the original source code. -You may safely remove this entire field without harming runtime -functionality of the descriptors -- the information is needed only by -development tools.

      syntaxstringoptional

      The syntax of the proto file. -The supported values are "proto2" and "proto3".

      - - - - -

      FileDescriptorSet

      -

      The protocol compiler can output a FileDescriptorSet containing the .proto

      files it parses.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      fileFileDescriptorProtorepeated

      - - - - -

      FileOptions

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      java_packagestringoptional

      Sets the Java package where classes generated from this .proto will be -placed. By default, the proto package is used, but this is often -inappropriate because proto packages do not normally start with backwards -domain names.

      java_outer_classnamestringoptional

      If set, all the classes from the .proto file are wrapped in a single -outer class with the given name. This applies to both Proto1 -(equivalent to the old "--one_java_file" option) and Proto2 (where -a .proto always translates to a single class, but you may want to -explicitly choose the class name).

      java_multiple_filesbooloptional

      If set true, then the Java code generator will generate a separate .java -file for each top-level message, enum, and service defined in the .proto -file. Thus, these types will *not* be nested inside the outer class -named by java_outer_classname. However, the outer class will still be -generated to contain the file's getDescriptor() method as well as any -top-level extensions defined in the file. Default: false

      java_generate_equals_and_hashbooloptional

      This option does nothing.

      java_string_check_utf8booloptional

      If set true, then the Java2 code generator will generate code that -throws an exception whenever an attempt is made to assign a non-UTF-8 -byte sequence to a string field. -Message reflection will do the same. -However, an extension field still accepts non-UTF-8 byte sequences. -This option has no effect on when used with the lite runtime. Default: false

      optimize_forFileOptions.OptimizeModeoptional

      Default: SPEED

      go_packagestringoptional

      Sets the Go package where structs generated from this .proto will be -placed. If omitted, the Go package will be derived from the following: - - The basename of the package import path, if provided. - - Otherwise, the package statement in the .proto file, if present. - - Otherwise, the basename of the .proto file, without extension.

      cc_generic_servicesbooloptional

      Should generic services be generated in each language? "Generic" services -are not specific to any particular RPC system. They are generated by the -main code generators in each language (without additional plugins). -Generic services were the only kind of service generation supported by -early versions of google.protobuf. - -Generic services are now considered deprecated in favor of using plugins -that generate code specific to your particular RPC system. Therefore, -these default to false. Old code which depends on generic services should -explicitly set them to true. Default: false

      java_generic_servicesbooloptional

      Default: false

      py_generic_servicesbooloptional

      Default: false

      php_generic_servicesbooloptional

      Default: false

      deprecatedbooloptional

      Is this file deprecated? -Depending on the target platform, this can emit Deprecated annotations -for everything in the file, or it will be completely ignored; in the very -least, this is a formalization for deprecating files. Default: false

      cc_enable_arenasbooloptional

      Enables the use of arenas for the proto messages in this file. This applies -only to generated classes for C++. Default: false

      objc_class_prefixstringoptional

      Sets the objective c class prefix which is prepended to all objective c -generated classes from this .proto. There is no default.

      csharp_namespacestringoptional

      Namespace for generated classes; defaults to the package.

      swift_prefixstringoptional

      By default Swift generators will take the proto package and CamelCase it -replacing '.' with underscore and use that to prefix the types/symbols -defined. When this options is provided, they will use this value instead -to prefix the types/symbols defined.

      php_class_prefixstringoptional

      Sets the php class prefix which is prepended to all php generated classes -from this .proto. Default is empty.

      php_namespacestringoptional

      Use this option to change the namespace of php generated classes. Default -is empty. When this option is empty, the package name will be used for -determining the namespace.

      php_metadata_namespacestringoptional

      Use this option to change the namespace of php generated metadata classes. -Default is empty. When this option is empty, the proto file name will be used -for determining the namespace.

      ruby_packagestringoptional

      Use this option to change the package of ruby generated classes. Default -is empty. When this option is not set, the package name will be used for -determining the ruby package.

      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. -See the documentation for the "Options" section above.

      - - - - -

      GeneratedCodeInfo

      -

      Describes the relationship between generated code and its original source

      file. A GeneratedCodeInfo message is associated with only one generated

      source file, but may contain references to different source .proto files.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      annotationGeneratedCodeInfo.Annotationrepeated

      An Annotation connects some span of text in generated code to an element -of its generating .proto file.

      - - - - -

      GeneratedCodeInfo.Annotation

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      pathint32repeated

      Identifies the element in the original source .proto file. This field -is formatted the same as SourceCodeInfo.Location.path.

      source_filestringoptional

      Identifies the filesystem path to the original source .proto.

      beginint32optional

      Identifies the starting offset in bytes in the generated code -that relates to the identified object.

      endint32optional

      Identifies the ending offset in bytes in the generated code that -relates to the identified offset. The end offset should be one past -the last relevant byte (so the length of the text = end - begin).

      - - - - -

      MessageOptions

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      message_set_wire_formatbooloptional

      Set true to use the old proto1 MessageSet wire format for extensions. -This is provided for backwards-compatibility with the MessageSet wire -format. You should not use this for any other reason: It's less -efficient, has fewer features, and is more complicated. - -The message must be defined exactly as follows: - message Foo { - option message_set_wire_format = true; - extensions 4 to max; - } -Note that the message cannot have any defined fields; MessageSets only -have extensions. - -All extensions of your type must be singular messages; e.g. they cannot -be int32s, enums, or repeated messages. - -Because this is an option, the above two restrictions are not enforced by -the protocol compiler. Default: false

      no_standard_descriptor_accessorbooloptional

      Disables the generation of the standard "descriptor()" accessor, which can -conflict with a field of the same name. This is meant to make migration -from proto1 easier; new code should avoid fields named "descriptor". Default: false

      deprecatedbooloptional

      Is this message deprecated? -Depending on the target platform, this can emit Deprecated annotations -for the message, or it will be completely ignored; in the very least, -this is a formalization for deprecating messages. Default: false

      map_entrybooloptional

      Whether the message is an automatically generated map entry type for the -maps field. - -For maps fields: - map<KeyType, ValueType> map_field = 1; -The parsed descriptor looks like: - message MapFieldEntry { - option map_entry = true; - optional KeyType key = 1; - optional ValueType value = 2; - } - repeated MapFieldEntry map_field = 1; - -Implementations may choose not to generate the map_entry=true message, but -use a native map in the target language to hold the keys and values. -The reflection APIs in such implementions still need to work as -if the field is a repeated message field. - -NOTE: Do not set the option in .proto files. Always use the maps syntax -instead. The option should only be implicitly set by the proto compiler -parser.

      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      MethodDescriptorProto

      -

      Describes a method of a service.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      input_typestringoptional

      Input and output type names. These are resolved in the same way as -FieldDescriptorProto.type_name, but must refer to a message type.

      output_typestringoptional

      optionsMethodOptionsoptional

      client_streamingbooloptional

      Identifies if client streams multiple client messages Default: false

      server_streamingbooloptional

      Identifies if server streams multiple server messages Default: false

      - - - - -

      MethodOptions

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      deprecatedbooloptional

      Is this method deprecated? -Depending on the target platform, this can emit Deprecated annotations -for the method, or it will be completely ignored; in the very least, -this is a formalization for deprecating methods. Default: false

      idempotency_levelMethodOptions.IdempotencyLeveloptional

      Default: IDEMPOTENCY_UNKNOWN

      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      OneofDescriptorProto

      -

      Describes a oneof.

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      optionsOneofOptionsoptional

      - - - - -

      OneofOptions

      -

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      ServiceDescriptorProto

      -

      Describes a service.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestringoptional

      methodMethodDescriptorProtorepeated

      optionsServiceOptionsoptional

      - - - - -

      ServiceOptions

      -

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      deprecatedbooloptional

      Is this service deprecated? -Depending on the target platform, this can emit Deprecated annotations -for the service, or it will be completely ignored; in the very least, -this is a formalization for deprecating services. Default: false

      uninterpreted_optionUninterpretedOptionrepeated

      The parser stores options it doesn't recognize here. See above.

      - - - - -

      SourceCodeInfo

      -

      Encapsulates information about the original source file from which a

      FileDescriptorProto was generated.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      locationSourceCodeInfo.Locationrepeated

      A Location identifies a piece of source code in a .proto file which -corresponds to a particular definition. This information is intended -to be useful to IDEs, code indexers, documentation generators, and similar -tools. - -For example, say we have a file like: - message Foo { - optional string foo = 1; - } -Let's look at just the field definition: - optional string foo = 1; - ^ ^^ ^^ ^ ^^^ - a bc de f ghi -We have the following locations: - span path represents - [a,i) [ 4, 0, 2, 0 ] The whole field definition. - [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). - [c,d) [ 4, 0, 2, 0, 5 ] The type (string). - [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). - [g,h) [ 4, 0, 2, 0, 3 ] The number (1). - -Notes: -- A location may refer to a repeated field itself (i.e. not to any - particular index within it). This is used whenever a set of elements are - logically enclosed in a single code segment. For example, an entire - extend block (possibly containing multiple extension definitions) will - have an outer location whose path refers to the "extensions" repeated - field without an index. -- Multiple locations may have the same path. This happens when a single - logical declaration is spread out across multiple places. The most - obvious example is the "extend" block again -- there may be multiple - extend blocks in the same scope, each of which will have the same path. -- A location's span is not always a subset of its parent's span. For - example, the "extendee" of an extension declaration appears at the - beginning of the "extend" block and is shared by all extensions within - the block. -- Just because a location's span is a subset of some other location's span - does not mean that it is a descendent. For example, a "group" defines - both a type and a field in a single declaration. Thus, the locations - corresponding to the type and field and their components will overlap. -- Code which tries to interpret locations should probably be designed to - ignore those that it doesn't understand, as more types of locations could - be recorded in the future.

      - - - - -

      SourceCodeInfo.Location

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      pathint32repeated

      Identifies which part of the FileDescriptorProto was defined at this -location. - -Each element is a field number or an index. They form a path from -the root FileDescriptorProto to the place where the definition. For -example, this path: - [ 4, 3, 2, 7, 1 ] -refers to: - file.message_type(3) // 4, 3 - .field(7) // 2, 7 - .name() // 1 -This is because FileDescriptorProto.message_type has field number 4: - repeated DescriptorProto message_type = 4; -and DescriptorProto.field has field number 2: - repeated FieldDescriptorProto field = 2; -and FieldDescriptorProto.name has field number 1: - optional string name = 1; - -Thus, the above path gives the location of a field name. If we removed -the last element: - [ 4, 3, 2, 7 ] -this path refers to the whole field declaration (from the beginning -of the label to the terminating semicolon).

      spanint32repeated

      Always has exactly three or four elements: start line, start column, -end line (optional, otherwise assumed same as start line), end column. -These are packed into a single field for efficiency. Note that line -and column numbers are zero-based -- typically you will want to add -1 to each before displaying to a user.

      leading_commentsstringoptional

      If this SourceCodeInfo represents a complete declaration, these are any -comments appearing before and after the declaration which appear to be -attached to the declaration. - -A series of line comments appearing on consecutive lines, with no other -tokens appearing on those lines, will be treated as a single comment. - -leading_detached_comments will keep paragraphs of comments that appear -before (but not connected to) the current element. Each paragraph, -separated by empty lines, will be one comment element in the repeated -field. - -Only the comment content is provided; comment markers (e.g. //) are -stripped out. For block comments, leading whitespace and an asterisk -will be stripped from the beginning of each line other than the first. -Newlines are included in the output. - -Examples: - - optional int32 foo = 1; // Comment attached to foo. - // Comment attached to bar. - optional int32 bar = 2; - - optional string baz = 3; - // Comment attached to baz. - // Another line attached to baz. - - // Comment attached to qux. - // - // Another line attached to qux. - optional double qux = 4; - - // Detached comment for corge. This is not leading or trailing comments - // to qux or corge because there are blank lines separating it from - // both. - - // Detached comment for corge paragraph 2. - - optional string corge = 5; - /* Block comment attached - * to corge. Leading asterisks - * will be removed. */ - /* Block comment attached to - * grault. */ - optional int32 grault = 6; - - // ignored detached comments.

      trailing_commentsstringoptional

      leading_detached_commentsstringrepeated

      - - - - -

      UninterpretedOption

      -

      A message representing a option the parser does not recognize. This only

      appears in options protos created by the compiler::Parser class.

      DescriptorPool resolves these when building Descriptor objects. Therefore,

      options protos in descriptor objects (e.g. returned by Descriptor::options(),

      or produced by Descriptor::CopyTo()) will never have UninterpretedOptions

      in them.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      nameUninterpretedOption.NamePartrepeated

      identifier_valuestringoptional

      The value of the uninterpreted option, in whatever type the tokenizer -identified it as during parsing. Exactly one of these should be set.

      positive_int_valueuint64optional

      negative_int_valueint64optional

      double_valuedoubleoptional

      string_valuebytesoptional

      aggregate_valuestringoptional

      - - - - -

      UninterpretedOption.NamePart

      -

      The name of the uninterpreted option. Each string represents a segment in

      a dot-separated name. is_extension is true iff a segment represents an

      extension (denoted with parentheses in options specs in .proto files).

      E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents

      "foo.(bar.baz).qux".

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      name_partstringrequired

      is_extensionboolrequired

      - - - - - - -

      FieldDescriptorProto.Label

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      LABEL_OPTIONAL1

      0 is reserved for errors

      LABEL_REQUIRED2

      LABEL_REPEATED3

      - -

      FieldDescriptorProto.Type

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      TYPE_DOUBLE1

      0 is reserved for errors. -Order is weird for historical reasons.

      TYPE_FLOAT2

      TYPE_INT643

      Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if -negative values are likely.

      TYPE_UINT644

      TYPE_INT325

      Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if -negative values are likely.

      TYPE_FIXED646

      TYPE_FIXED327

      TYPE_BOOL8

      TYPE_STRING9

      TYPE_GROUP10

      Tag-delimited aggregate. -Group type is deprecated and not supported in proto3. However, Proto3 -implementations should still be able to parse the group wire format and -treat group fields as unknown fields.

      TYPE_MESSAGE11

      Length-delimited aggregate.

      TYPE_BYTES12

      New in version 2.

      TYPE_UINT3213

      TYPE_ENUM14

      TYPE_SFIXED3215

      TYPE_SFIXED6416

      TYPE_SINT3217

      Uses ZigZag encoding.

      TYPE_SINT6418

      Uses ZigZag encoding.

      - -

      FieldOptions.CType

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      STRING0

      Default mode.

      CORD1

      STRING_PIECE2

      - -

      FieldOptions.JSType

      -

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      JS_NORMAL0

      Use the default type.

      JS_STRING1

      Use JavaScript strings.

      JS_NUMBER2

      Use JavaScript numbers.

      - -

      FileOptions.OptimizeMode

      -

      Generated classes can be optimized for speed or code size.

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      SPEED1

      Generate complete code for parsing, serialization,

      CODE_SIZE2

      etc. - -Use ReflectionOps to implement these methods.

      LITE_RUNTIME3

      Generate code using MessageLite and the lite runtime.

      - -

      MethodOptions.IdempotencyLevel

      -

      Is this method side-effect-free (or safe in HTTP parlance), or idempotent,

      or neither? HTTP based RPC implementation may choose GET verb for safe

      methods, and PUT verb for idempotent methods instead of the default POST.

      - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      IDEMPOTENCY_UNKNOWN0

      NO_SIDE_EFFECTS1

      implies idempotent

      IDEMPOTENT2

      idempotent, but may have side effects

      - - - - - - - -
      -

      google/protobuf/duration.proto

      Top -
      -

      - - -

      Duration

      -

      A Duration represents a signed, fixed-length span of time represented

      as a count of seconds and fractions of seconds at nanosecond

      resolution. It is independent of any calendar and concepts like "day"

      or "month". It is related to Timestamp in that the difference between

      two Timestamp values is a Duration and it can be added or subtracted

      from a Timestamp. Range is approximately +-10,000 years.

      # Examples

      Example 1: Compute Duration from two Timestamps in pseudo code.

      Timestamp start = ...;

      Timestamp end = ...;

      Duration duration = ...;

      duration.seconds = end.seconds - start.seconds;

      duration.nanos = end.nanos - start.nanos;

      if (duration.seconds < 0 && duration.nanos > 0) {

      duration.seconds += 1;

      duration.nanos -= 1000000000;

      } else if (durations.seconds > 0 && duration.nanos < 0) {

      duration.seconds -= 1;

      duration.nanos += 1000000000;

      }

      Example 2: Compute Timestamp from Timestamp + Duration in pseudo code.

      Timestamp start = ...;

      Duration duration = ...;

      Timestamp end = ...;

      end.seconds = start.seconds + duration.seconds;

      end.nanos = start.nanos + duration.nanos;

      if (end.nanos < 0) {

      end.seconds -= 1;

      end.nanos += 1000000000;

      } else if (end.nanos >= 1000000000) {

      end.seconds += 1;

      end.nanos -= 1000000000;

      }

      Example 3: Compute Duration from datetime.timedelta in Python.

      td = datetime.timedelta(days=3, minutes=10)

      duration = Duration()

      duration.FromTimedelta(td)

      # JSON Mapping

      In JSON format, the Duration type is encoded as a string rather than an

      object, where the string ends in the suffix "s" (indicating seconds) and

      is preceded by the number of seconds, with nanoseconds expressed as

      fractional seconds. For example, 3 seconds with 0 nanoseconds should be

      encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should

      be expressed in JSON format as "3.000000001s", and 3 seconds and 1

      microsecond should be expressed in JSON format as "3.000001s".

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      secondsint64

      Signed seconds of the span of time. Must be from -315,576,000,000 -to +315,576,000,000 inclusive. Note: these bounds are computed from: -60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years

      nanosint32

      Signed fractions of a second at nanosecond resolution of the span -of time. Durations less than one second are represented with a 0 -`seconds` field and a positive or negative `nanos` field. For durations -of one second or more, a non-zero value for the `nanos` field must be -of the same sign as the `seconds` field. Must be from -999,999,999 -to +999,999,999 inclusive.

      - - - - - - - - - - - - -
      -

      google/protobuf/empty.proto

      Top -
      -

      - - -

      Empty

      -

      A generic empty message that you can re-use to avoid defining duplicated

      empty messages in your APIs. A typical example is to use it as the request

      or the response type of an API method. For instance:

      service Foo {

      rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);

      }

      The JSON representation for `Empty` is empty JSON object `{}`.

      - - - - - - - - - - - - - -
      -

      google/protobuf/field_mask.proto

      Top -
      -

      - - -

      FieldMask

      -

      `FieldMask` represents a set of symbolic field paths, for example:

      paths: "f.a"

      paths: "f.b.d"

      Here `f` represents a field in some root message, `a` and `b`

      fields in the message found in `f`, and `d` a field found in the

      message in `f.b`.

      Field masks are used to specify a subset of fields that should be

      returned by a get operation or modified by an update operation.

      Field masks also have a custom JSON encoding (see below).

      # Field Masks in Projections

      When used in the context of a projection, a response message or

      sub-message is filtered by the API to only contain those fields as

      specified in the mask. For example, if the mask in the previous

      example is applied to a response message as follows:

      f {

      a : 22

      b {

      d : 1

      x : 2

      }

      y : 13

      }

      z: 8

      The result will not contain specific values for fields x,y and z

      (their value will be set to the default, and omitted in proto text

      output):

      f {

      a : 22

      b {

      d : 1

      }

      }

      A repeated field is not allowed except at the last position of a

      paths string.

      If a FieldMask object is not present in a get operation, the

      operation applies to all fields (as if a FieldMask of all fields

      had been specified).

      Note that a field mask does not necessarily apply to the

      top-level response message. In case of a REST get operation, the

      field mask applies directly to the response, but in case of a REST

      list operation, the mask instead applies to each individual message

      in the returned resource list. In case of a REST custom method,

      other definitions may be used. Where the mask applies will be

      clearly documented together with its declaration in the API. In

      any case, the effect on the returned resource/resources is required

      behavior for APIs.

      # Field Masks in Update Operations

      A field mask in update operations specifies which fields of the

      targeted resource are going to be updated. The API is required

      to only change the values of the fields as specified in the mask

      and leave the others untouched. If a resource is passed in to

      describe the updated values, the API ignores the values of all

      fields not covered by the mask.

      If a repeated field is specified for an update operation, the existing

      repeated values in the target resource will be overwritten by the new values.

      Note that a repeated field is only allowed in the last position of a `paths`

      string.

      If a sub-message is specified in the last position of the field mask for an

      update operation, then the existing sub-message in the target resource is

      overwritten. Given the target message:

      f {

      b {

      d : 1

      x : 2

      }

      c : 1

      }

      And an update message:

      f {

      b {

      d : 10

      }

      }

      then if the field mask is:

      paths: "f.b"

      then the result will be:

      f {

      b {

      d : 10

      }

      c : 1

      }

      However, if the update mask was:

      paths: "f.b.d"

      then the result would be:

      f {

      b {

      d : 10

      x : 2

      }

      c : 1

      }

      In order to reset a field's value to the default, the field must

      be in the mask and set to the default value in the provided resource.

      Hence, in order to reset all fields of a resource, provide a default

      instance of the resource and set all fields in the mask, or do

      not provide a mask as described below.

      If a field mask is not present on update, the operation applies to

      all fields (as if a field mask of all fields has been specified).

      Note that in the presence of schema evolution, this may mean that

      fields the client does not know and has therefore not filled into

      the request will be reset to their default. If this is unwanted

      behavior, a specific service may require a client to always specify

      a field mask, producing an error if not.

      As with get operations, the location of the resource which

      describes the updated values in the request message depends on the

      operation kind. In any case, the effect of the field mask is

      required to be honored by the API.

      ## Considerations for HTTP REST

      The HTTP kind of an update operation which uses a field mask must

      be set to PATCH instead of PUT in order to satisfy HTTP semantics

      (PUT must only be used for full updates).

      # JSON Encoding of Field Masks

      In JSON, a field mask is encoded as a single string where paths are

      separated by a comma. Fields name in each path are converted

      to/from lower-camel naming conventions.

      As an example, consider the following message declarations:

      message Profile {

      User user = 1;

      Photo photo = 2;

      }

      message User {

      string display_name = 1;

      string address = 2;

      }

      In proto a field mask for `Profile` may look as such:

      mask {

      paths: "user.display_name"

      paths: "photo"

      }

      In JSON, the same mask is represented as below:

      {

      mask: "user.displayName,photo"

      }

      # Field Masks and Oneof Fields

      Field masks treat fields in oneofs just as regular fields. Consider the

      following message:

      message SampleMessage {

      oneof test_oneof {

      string name = 4;

      SubMessage sub_message = 9;

      }

      }

      The field mask can be:

      mask {

      paths: "name"

      }

      Or:

      mask {

      paths: "sub_message"

      }

      Note that oneof type names ("test_oneof" in this case) cannot be used in

      paths.

      ## Field Mask Verification

      The implementation of any API method which has a FieldMask type field in the

      request should verify the included field paths, and return an

      `INVALID_ARGUMENT` error if any path is duplicated or unmappable.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      pathsstringrepeated

      The set of field mask paths.

      - - - - - - - - - - - - -
      -

      google/protobuf/source_context.proto

      Top -
      -

      - - -

      SourceContext

      -

      `SourceContext` represents information about the source of a

      protobuf element, like the file in which it is defined.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      file_namestring

      The path-qualified name of the .proto file that contained the associated -protobuf element. For example: `"google/protobuf/source_context.proto"`.

      - - - - - - - - - - - - -
      -

      google/protobuf/struct.proto

      Top -
      -

      - - -

      ListValue

      -

      `ListValue` is a wrapper around a repeated field of values.

      The JSON representation for `ListValue` is JSON array.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valuesValuerepeated

      Repeated field of dynamically typed values.

      - - - - -

      Struct

      -

      `Struct` represents a structured data value, consisting of fields

      which map to dynamically typed values. In some languages, `Struct`

      might be supported by a native representation. For example, in

      scripting languages like JS a struct is represented as an

      object. The details of that representation are described together

      with the proto support for the language.

      The JSON representation for `Struct` is JSON object.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      fieldsStruct.FieldsEntryrepeated

      Unordered map of dynamically typed values.

      - - - - -

      Struct.FieldsEntry

      -

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      keystring

      valueValue

      - - - - -

      Value

      -

      `Value` represents a dynamically typed value which can be either

      null, a number, a string, a boolean, a recursive struct value, or a

      list of values. A producer of value is expected to set one of that

      variants, absence of any variant indicates an error.

      The JSON representation for `Value` is JSON value.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      null_valueNullValue

      Represents a null value.

      number_valuedouble

      Represents a double value.

      string_valuestring

      Represents a string value.

      bool_valuebool

      Represents a boolean value.

      struct_valueStruct

      Represents a structured value.

      list_valueListValue

      Represents a repeated `Value`.

      - - - - - - -

      NullValue

      -

      `NullValue` is a singleton enumeration to represent the null value for the

      `Value` type union.

      The JSON representation for `NullValue` is JSON `null`.

      - - - - - - - - - - - - - -
      NameNumberDescription
      NULL_VALUE0

      Null value.

      - - - - - - - -
      -

      google/protobuf/timestamp.proto

      Top -
      -

      - - -

      Timestamp

      -

      A Timestamp represents a point in time independent of any time zone

      or calendar, represented as seconds and fractions of seconds at

      nanosecond resolution in UTC Epoch time. It is encoded using the

      Proleptic Gregorian Calendar which extends the Gregorian calendar

      backwards to year one. It is encoded assuming all minutes are 60

      seconds long, i.e. leap seconds are "smeared" so that no leap second

      table is needed for interpretation. Range is from

      0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z.

      By restricting to that range, we ensure that we can convert to

      and from RFC 3339 date strings.

      See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt).

      # Examples

      Example 1: Compute Timestamp from POSIX `time()`.

      Timestamp timestamp;

      timestamp.set_seconds(time(NULL));

      timestamp.set_nanos(0);

      Example 2: Compute Timestamp from POSIX `gettimeofday()`.

      struct timeval tv;

      gettimeofday(&tv, NULL);

      Timestamp timestamp;

      timestamp.set_seconds(tv.tv_sec);

      timestamp.set_nanos(tv.tv_usec * 1000);

      Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.

      FILETIME ft;

      GetSystemTimeAsFileTime(&ft);

      UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;

      // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z

      // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.

      Timestamp timestamp;

      timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));

      timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));

      Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.

      long millis = System.currentTimeMillis();

      Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)

      .setNanos((int) ((millis % 1000) * 1000000)).build();

      Example 5: Compute Timestamp from current time in Python.

      timestamp = Timestamp()

      timestamp.GetCurrentTime()

      # JSON Mapping

      In JSON format, the Timestamp type is encoded as a string in the

      [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the

      format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z"

      where {year} is always expressed using four digits while {month}, {day},

      {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional

      seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),

      are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone

      is required. A proto3 JSON serializer should always use UTC (as indicated by

      "Z") when printing the Timestamp type and a proto3 JSON parser should be

      able to accept both UTC and other timezones (as indicated by an offset).

      For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past

      01:30 UTC on January 15, 2017.

      In JavaScript, one can convert a Date object to this format using the

      standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString]

      method. In Python, a standard `datetime.datetime` object can be converted

      to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime)

      with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one

      can use the Joda Time's [`ISODateTimeFormat.dateTime()`](

      http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime--

      ) to obtain a formatter capable of generating timestamps in this format.

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      secondsint64

      Represents seconds of UTC time since Unix epoch -1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to -9999-12-31T23:59:59Z inclusive.

      nanosint32

      Non-negative fractions of a second at nanosecond resolution. Negative -second values with fractions must still have non-negative nanos values -that count forward in time. Must be from 0 to 999,999,999 -inclusive.

      - - - - - - - - - - - - -
      -

      google/protobuf/type.proto

      Top -
      -

      - - -

      Enum

      -

      Enum type definition.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestring

      Enum type name.

      enumvalueEnumValuerepeated

      Enum value definitions.

      optionsOptionrepeated

      Protocol buffer options.

      source_contextSourceContext

      The source context.

      syntaxSyntax

      The source syntax.

      - - - - -

      EnumValue

      -

      Enum value definition.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestring

      Enum value name.

      numberint32

      Enum value number.

      optionsOptionrepeated

      Protocol buffer options.

      - - - - -

      Field

      -

      A single field of a message type.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      kindField.Kind

      The field type.

      cardinalityField.Cardinality

      The field cardinality.

      numberint32

      The field number.

      namestring

      The field name.

      type_urlstring

      The field type URL, without the scheme, for message or enumeration -types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`.

      oneof_indexint32

      The index of the field type in `Type.oneofs`, for message or enumeration -types. The first type has index 1; zero means the type is not in the list.

      packedbool

      Whether to use alternative packed wire representation.

      optionsOptionrepeated

      The protocol buffer options.

      json_namestring

      The field JSON name.

      default_valuestring

      The string value of the default value of this field. Proto2 syntax only.

      - - - - -

      Option

      -

      A protocol buffer option, which can be attached to a message, field,

      enumeration, etc.

      - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestring

      The option's name. For protobuf built-in options (options defined in -descriptor.proto), this is the short name. For example, `"map_entry"`. -For custom options, it should be the fully-qualified name. For example, -`"google.api.http"`.

      valueAny

      The option's value packed in an Any message. If the value is a primitive, -the corresponding wrapper type defined in google/protobuf/wrappers.proto -should be used. If the value is an enum, it should be stored as an int32 -value using the google.protobuf.Int32Value type.

      - - - - -

      Type

      -

      A protocol buffer message type.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      namestring

      The fully qualified message name.

      fieldsFieldrepeated

      The list of fields.

      oneofsstringrepeated

      The list of types appearing in `oneof` definitions in this type.

      optionsOptionrepeated

      The protocol buffer options.

      source_contextSourceContext

      The source context.

      syntaxSyntax

      The source syntax.

      - - - - - - -

      Field.Cardinality

      -

      Whether a field is optional, required, or repeated.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      CARDINALITY_UNKNOWN0

      For fields with unknown cardinality.

      CARDINALITY_OPTIONAL1

      For optional fields.

      CARDINALITY_REQUIRED2

      For required fields. Proto2 syntax only.

      CARDINALITY_REPEATED3

      For repeated fields.

      - -

      Field.Kind

      -

      Basic field types.

      - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      TYPE_UNKNOWN0

      Field type unknown.

      TYPE_DOUBLE1

      Field type double.

      TYPE_FLOAT2

      Field type float.

      TYPE_INT643

      Field type int64.

      TYPE_UINT644

      Field type uint64.

      TYPE_INT325

      Field type int32.

      TYPE_FIXED646

      Field type fixed64.

      TYPE_FIXED327

      Field type fixed32.

      TYPE_BOOL8

      Field type bool.

      TYPE_STRING9

      Field type string.

      TYPE_GROUP10

      Field type group. Proto2 syntax only, and deprecated.

      TYPE_MESSAGE11

      Field type message.

      TYPE_BYTES12

      Field type bytes.

      TYPE_UINT3213

      Field type uint32.

      TYPE_ENUM14

      Field type enum.

      TYPE_SFIXED3215

      Field type sfixed32.

      TYPE_SFIXED6416

      Field type sfixed64.

      TYPE_SINT3217

      Field type sint32.

      TYPE_SINT6418

      Field type sint64.

      - -

      Syntax

      -

      The syntax in which a protocol buffer element is defined.

      - - - - - - - - - - - - - - - - - - - -
      NameNumberDescription
      SYNTAX_PROTO20

      Syntax `proto2`.

      SYNTAX_PROTO31

      Syntax `proto3`.

      - - - - - - - -
      -

      google/protobuf/wrappers.proto

      Top -
      -

      - - -

      BoolValue

      -

      Wrapper message for `bool`.

      The JSON representation for `BoolValue` is JSON `true` and `false`.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valuebool

      The bool value.

      - - - - -

      BytesValue

      -

      Wrapper message for `bytes`.

      The JSON representation for `BytesValue` is JSON string.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valuebytes

      The bytes value.

      - - - - -

      DoubleValue

      -

      Wrapper message for `double`.

      The JSON representation for `DoubleValue` is JSON number.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valuedouble

      The double value.

      - - - - -

      FloatValue

      -

      Wrapper message for `float`.

      The JSON representation for `FloatValue` is JSON number.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valuefloat

      The float value.

      - - - - -

      Int32Value

      -

      Wrapper message for `int32`.

      The JSON representation for `Int32Value` is JSON number.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valueint32

      The int32 value.

      - - - - -

      Int64Value

      -

      Wrapper message for `int64`.

      The JSON representation for `Int64Value` is JSON string.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valueint64

      The int64 value.

      - - - - -

      StringValue

      -

      Wrapper message for `string`.

      The JSON representation for `StringValue` is JSON string.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valuestring

      The string value.

      - - - - -

      UInt32Value

      -

      Wrapper message for `uint32`.

      The JSON representation for `UInt32Value` is JSON number.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valueuint32

      The uint32 value.

      - - - - -

      UInt64Value

      -

      Wrapper message for `uint64`.

      The JSON representation for `UInt64Value` is JSON string.

      - - - - - - - - - - - - - - - - -
      FieldTypeLabelDescription
      valueuint64

      The uint64 value.

      - - - - - - - - - - - -

      krotoplus/compiler/config.proto

      Top
      diff --git a/docs/markdown/kroto-plus-config.md b/docs/markdown/kroto-plus-config.md index 646edaa..d97079d 100644 --- a/docs/markdown/kroto-plus-config.md +++ b/docs/markdown/kroto-plus-config.md @@ -3,146 +3,6 @@ ## Table of Contents -- [google/protobuf/any.proto](#google/protobuf/any.proto) - - [Any](#google.protobuf.Any) - - - - - -- [google/protobuf/api.proto](#google/protobuf/api.proto) - - [Api](#google.protobuf.Api) - - [Method](#google.protobuf.Method) - - [Mixin](#google.protobuf.Mixin) - - - - - -- [google/protobuf/compiler/plugin.proto](#google/protobuf/compiler/plugin.proto) - - [CodeGeneratorRequest](#google.protobuf.compiler.CodeGeneratorRequest) - - [CodeGeneratorResponse](#google.protobuf.compiler.CodeGeneratorResponse) - - [CodeGeneratorResponse.File](#google.protobuf.compiler.CodeGeneratorResponse.File) - - [Version](#google.protobuf.compiler.Version) - - - - - -- [google/protobuf/descriptor.proto](#google/protobuf/descriptor.proto) - - [DescriptorProto](#google.protobuf.DescriptorProto) - - [DescriptorProto.ExtensionRange](#google.protobuf.DescriptorProto.ExtensionRange) - - [DescriptorProto.ReservedRange](#google.protobuf.DescriptorProto.ReservedRange) - - [EnumDescriptorProto](#google.protobuf.EnumDescriptorProto) - - [EnumDescriptorProto.EnumReservedRange](#google.protobuf.EnumDescriptorProto.EnumReservedRange) - - [EnumOptions](#google.protobuf.EnumOptions) - - [EnumValueDescriptorProto](#google.protobuf.EnumValueDescriptorProto) - - [EnumValueOptions](#google.protobuf.EnumValueOptions) - - [ExtensionRangeOptions](#google.protobuf.ExtensionRangeOptions) - - [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) - - [FieldOptions](#google.protobuf.FieldOptions) - - [FileDescriptorProto](#google.protobuf.FileDescriptorProto) - - [FileDescriptorSet](#google.protobuf.FileDescriptorSet) - - [FileOptions](#google.protobuf.FileOptions) - - [GeneratedCodeInfo](#google.protobuf.GeneratedCodeInfo) - - [GeneratedCodeInfo.Annotation](#google.protobuf.GeneratedCodeInfo.Annotation) - - [MessageOptions](#google.protobuf.MessageOptions) - - [MethodDescriptorProto](#google.protobuf.MethodDescriptorProto) - - [MethodOptions](#google.protobuf.MethodOptions) - - [OneofDescriptorProto](#google.protobuf.OneofDescriptorProto) - - [OneofOptions](#google.protobuf.OneofOptions) - - [ServiceDescriptorProto](#google.protobuf.ServiceDescriptorProto) - - [ServiceOptions](#google.protobuf.ServiceOptions) - - [SourceCodeInfo](#google.protobuf.SourceCodeInfo) - - [SourceCodeInfo.Location](#google.protobuf.SourceCodeInfo.Location) - - [UninterpretedOption](#google.protobuf.UninterpretedOption) - - [UninterpretedOption.NamePart](#google.protobuf.UninterpretedOption.NamePart) - - - [FieldDescriptorProto.Label](#google.protobuf.FieldDescriptorProto.Label) - - [FieldDescriptorProto.Type](#google.protobuf.FieldDescriptorProto.Type) - - [FieldOptions.CType](#google.protobuf.FieldOptions.CType) - - [FieldOptions.JSType](#google.protobuf.FieldOptions.JSType) - - [FileOptions.OptimizeMode](#google.protobuf.FileOptions.OptimizeMode) - - [MethodOptions.IdempotencyLevel](#google.protobuf.MethodOptions.IdempotencyLevel) - - - - -- [google/protobuf/duration.proto](#google/protobuf/duration.proto) - - [Duration](#google.protobuf.Duration) - - - - - -- [google/protobuf/empty.proto](#google/protobuf/empty.proto) - - [Empty](#google.protobuf.Empty) - - - - - -- [google/protobuf/field_mask.proto](#google/protobuf/field_mask.proto) - - [FieldMask](#google.protobuf.FieldMask) - - - - - -- [google/protobuf/source_context.proto](#google/protobuf/source_context.proto) - - [SourceContext](#google.protobuf.SourceContext) - - - - - -- [google/protobuf/struct.proto](#google/protobuf/struct.proto) - - [ListValue](#google.protobuf.ListValue) - - [Struct](#google.protobuf.Struct) - - [Struct.FieldsEntry](#google.protobuf.Struct.FieldsEntry) - - [Value](#google.protobuf.Value) - - - [NullValue](#google.protobuf.NullValue) - - - - -- [google/protobuf/timestamp.proto](#google/protobuf/timestamp.proto) - - [Timestamp](#google.protobuf.Timestamp) - - - - - -- [google/protobuf/type.proto](#google/protobuf/type.proto) - - [Enum](#google.protobuf.Enum) - - [EnumValue](#google.protobuf.EnumValue) - - [Field](#google.protobuf.Field) - - [Option](#google.protobuf.Option) - - [Type](#google.protobuf.Type) - - - [Field.Cardinality](#google.protobuf.Field.Cardinality) - - [Field.Kind](#google.protobuf.Field.Kind) - - [Syntax](#google.protobuf.Syntax) - - - - -- [google/protobuf/wrappers.proto](#google/protobuf/wrappers.proto) - - [BoolValue](#google.protobuf.BoolValue) - - [BytesValue](#google.protobuf.BytesValue) - - [DoubleValue](#google.protobuf.DoubleValue) - - [FloatValue](#google.protobuf.FloatValue) - - [Int32Value](#google.protobuf.Int32Value) - - [Int64Value](#google.protobuf.Int64Value) - - [StringValue](#google.protobuf.StringValue) - - [UInt32Value](#google.protobuf.UInt32Value) - - [UInt64Value](#google.protobuf.UInt64Value) - - - - - - [krotoplus/compiler/config.proto](#krotoplus/compiler/config.proto) - [CompilerConfig](#krotoplus.compiler.CompilerConfig) - [ExtenableMessagesGenOptions](#krotoplus.compiler.ExtenableMessagesGenOptions) @@ -164,2023 +24,6 @@ - -

      Top

      - -## google/protobuf/any.proto - - - - - -### Any -`Any` contains an arbitrary serialized protocol buffer message along with a -URL that describes the type of the serialized message. - -Protobuf library provides support to pack/unpack Any values in the form -of utility functions or additional generated methods of the Any type. - -Example 1: Pack and unpack a message in C++. - - Foo foo = ...; - Any any; - any.PackFrom(foo); - ... - if (any.UnpackTo(&foo)) { - ... - } - -Example 2: Pack and unpack a message in Java. - - Foo foo = ...; - Any any = Any.pack(foo); - ... - if (any.is(Foo.class)) { - foo = any.unpack(Foo.class); - } - - Example 3: Pack and unpack a message in Python. - - foo = Foo(...) - any = Any() - any.Pack(foo) - ... - if any.Is(Foo.DESCRIPTOR): - any.Unpack(foo) - ... - - Example 4: Pack and unpack a message in Go - - foo := &pb.Foo{...} - any, err := ptypes.MarshalAny(foo) - ... - foo := &pb.Foo{} - if err := ptypes.UnmarshalAny(any, foo); err != nil { - ... - } - -The pack methods provided by protobuf library will by default use -'type.googleapis.com/full.type.name' as the type URL and the unpack -methods only use the fully qualified type name after the last '/' -in the type URL, for example "foo.bar.com/x/y.z" will yield type -name "y.z". - - -JSON -==== -The JSON representation of an `Any` value uses the regular -representation of the deserialized, embedded message, with an -additional field `@type` which contains the type URL. Example: - - package google.profile; - message Person { - string first_name = 1; - string last_name = 2; - } - - { - "@type": "type.googleapis.com/google.profile.Person", - "firstName": <string>, - "lastName": <string> - } - -If the embedded message type is well-known and has a custom JSON -representation, that representation will be embedded adding a field -`value` which holds the custom JSON in addition to the `@type` -field. Example (for message [google.protobuf.Duration][]): - - { - "@type": "type.googleapis.com/google.protobuf.Duration", - "value": "1.212s" - } - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| type_url | [string](#string) | | A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. The last segment of the URL's path must represent the fully qualified name of the type (as in `path/google.protobuf.Duration`). The name should be in a canonical form (e.g., leading "." is not accepted). - -In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme `http`, `https`, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows: - -* If no scheme is provided, `https` is assumed. * An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error. * Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.) - -Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. - -Schemes other than `http`, `https` (or the empty scheme) might be used with implementation specific semantics. | -| value | [bytes](#bytes) | | Must be a valid serialized protocol buffer of the above specified type. | - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/api.proto - - - - - -### Api -Api is a light-weight descriptor for an API Interface. - -Interfaces are also described as "protocol buffer services" in some contexts, -such as by the "service" keyword in a .proto file, but they are different -from API Services, which represent a concrete implementation of an interface -as opposed to simply a description of methods and bindings. They are also -sometimes simply referred to as "APIs" in other contexts, such as the name of -this message itself. See https://cloud.google.com/apis/design/glossary for -detailed terminology. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | The fully qualified name of this interface, including package name followed by the interface's simple name. | -| methods | [Method](#google.protobuf.Method) | repeated | The methods of this interface, in unspecified order. | -| options | [Option](#google.protobuf.Option) | repeated | Any metadata attached to the interface. | -| version | [string](#string) | | A version string for this interface. If specified, must have the form `major-version.minor-version`, as in `1.10`. If the minor version is omitted, it defaults to zero. If the entire version field is empty, the major version is derived from the package name, as outlined below. If the field is not empty, the version in the package name will be verified to be consistent with what is provided here. - -The versioning schema uses [semantic versioning](http://semver.org) where the major version number indicates a breaking change and the minor version an additive, non-breaking change. Both version numbers are signals to users what to expect from different versions, and should be carefully chosen based on the product plan. - -The major version is also reflected in the package name of the interface, which must end in `v<major-version>`, as in `google.feature.v1`. For major versions 0 and 1, the suffix can be omitted. Zero major versions must only be used for experimental, non-GA interfaces. | -| source_context | [SourceContext](#google.protobuf.SourceContext) | | Source context for the protocol buffer service represented by this message. | -| mixins | [Mixin](#google.protobuf.Mixin) | repeated | Included interfaces. See [Mixin][]. | -| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax of the service. | - - - - - - - - -### Method -Method represents a method of an API interface. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | The simple name of this method. | -| request_type_url | [string](#string) | | A URL of the input message type. | -| request_streaming | [bool](#bool) | | If true, the request is streamed. | -| response_type_url | [string](#string) | | The URL of the output message type. | -| response_streaming | [bool](#bool) | | If true, the response is streamed. | -| options | [Option](#google.protobuf.Option) | repeated | Any metadata attached to the method. | -| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax of this method. | - - - - - - - - -### Mixin -Declares an API Interface to be included in this interface. The including -interface must redeclare all the methods from the included interface, but -documentation and options are inherited as follows: - -- If after comment and whitespace stripping, the documentation - string of the redeclared method is empty, it will be inherited - from the original method. - -- Each annotation belonging to the service config (http, - visibility) which is not set in the redeclared method will be - inherited. - -- If an http annotation is inherited, the path pattern will be - modified as follows. Any version prefix will be replaced by the - version of the including interface plus the [root][] path if - specified. - -Example of a simple mixin: - - package google.acl.v1; - service AccessControl { - // Get the underlying ACL object. - rpc GetAcl(GetAclRequest) returns (Acl) { - option (google.api.http).get = "/v1/{resource=**}:getAcl"; - } - } - - package google.storage.v2; - service Storage { - rpc GetAcl(GetAclRequest) returns (Acl); - - // Get a data record. - rpc GetData(GetDataRequest) returns (Data) { - option (google.api.http).get = "/v2/{resource=**}"; - } - } - -Example of a mixin configuration: - - apis: - - name: google.storage.v2.Storage - mixins: - - name: google.acl.v1.AccessControl - -The mixin construct implies that all methods in `AccessControl` are -also declared with same name and request/response types in -`Storage`. A documentation generator or annotation processor will -see the effective `Storage.GetAcl` method after inherting -documentation and annotations as follows: - - service Storage { - // Get the underlying ACL object. - rpc GetAcl(GetAclRequest) returns (Acl) { - option (google.api.http).get = "/v2/{resource=**}:getAcl"; - } - ... - } - -Note how the version in the path pattern changed from `v1` to `v2`. - -If the `root` field in the mixin is specified, it should be a -relative path under which inherited HTTP paths are placed. Example: - - apis: - - name: google.storage.v2.Storage - mixins: - - name: google.acl.v1.AccessControl - root: acls - -This implies the following inherited HTTP annotation: - - service Storage { - // Get the underlying ACL object. - rpc GetAcl(GetAclRequest) returns (Acl) { - option (google.api.http).get = "/v2/acls/{resource=**}:getAcl"; - } - ... - } - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | The fully qualified name of the interface which is included. | -| root | [string](#string) | | If non-empty specifies a path under which inherited HTTP paths are rooted. | - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/compiler/plugin.proto - - - - - -### CodeGeneratorRequest -An encoded CodeGeneratorRequest is written to the plugin's stdin. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| file_to_generate | [string](#string) | repeated | The .proto files that were explicitly listed on the command-line. The code generator should generate code only for these files. Each file's descriptor will be included in proto_file, below. | -| parameter | [string](#string) | optional | The generator parameter passed on the command-line. | -| proto_file | [google.protobuf.FileDescriptorProto](#google.protobuf.FileDescriptorProto) | repeated | FileDescriptorProtos for all files in files_to_generate and everything they import. The files will appear in topological order, so each file appears before any file that imports it. - -protoc guarantees that all proto_files will be written after the fields above, even though this is not technically guaranteed by the protobuf wire format. This theoretically could allow a plugin to stream in the FileDescriptorProtos and handle them one by one rather than read the entire set into memory at once. However, as of this writing, this is not similarly optimized on protoc's end -- it will store all fields in memory at once before sending them to the plugin. - -Type names of fields and extensions in the FileDescriptorProto are always fully qualified. | -| compiler_version | [Version](#google.protobuf.compiler.Version) | optional | The version number of protocol compiler. | - - - - - - - - -### CodeGeneratorResponse -The plugin writes an encoded CodeGeneratorResponse to stdout. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| error | [string](#string) | optional | Error message. If non-empty, code generation failed. The plugin process should exit with status code zero even if it reports an error in this way. - -This should be used to indicate errors in .proto files which prevent the code generator from generating correct code. Errors which indicate a problem in protoc itself -- such as the input CodeGeneratorRequest being unparseable -- should be reported by writing a message to stderr and exiting with a non-zero status code. | -| file | [CodeGeneratorResponse.File](#google.protobuf.compiler.CodeGeneratorResponse.File) | repeated | | - - - - - - - - -### CodeGeneratorResponse.File -Represents a single generated file. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | The file name, relative to the output directory. The name must not contain "." or ".." components and must be relative, not be absolute (so, the file cannot lie outside the output directory). "/" must be used as the path separator, not "\". - -If the name is omitted, the content will be appended to the previous file. This allows the generator to break large files into small chunks, and allows the generated text to be streamed back to protoc so that large files need not reside completely in memory at one time. Note that as of this writing protoc does not optimize for this -- it will read the entire CodeGeneratorResponse before writing files to disk. | -| insertion_point | [string](#string) | optional | If non-empty, indicates that the named file should already exist, and the content here is to be inserted into that file at a defined insertion point. This feature allows a code generator to extend the output produced by another code generator. The original generator may provide insertion points by placing special annotations in the file that look like: @@protoc_insertion_point(NAME) The annotation can have arbitrary text before and after it on the line, which allows it to be placed in a comment. NAME should be replaced with an identifier naming the point -- this is what other generators will use as the insertion_point. Code inserted at this point will be placed immediately above the line containing the insertion point (thus multiple insertions to the same point will come out in the order they were added). The double-@ is intended to make it unlikely that the generated code could contain things that look like insertion points by accident. - -For example, the C++ code generator places the following line in the .pb.h files that it generates: // @@protoc_insertion_point(namespace_scope) This line appears within the scope of the file's package namespace, but outside of any particular class. Another plugin can then specify the insertion_point "namespace_scope" to generate additional classes or other declarations that should be placed in this scope. - -Note that if the line containing the insertion point begins with whitespace, the same whitespace will be added to every line of the inserted text. This is useful for languages like Python, where indentation matters. In these languages, the insertion point comment should be indented the same amount as any inserted code will need to be in order to work correctly in that context. - -The code generator that generates the initial file and the one which inserts into it must both run as part of a single invocation of protoc. Code generators are executed in the order in which they appear on the command line. - -If |insertion_point| is present, |name| must also be present. | -| content | [string](#string) | optional | The file contents. | - - - - - - - - -### Version -The version number of protocol compiler. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| major | [int32](#int32) | optional | | -| minor | [int32](#int32) | optional | | -| patch | [int32](#int32) | optional | | -| suffix | [string](#string) | optional | A suffix for alpha, beta or rc release, e.g., "alpha-1", "rc2". It should be empty for mainline stable releases. | - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/descriptor.proto - - - - - -### DescriptorProto -Describes a message type. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | | -| field | [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) | repeated | | -| extension | [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) | repeated | | -| nested_type | [DescriptorProto](#google.protobuf.DescriptorProto) | repeated | | -| enum_type | [EnumDescriptorProto](#google.protobuf.EnumDescriptorProto) | repeated | | -| extension_range | [DescriptorProto.ExtensionRange](#google.protobuf.DescriptorProto.ExtensionRange) | repeated | | -| oneof_decl | [OneofDescriptorProto](#google.protobuf.OneofDescriptorProto) | repeated | | -| options | [MessageOptions](#google.protobuf.MessageOptions) | optional | | -| reserved_range | [DescriptorProto.ReservedRange](#google.protobuf.DescriptorProto.ReservedRange) | repeated | | -| reserved_name | [string](#string) | repeated | Reserved field names, which may not be used by fields in the same message. A given name may only be reserved once. | - - - - - - - - -### DescriptorProto.ExtensionRange - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| start | [int32](#int32) | optional | | -| end | [int32](#int32) | optional | | -| options | [ExtensionRangeOptions](#google.protobuf.ExtensionRangeOptions) | optional | | - - - - - - - - -### DescriptorProto.ReservedRange -Range of reserved tag numbers. Reserved tag numbers may not be used by -fields or extension ranges in the same message. Reserved ranges may -not overlap. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| start | [int32](#int32) | optional | Inclusive. | -| end | [int32](#int32) | optional | Exclusive. | - - - - - - - - -### EnumDescriptorProto -Describes an enum type. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | | -| value | [EnumValueDescriptorProto](#google.protobuf.EnumValueDescriptorProto) | repeated | | -| options | [EnumOptions](#google.protobuf.EnumOptions) | optional | | -| reserved_range | [EnumDescriptorProto.EnumReservedRange](#google.protobuf.EnumDescriptorProto.EnumReservedRange) | repeated | Range of reserved numeric values. Reserved numeric values may not be used by enum values in the same enum declaration. Reserved ranges may not overlap. | -| reserved_name | [string](#string) | repeated | Reserved enum value names, which may not be reused. A given name may only be reserved once. | - - - - - - - - -### EnumDescriptorProto.EnumReservedRange -Range of reserved numeric values. Reserved values may not be used by -entries in the same enum. Reserved ranges may not overlap. - -Note that this is distinct from DescriptorProto.ReservedRange in that it -is inclusive such that it can appropriately represent the entire int32 -domain. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| start | [int32](#int32) | optional | Inclusive. | -| end | [int32](#int32) | optional | Inclusive. | - - - - - - - - -### EnumOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| allow_alias | [bool](#bool) | optional | Set this option to true to allow mapping different tag names to the same value. | -| deprecated | [bool](#bool) | optional | Is this enum deprecated? Depending on the target platform, this can emit Deprecated annotations for the enum, or it will be completely ignored; in the very least, this is a formalization for deprecating enums. Default: false | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### EnumValueDescriptorProto -Describes a value within an enum. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | | -| number | [int32](#int32) | optional | | -| options | [EnumValueOptions](#google.protobuf.EnumValueOptions) | optional | | - - - - - - - - -### EnumValueOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| deprecated | [bool](#bool) | optional | Is this enum value deprecated? Depending on the target platform, this can emit Deprecated annotations for the enum value, or it will be completely ignored; in the very least, this is a formalization for deprecating enum values. Default: false | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### ExtensionRangeOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### FieldDescriptorProto -Describes a field within a message. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | | -| number | [int32](#int32) | optional | | -| label | [FieldDescriptorProto.Label](#google.protobuf.FieldDescriptorProto.Label) | optional | | -| type | [FieldDescriptorProto.Type](#google.protobuf.FieldDescriptorProto.Type) | optional | If type_name is set, this need not be set. If both this and type_name are set, this must be one of TYPE_ENUM, TYPE_MESSAGE or TYPE_GROUP. | -| type_name | [string](#string) | optional | For message and enum types, this is the name of the type. If the name starts with a '.', it is fully-qualified. Otherwise, C++-like scoping rules are used to find the type (i.e. first the nested types within this message are searched, then within the parent, on up to the root namespace). | -| extendee | [string](#string) | optional | For extensions, this is the name of the type being extended. It is resolved in the same manner as type_name. | -| default_value | [string](#string) | optional | For numeric types, contains the original text representation of the value. For booleans, "true" or "false". For strings, contains the default text contents (not escaped in any way). For bytes, contains the C escaped value. All bytes >= 128 are escaped. TODO(kenton): Base-64 encode? | -| oneof_index | [int32](#int32) | optional | If set, gives the index of a oneof in the containing type's oneof_decl list. This field is a member of that oneof. | -| json_name | [string](#string) | optional | JSON name of this field. The value is set by protocol compiler. If the user has set a "json_name" option on this field, that option's value will be used. Otherwise, it's deduced from the field's name by converting it to camelCase. | -| options | [FieldOptions](#google.protobuf.FieldOptions) | optional | | - - - - - - - - -### FieldOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| ctype | [FieldOptions.CType](#google.protobuf.FieldOptions.CType) | optional | The ctype option instructs the C++ code generator to use a different representation of the field than it normally would. See the specific options below. This option is not yet implemented in the open source release -- sorry, we'll try to include it in a future version! Default: STRING | -| packed | [bool](#bool) | optional | The packed option can be enabled for repeated primitive fields to enable a more efficient representation on the wire. Rather than repeatedly writing the tag and type for each element, the entire array is encoded as a single length-delimited blob. In proto3, only explicit setting it to false will avoid using packed encoding. | -| jstype | [FieldOptions.JSType](#google.protobuf.FieldOptions.JSType) | optional | The jstype option determines the JavaScript type used for values of the field. The option is permitted only for 64 bit integral and fixed types (int64, uint64, sint64, fixed64, sfixed64). A field with jstype JS_STRING is represented as JavaScript string, which avoids loss of precision that can happen when a large value is converted to a floating point JavaScript. Specifying JS_NUMBER for the jstype causes the generated JavaScript code to use the JavaScript "number" type. The behavior of the default option JS_NORMAL is implementation dependent. - -This option is an enum to permit additional types to be added, e.g. goog.math.Integer. Default: JS_NORMAL | -| lazy | [bool](#bool) | optional | Should this field be parsed lazily? Lazy applies only to message-type fields. It means that when the outer message is initially parsed, the inner message's contents will not be parsed but instead stored in encoded form. The inner message will actually be parsed when it is first accessed. - -This is only a hint. Implementations are free to choose whether to use eager or lazy parsing regardless of the value of this option. However, setting this option true suggests that the protocol author believes that using lazy parsing on this field is worth the additional bookkeeping overhead typically needed to implement it. - -This option does not affect the public interface of any generated code; all method signatures remain the same. Furthermore, thread-safety of the interface is not affected by this option; const methods remain safe to call from multiple threads concurrently, while non-const methods continue to require exclusive access. - -Note that implementations may choose not to check required fields within a lazy sub-message. That is, calling IsInitialized() on the outer message may return true even if the inner message has missing required fields. This is necessary because otherwise the inner message would have to be parsed in order to perform the check, defeating the purpose of lazy parsing. An implementation which chooses not to check required fields must be consistent about it. That is, for any particular sub-message, the implementation must either *always* check its required fields, or *never* check its required fields, regardless of whether or not the message has been parsed. Default: false | -| deprecated | [bool](#bool) | optional | Is this field deprecated? Depending on the target platform, this can emit Deprecated annotations for accessors, or it will be completely ignored; in the very least, this is a formalization for deprecating fields. Default: false | -| weak | [bool](#bool) | optional | For Google-internal migration only. Do not use. Default: false | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### FileDescriptorProto -Describes a complete .proto file. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | file name, relative to root of source tree | -| package | [string](#string) | optional | e.g. "foo", "foo.bar", etc. | -| dependency | [string](#string) | repeated | Names of files imported by this file. | -| public_dependency | [int32](#int32) | repeated | Indexes of the public imported files in the dependency list above. | -| weak_dependency | [int32](#int32) | repeated | Indexes of the weak imported files in the dependency list. For Google-internal migration only. Do not use. | -| message_type | [DescriptorProto](#google.protobuf.DescriptorProto) | repeated | All top-level definitions in this file. | -| enum_type | [EnumDescriptorProto](#google.protobuf.EnumDescriptorProto) | repeated | | -| service | [ServiceDescriptorProto](#google.protobuf.ServiceDescriptorProto) | repeated | | -| extension | [FieldDescriptorProto](#google.protobuf.FieldDescriptorProto) | repeated | | -| options | [FileOptions](#google.protobuf.FileOptions) | optional | | -| source_code_info | [SourceCodeInfo](#google.protobuf.SourceCodeInfo) | optional | This field contains optional information about the original source code. You may safely remove this entire field without harming runtime functionality of the descriptors -- the information is needed only by development tools. | -| syntax | [string](#string) | optional | The syntax of the proto file. The supported values are "proto2" and "proto3". | - - - - - - - - -### FileDescriptorSet -The protocol compiler can output a FileDescriptorSet containing the .proto -files it parses. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| file | [FileDescriptorProto](#google.protobuf.FileDescriptorProto) | repeated | | - - - - - - - - -### FileOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| java_package | [string](#string) | optional | Sets the Java package where classes generated from this .proto will be placed. By default, the proto package is used, but this is often inappropriate because proto packages do not normally start with backwards domain names. | -| java_outer_classname | [string](#string) | optional | If set, all the classes from the .proto file are wrapped in a single outer class with the given name. This applies to both Proto1 (equivalent to the old "--one_java_file" option) and Proto2 (where a .proto always translates to a single class, but you may want to explicitly choose the class name). | -| java_multiple_files | [bool](#bool) | optional | If set true, then the Java code generator will generate a separate .java file for each top-level message, enum, and service defined in the .proto file. Thus, these types will *not* be nested inside the outer class named by java_outer_classname. However, the outer class will still be generated to contain the file's getDescriptor() method as well as any top-level extensions defined in the file. Default: false | -| java_generate_equals_and_hash | [bool](#bool) | optional | This option does nothing. | -| java_string_check_utf8 | [bool](#bool) | optional | If set true, then the Java2 code generator will generate code that throws an exception whenever an attempt is made to assign a non-UTF-8 byte sequence to a string field. Message reflection will do the same. However, an extension field still accepts non-UTF-8 byte sequences. This option has no effect on when used with the lite runtime. Default: false | -| optimize_for | [FileOptions.OptimizeMode](#google.protobuf.FileOptions.OptimizeMode) | optional | Default: SPEED | -| go_package | [string](#string) | optional | Sets the Go package where structs generated from this .proto will be placed. If omitted, the Go package will be derived from the following: - The basename of the package import path, if provided. - Otherwise, the package statement in the .proto file, if present. - Otherwise, the basename of the .proto file, without extension. | -| cc_generic_services | [bool](#bool) | optional | Should generic services be generated in each language? "Generic" services are not specific to any particular RPC system. They are generated by the main code generators in each language (without additional plugins). Generic services were the only kind of service generation supported by early versions of google.protobuf. - -Generic services are now considered deprecated in favor of using plugins that generate code specific to your particular RPC system. Therefore, these default to false. Old code which depends on generic services should explicitly set them to true. Default: false | -| java_generic_services | [bool](#bool) | optional | Default: false | -| py_generic_services | [bool](#bool) | optional | Default: false | -| php_generic_services | [bool](#bool) | optional | Default: false | -| deprecated | [bool](#bool) | optional | Is this file deprecated? Depending on the target platform, this can emit Deprecated annotations for everything in the file, or it will be completely ignored; in the very least, this is a formalization for deprecating files. Default: false | -| cc_enable_arenas | [bool](#bool) | optional | Enables the use of arenas for the proto messages in this file. This applies only to generated classes for C++. Default: false | -| objc_class_prefix | [string](#string) | optional | Sets the objective c class prefix which is prepended to all objective c generated classes from this .proto. There is no default. | -| csharp_namespace | [string](#string) | optional | Namespace for generated classes; defaults to the package. | -| swift_prefix | [string](#string) | optional | By default Swift generators will take the proto package and CamelCase it replacing '.' with underscore and use that to prefix the types/symbols defined. When this options is provided, they will use this value instead to prefix the types/symbols defined. | -| php_class_prefix | [string](#string) | optional | Sets the php class prefix which is prepended to all php generated classes from this .proto. Default is empty. | -| php_namespace | [string](#string) | optional | Use this option to change the namespace of php generated classes. Default is empty. When this option is empty, the package name will be used for determining the namespace. | -| php_metadata_namespace | [string](#string) | optional | Use this option to change the namespace of php generated metadata classes. Default is empty. When this option is empty, the proto file name will be used for determining the namespace. | -| ruby_package | [string](#string) | optional | Use this option to change the package of ruby generated classes. Default is empty. When this option is not set, the package name will be used for determining the ruby package. | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See the documentation for the "Options" section above. | - - - - - - - - -### GeneratedCodeInfo -Describes the relationship between generated code and its original source -file. A GeneratedCodeInfo message is associated with only one generated -source file, but may contain references to different source .proto files. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| annotation | [GeneratedCodeInfo.Annotation](#google.protobuf.GeneratedCodeInfo.Annotation) | repeated | An Annotation connects some span of text in generated code to an element of its generating .proto file. | - - - - - - - - -### GeneratedCodeInfo.Annotation - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| path | [int32](#int32) | repeated | Identifies the element in the original source .proto file. This field is formatted the same as SourceCodeInfo.Location.path. | -| source_file | [string](#string) | optional | Identifies the filesystem path to the original source .proto. | -| begin | [int32](#int32) | optional | Identifies the starting offset in bytes in the generated code that relates to the identified object. | -| end | [int32](#int32) | optional | Identifies the ending offset in bytes in the generated code that relates to the identified offset. The end offset should be one past the last relevant byte (so the length of the text = end - begin). | - - - - - - - - -### MessageOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| message_set_wire_format | [bool](#bool) | optional | Set true to use the old proto1 MessageSet wire format for extensions. This is provided for backwards-compatibility with the MessageSet wire format. You should not use this for any other reason: It's less efficient, has fewer features, and is more complicated. - -The message must be defined exactly as follows: message Foo { option message_set_wire_format = true; extensions 4 to max; } Note that the message cannot have any defined fields; MessageSets only have extensions. - -All extensions of your type must be singular messages; e.g. they cannot be int32s, enums, or repeated messages. - -Because this is an option, the above two restrictions are not enforced by the protocol compiler. Default: false | -| no_standard_descriptor_accessor | [bool](#bool) | optional | Disables the generation of the standard "descriptor()" accessor, which can conflict with a field of the same name. This is meant to make migration from proto1 easier; new code should avoid fields named "descriptor". Default: false | -| deprecated | [bool](#bool) | optional | Is this message deprecated? Depending on the target platform, this can emit Deprecated annotations for the message, or it will be completely ignored; in the very least, this is a formalization for deprecating messages. Default: false | -| map_entry | [bool](#bool) | optional | Whether the message is an automatically generated map entry type for the maps field. - -For maps fields: map<KeyType, ValueType> map_field = 1; The parsed descriptor looks like: message MapFieldEntry { option map_entry = true; optional KeyType key = 1; optional ValueType value = 2; } repeated MapFieldEntry map_field = 1; - -Implementations may choose not to generate the map_entry=true message, but use a native map in the target language to hold the keys and values. The reflection APIs in such implementions still need to work as if the field is a repeated message field. - -NOTE: Do not set the option in .proto files. Always use the maps syntax instead. The option should only be implicitly set by the proto compiler parser. | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### MethodDescriptorProto -Describes a method of a service. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | | -| input_type | [string](#string) | optional | Input and output type names. These are resolved in the same way as FieldDescriptorProto.type_name, but must refer to a message type. | -| output_type | [string](#string) | optional | | -| options | [MethodOptions](#google.protobuf.MethodOptions) | optional | | -| client_streaming | [bool](#bool) | optional | Identifies if client streams multiple client messages Default: false | -| server_streaming | [bool](#bool) | optional | Identifies if server streams multiple server messages Default: false | - - - - - - - - -### MethodOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| deprecated | [bool](#bool) | optional | Is this method deprecated? Depending on the target platform, this can emit Deprecated annotations for the method, or it will be completely ignored; in the very least, this is a formalization for deprecating methods. Default: false | -| idempotency_level | [MethodOptions.IdempotencyLevel](#google.protobuf.MethodOptions.IdempotencyLevel) | optional | Default: IDEMPOTENCY_UNKNOWN | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### OneofDescriptorProto -Describes a oneof. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | | -| options | [OneofOptions](#google.protobuf.OneofOptions) | optional | | - - - - - - - - -### OneofOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### ServiceDescriptorProto -Describes a service. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | optional | | -| method | [MethodDescriptorProto](#google.protobuf.MethodDescriptorProto) | repeated | | -| options | [ServiceOptions](#google.protobuf.ServiceOptions) | optional | | - - - - - - - - -### ServiceOptions - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| deprecated | [bool](#bool) | optional | Is this service deprecated? Depending on the target platform, this can emit Deprecated annotations for the service, or it will be completely ignored; in the very least, this is a formalization for deprecating services. Default: false | -| uninterpreted_option | [UninterpretedOption](#google.protobuf.UninterpretedOption) | repeated | The parser stores options it doesn't recognize here. See above. | - - - - - - - - -### SourceCodeInfo -Encapsulates information about the original source file from which a -FileDescriptorProto was generated. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| location | [SourceCodeInfo.Location](#google.protobuf.SourceCodeInfo.Location) | repeated | A Location identifies a piece of source code in a .proto file which corresponds to a particular definition. This information is intended to be useful to IDEs, code indexers, documentation generators, and similar tools. - -For example, say we have a file like: message Foo { optional string foo = 1; } Let's look at just the field definition: optional string foo = 1; ^ ^^ ^^ ^ ^^^ a bc de f ghi We have the following locations: span path represents [a,i) [ 4, 0, 2, 0 ] The whole field definition. [a,b) [ 4, 0, 2, 0, 4 ] The label (optional). [c,d) [ 4, 0, 2, 0, 5 ] The type (string). [e,f) [ 4, 0, 2, 0, 1 ] The name (foo). [g,h) [ 4, 0, 2, 0, 3 ] The number (1). - -Notes: - A location may refer to a repeated field itself (i.e. not to any particular index within it). This is used whenever a set of elements are logically enclosed in a single code segment. For example, an entire extend block (possibly containing multiple extension definitions) will have an outer location whose path refers to the "extensions" repeated field without an index. - Multiple locations may have the same path. This happens when a single logical declaration is spread out across multiple places. The most obvious example is the "extend" block again -- there may be multiple extend blocks in the same scope, each of which will have the same path. - A location's span is not always a subset of its parent's span. For example, the "extendee" of an extension declaration appears at the beginning of the "extend" block and is shared by all extensions within the block. - Just because a location's span is a subset of some other location's span does not mean that it is a descendent. For example, a "group" defines both a type and a field in a single declaration. Thus, the locations corresponding to the type and field and their components will overlap. - Code which tries to interpret locations should probably be designed to ignore those that it doesn't understand, as more types of locations could be recorded in the future. | - - - - - - - - -### SourceCodeInfo.Location - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| path | [int32](#int32) | repeated | Identifies which part of the FileDescriptorProto was defined at this location. - -Each element is a field number or an index. They form a path from the root FileDescriptorProto to the place where the definition. For example, this path: [ 4, 3, 2, 7, 1 ] refers to: file.message_type(3) // 4, 3 .field(7) // 2, 7 .name() // 1 This is because FileDescriptorProto.message_type has field number 4: repeated DescriptorProto message_type = 4; and DescriptorProto.field has field number 2: repeated FieldDescriptorProto field = 2; and FieldDescriptorProto.name has field number 1: optional string name = 1; - -Thus, the above path gives the location of a field name. If we removed the last element: [ 4, 3, 2, 7 ] this path refers to the whole field declaration (from the beginning of the label to the terminating semicolon). | -| span | [int32](#int32) | repeated | Always has exactly three or four elements: start line, start column, end line (optional, otherwise assumed same as start line), end column. These are packed into a single field for efficiency. Note that line and column numbers are zero-based -- typically you will want to add 1 to each before displaying to a user. | -| leading_comments | [string](#string) | optional | If this SourceCodeInfo represents a complete declaration, these are any comments appearing before and after the declaration which appear to be attached to the declaration. - -A series of line comments appearing on consecutive lines, with no other tokens appearing on those lines, will be treated as a single comment. - -leading_detached_comments will keep paragraphs of comments that appear before (but not connected to) the current element. Each paragraph, separated by empty lines, will be one comment element in the repeated field. - -Only the comment content is provided; comment markers (e.g. //) are stripped out. For block comments, leading whitespace and an asterisk will be stripped from the beginning of each line other than the first. Newlines are included in the output. - -Examples: - - optional int32 foo = 1; // Comment attached to foo. // Comment attached to bar. optional int32 bar = 2; - - optional string baz = 3; // Comment attached to baz. // Another line attached to baz. - - // Comment attached to qux. // // Another line attached to qux. optional double qux = 4; - - // Detached comment for corge. This is not leading or trailing comments // to qux or corge because there are blank lines separating it from // both. - - // Detached comment for corge paragraph 2. - - optional string corge = 5; /* Block comment attached * to corge. Leading asterisks * will be removed. */ /* Block comment attached to * grault. */ optional int32 grault = 6; - - // ignored detached comments. | -| trailing_comments | [string](#string) | optional | | -| leading_detached_comments | [string](#string) | repeated | | - - - - - - - - -### UninterpretedOption -A message representing a option the parser does not recognize. This only -appears in options protos created by the compiler::Parser class. -DescriptorPool resolves these when building Descriptor objects. Therefore, -options protos in descriptor objects (e.g. returned by Descriptor::options(), -or produced by Descriptor::CopyTo()) will never have UninterpretedOptions -in them. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [UninterpretedOption.NamePart](#google.protobuf.UninterpretedOption.NamePart) | repeated | | -| identifier_value | [string](#string) | optional | The value of the uninterpreted option, in whatever type the tokenizer identified it as during parsing. Exactly one of these should be set. | -| positive_int_value | [uint64](#uint64) | optional | | -| negative_int_value | [int64](#int64) | optional | | -| double_value | [double](#double) | optional | | -| string_value | [bytes](#bytes) | optional | | -| aggregate_value | [string](#string) | optional | | - - - - - - - - -### UninterpretedOption.NamePart -The name of the uninterpreted option. Each string represents a segment in -a dot-separated name. is_extension is true iff a segment represents an -extension (denoted with parentheses in options specs in .proto files). -E.g.,{ ["foo", false], ["bar.baz", true], ["qux", false] } represents -"foo.(bar.baz).qux". - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name_part | [string](#string) | required | | -| is_extension | [bool](#bool) | required | | - - - - - - - - - - -### FieldDescriptorProto.Label - - -| Name | Number | Description | -| ---- | ------ | ----------- | -| LABEL_OPTIONAL | 1 | 0 is reserved for errors | -| LABEL_REQUIRED | 2 | | -| LABEL_REPEATED | 3 | | - - - - - -### FieldDescriptorProto.Type - - -| Name | Number | Description | -| ---- | ------ | ----------- | -| TYPE_DOUBLE | 1 | 0 is reserved for errors. Order is weird for historical reasons. | -| TYPE_FLOAT | 2 | | -| TYPE_INT64 | 3 | Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT64 if negative values are likely. | -| TYPE_UINT64 | 4 | | -| TYPE_INT32 | 5 | Not ZigZag encoded. Negative numbers take 10 bytes. Use TYPE_SINT32 if negative values are likely. | -| TYPE_FIXED64 | 6 | | -| TYPE_FIXED32 | 7 | | -| TYPE_BOOL | 8 | | -| TYPE_STRING | 9 | | -| TYPE_GROUP | 10 | Tag-delimited aggregate. Group type is deprecated and not supported in proto3. However, Proto3 implementations should still be able to parse the group wire format and treat group fields as unknown fields. | -| TYPE_MESSAGE | 11 | Length-delimited aggregate. | -| TYPE_BYTES | 12 | New in version 2. | -| TYPE_UINT32 | 13 | | -| TYPE_ENUM | 14 | | -| TYPE_SFIXED32 | 15 | | -| TYPE_SFIXED64 | 16 | | -| TYPE_SINT32 | 17 | Uses ZigZag encoding. | -| TYPE_SINT64 | 18 | Uses ZigZag encoding. | - - - - - -### FieldOptions.CType - - -| Name | Number | Description | -| ---- | ------ | ----------- | -| STRING | 0 | Default mode. | -| CORD | 1 | | -| STRING_PIECE | 2 | | - - - - - -### FieldOptions.JSType - - -| Name | Number | Description | -| ---- | ------ | ----------- | -| JS_NORMAL | 0 | Use the default type. | -| JS_STRING | 1 | Use JavaScript strings. | -| JS_NUMBER | 2 | Use JavaScript numbers. | - - - - - -### FileOptions.OptimizeMode -Generated classes can be optimized for speed or code size. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| SPEED | 1 | Generate complete code for parsing, serialization, | -| CODE_SIZE | 2 | etc. - -Use ReflectionOps to implement these methods. | -| LITE_RUNTIME | 3 | Generate code using MessageLite and the lite runtime. | - - - - - -### MethodOptions.IdempotencyLevel -Is this method side-effect-free (or safe in HTTP parlance), or idempotent, -or neither? HTTP based RPC implementation may choose GET verb for safe -methods, and PUT verb for idempotent methods instead of the default POST. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| IDEMPOTENCY_UNKNOWN | 0 | | -| NO_SIDE_EFFECTS | 1 | implies idempotent | -| IDEMPOTENT | 2 | idempotent, but may have side effects | - - - - - - - - - - - -

      Top

      - -## google/protobuf/duration.proto - - - - - -### Duration -A Duration represents a signed, fixed-length span of time represented -as a count of seconds and fractions of seconds at nanosecond -resolution. It is independent of any calendar and concepts like "day" -or "month". It is related to Timestamp in that the difference between -two Timestamp values is a Duration and it can be added or subtracted -from a Timestamp. Range is approximately +-10,000 years. - -# Examples - -Example 1: Compute Duration from two Timestamps in pseudo code. - - Timestamp start = ...; - Timestamp end = ...; - Duration duration = ...; - - duration.seconds = end.seconds - start.seconds; - duration.nanos = end.nanos - start.nanos; - - if (duration.seconds < 0 && duration.nanos > 0) { - duration.seconds += 1; - duration.nanos -= 1000000000; - } else if (durations.seconds > 0 && duration.nanos < 0) { - duration.seconds -= 1; - duration.nanos += 1000000000; - } - -Example 2: Compute Timestamp from Timestamp + Duration in pseudo code. - - Timestamp start = ...; - Duration duration = ...; - Timestamp end = ...; - - end.seconds = start.seconds + duration.seconds; - end.nanos = start.nanos + duration.nanos; - - if (end.nanos < 0) { - end.seconds -= 1; - end.nanos += 1000000000; - } else if (end.nanos >= 1000000000) { - end.seconds += 1; - end.nanos -= 1000000000; - } - -Example 3: Compute Duration from datetime.timedelta in Python. - - td = datetime.timedelta(days=3, minutes=10) - duration = Duration() - duration.FromTimedelta(td) - -# JSON Mapping - -In JSON format, the Duration type is encoded as a string rather than an -object, where the string ends in the suffix "s" (indicating seconds) and -is preceded by the number of seconds, with nanoseconds expressed as -fractional seconds. For example, 3 seconds with 0 nanoseconds should be -encoded in JSON format as "3s", while 3 seconds and 1 nanosecond should -be expressed in JSON format as "3.000000001s", and 3 seconds and 1 -microsecond should be expressed in JSON format as "3.000001s". - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| seconds | [int64](#int64) | | Signed seconds of the span of time. Must be from -315,576,000,000 to +315,576,000,000 inclusive. Note: these bounds are computed from: 60 sec/min * 60 min/hr * 24 hr/day * 365.25 days/year * 10000 years | -| nanos | [int32](#int32) | | Signed fractions of a second at nanosecond resolution of the span of time. Durations less than one second are represented with a 0 `seconds` field and a positive or negative `nanos` field. For durations of one second or more, a non-zero value for the `nanos` field must be of the same sign as the `seconds` field. Must be from -999,999,999 to +999,999,999 inclusive. | - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/empty.proto - - - - - -### Empty -A generic empty message that you can re-use to avoid defining duplicated -empty messages in your APIs. A typical example is to use it as the request -or the response type of an API method. For instance: - - service Foo { - rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty); - } - -The JSON representation for `Empty` is empty JSON object `{}`. - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/field_mask.proto - - - - - -### FieldMask -`FieldMask` represents a set of symbolic field paths, for example: - - paths: "f.a" - paths: "f.b.d" - -Here `f` represents a field in some root message, `a` and `b` -fields in the message found in `f`, and `d` a field found in the -message in `f.b`. - -Field masks are used to specify a subset of fields that should be -returned by a get operation or modified by an update operation. -Field masks also have a custom JSON encoding (see below). - -# Field Masks in Projections - -When used in the context of a projection, a response message or -sub-message is filtered by the API to only contain those fields as -specified in the mask. For example, if the mask in the previous -example is applied to a response message as follows: - - f { - a : 22 - b { - d : 1 - x : 2 - } - y : 13 - } - z: 8 - -The result will not contain specific values for fields x,y and z -(their value will be set to the default, and omitted in proto text -output): - - - f { - a : 22 - b { - d : 1 - } - } - -A repeated field is not allowed except at the last position of a -paths string. - -If a FieldMask object is not present in a get operation, the -operation applies to all fields (as if a FieldMask of all fields -had been specified). - -Note that a field mask does not necessarily apply to the -top-level response message. In case of a REST get operation, the -field mask applies directly to the response, but in case of a REST -list operation, the mask instead applies to each individual message -in the returned resource list. In case of a REST custom method, -other definitions may be used. Where the mask applies will be -clearly documented together with its declaration in the API. In -any case, the effect on the returned resource/resources is required -behavior for APIs. - -# Field Masks in Update Operations - -A field mask in update operations specifies which fields of the -targeted resource are going to be updated. The API is required -to only change the values of the fields as specified in the mask -and leave the others untouched. If a resource is passed in to -describe the updated values, the API ignores the values of all -fields not covered by the mask. - -If a repeated field is specified for an update operation, the existing -repeated values in the target resource will be overwritten by the new values. -Note that a repeated field is only allowed in the last position of a `paths` -string. - -If a sub-message is specified in the last position of the field mask for an -update operation, then the existing sub-message in the target resource is -overwritten. Given the target message: - - f { - b { - d : 1 - x : 2 - } - c : 1 - } - -And an update message: - - f { - b { - d : 10 - } - } - -then if the field mask is: - - paths: "f.b" - -then the result will be: - - f { - b { - d : 10 - } - c : 1 - } - -However, if the update mask was: - - paths: "f.b.d" - -then the result would be: - - f { - b { - d : 10 - x : 2 - } - c : 1 - } - -In order to reset a field's value to the default, the field must -be in the mask and set to the default value in the provided resource. -Hence, in order to reset all fields of a resource, provide a default -instance of the resource and set all fields in the mask, or do -not provide a mask as described below. - -If a field mask is not present on update, the operation applies to -all fields (as if a field mask of all fields has been specified). -Note that in the presence of schema evolution, this may mean that -fields the client does not know and has therefore not filled into -the request will be reset to their default. If this is unwanted -behavior, a specific service may require a client to always specify -a field mask, producing an error if not. - -As with get operations, the location of the resource which -describes the updated values in the request message depends on the -operation kind. In any case, the effect of the field mask is -required to be honored by the API. - -## Considerations for HTTP REST - -The HTTP kind of an update operation which uses a field mask must -be set to PATCH instead of PUT in order to satisfy HTTP semantics -(PUT must only be used for full updates). - -# JSON Encoding of Field Masks - -In JSON, a field mask is encoded as a single string where paths are -separated by a comma. Fields name in each path are converted -to/from lower-camel naming conventions. - -As an example, consider the following message declarations: - - message Profile { - User user = 1; - Photo photo = 2; - } - message User { - string display_name = 1; - string address = 2; - } - -In proto a field mask for `Profile` may look as such: - - mask { - paths: "user.display_name" - paths: "photo" - } - -In JSON, the same mask is represented as below: - - { - mask: "user.displayName,photo" - } - -# Field Masks and Oneof Fields - -Field masks treat fields in oneofs just as regular fields. Consider the -following message: - - message SampleMessage { - oneof test_oneof { - string name = 4; - SubMessage sub_message = 9; - } - } - -The field mask can be: - - mask { - paths: "name" - } - -Or: - - mask { - paths: "sub_message" - } - -Note that oneof type names ("test_oneof" in this case) cannot be used in -paths. - -## Field Mask Verification - -The implementation of any API method which has a FieldMask type field in the -request should verify the included field paths, and return an -`INVALID_ARGUMENT` error if any path is duplicated or unmappable. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| paths | [string](#string) | repeated | The set of field mask paths. | - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/source_context.proto - - - - - -### SourceContext -`SourceContext` represents information about the source of a -protobuf element, like the file in which it is defined. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| file_name | [string](#string) | | The path-qualified name of the .proto file that contained the associated protobuf element. For example: `"google/protobuf/source_context.proto"`. | - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/struct.proto - - - - - -### ListValue -`ListValue` is a wrapper around a repeated field of values. - -The JSON representation for `ListValue` is JSON array. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| values | [Value](#google.protobuf.Value) | repeated | Repeated field of dynamically typed values. | - - - - - - - - -### Struct -`Struct` represents a structured data value, consisting of fields -which map to dynamically typed values. In some languages, `Struct` -might be supported by a native representation. For example, in -scripting languages like JS a struct is represented as an -object. The details of that representation are described together -with the proto support for the language. - -The JSON representation for `Struct` is JSON object. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| fields | [Struct.FieldsEntry](#google.protobuf.Struct.FieldsEntry) | repeated | Unordered map of dynamically typed values. | - - - - - - - - -### Struct.FieldsEntry - - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| key | [string](#string) | | | -| value | [Value](#google.protobuf.Value) | | | - - - - - - - - -### Value -`Value` represents a dynamically typed value which can be either -null, a number, a string, a boolean, a recursive struct value, or a -list of values. A producer of value is expected to set one of that -variants, absence of any variant indicates an error. - -The JSON representation for `Value` is JSON value. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| null_value | [NullValue](#google.protobuf.NullValue) | | Represents a null value. | -| number_value | [double](#double) | | Represents a double value. | -| string_value | [string](#string) | | Represents a string value. | -| bool_value | [bool](#bool) | | Represents a boolean value. | -| struct_value | [Struct](#google.protobuf.Struct) | | Represents a structured value. | -| list_value | [ListValue](#google.protobuf.ListValue) | | Represents a repeated `Value`. | - - - - - - - - - - -### NullValue -`NullValue` is a singleton enumeration to represent the null value for the -`Value` type union. - - The JSON representation for `NullValue` is JSON `null`. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| NULL_VALUE | 0 | Null value. | - - - - - - - - - - - -

      Top

      - -## google/protobuf/timestamp.proto - - - - - -### Timestamp -A Timestamp represents a point in time independent of any time zone -or calendar, represented as seconds and fractions of seconds at -nanosecond resolution in UTC Epoch time. It is encoded using the -Proleptic Gregorian Calendar which extends the Gregorian calendar -backwards to year one. It is encoded assuming all minutes are 60 -seconds long, i.e. leap seconds are "smeared" so that no leap second -table is needed for interpretation. Range is from -0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. -By restricting to that range, we ensure that we can convert to -and from RFC 3339 date strings. -See [https://www.ietf.org/rfc/rfc3339.txt](https://www.ietf.org/rfc/rfc3339.txt). - -# Examples - -Example 1: Compute Timestamp from POSIX `time()`. - - Timestamp timestamp; - timestamp.set_seconds(time(NULL)); - timestamp.set_nanos(0); - -Example 2: Compute Timestamp from POSIX `gettimeofday()`. - - struct timeval tv; - gettimeofday(&tv, NULL); - - Timestamp timestamp; - timestamp.set_seconds(tv.tv_sec); - timestamp.set_nanos(tv.tv_usec * 1000); - -Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`. - - FILETIME ft; - GetSystemTimeAsFileTime(&ft); - UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime; - - // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z - // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z. - Timestamp timestamp; - timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL)); - timestamp.set_nanos((INT32) ((ticks % 10000000) * 100)); - -Example 4: Compute Timestamp from Java `System.currentTimeMillis()`. - - long millis = System.currentTimeMillis(); - - Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000) - .setNanos((int) ((millis % 1000) * 1000000)).build(); - - -Example 5: Compute Timestamp from current time in Python. - - timestamp = Timestamp() - timestamp.GetCurrentTime() - -# JSON Mapping - -In JSON format, the Timestamp type is encoded as a string in the -[RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the -format is "{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z" -where {year} is always expressed using four digits while {month}, {day}, -{hour}, {min}, and {sec} are zero-padded to two digits each. The fractional -seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution), -are optional. The "Z" suffix indicates the timezone ("UTC"); the timezone -is required. A proto3 JSON serializer should always use UTC (as indicated by -"Z") when printing the Timestamp type and a proto3 JSON parser should be -able to accept both UTC and other timezones (as indicated by an offset). - -For example, "2017-01-15T01:30:15.01Z" encodes 15.01 seconds past -01:30 UTC on January 15, 2017. - -In JavaScript, one can convert a Date object to this format using the -standard [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString] -method. In Python, a standard `datetime.datetime` object can be converted -to this format using [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) -with the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one -can use the Joda Time's [`ISODateTimeFormat.dateTime()`]( -http://www.joda.org/joda-time/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime-- -) to obtain a formatter capable of generating timestamps in this format. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| seconds | [int64](#int64) | | Represents seconds of UTC time since Unix epoch 1970-01-01T00:00:00Z. Must be from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59Z inclusive. | -| nanos | [int32](#int32) | | Non-negative fractions of a second at nanosecond resolution. Negative second values with fractions must still have non-negative nanos values that count forward in time. Must be from 0 to 999,999,999 inclusive. | - - - - - - - - - - - - - - - - -

      Top

      - -## google/protobuf/type.proto - - - - - -### Enum -Enum type definition. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | Enum type name. | -| enumvalue | [EnumValue](#google.protobuf.EnumValue) | repeated | Enum value definitions. | -| options | [Option](#google.protobuf.Option) | repeated | Protocol buffer options. | -| source_context | [SourceContext](#google.protobuf.SourceContext) | | The source context. | -| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax. | - - - - - - - - -### EnumValue -Enum value definition. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | Enum value name. | -| number | [int32](#int32) | | Enum value number. | -| options | [Option](#google.protobuf.Option) | repeated | Protocol buffer options. | - - - - - - - - -### Field -A single field of a message type. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| kind | [Field.Kind](#google.protobuf.Field.Kind) | | The field type. | -| cardinality | [Field.Cardinality](#google.protobuf.Field.Cardinality) | | The field cardinality. | -| number | [int32](#int32) | | The field number. | -| name | [string](#string) | | The field name. | -| type_url | [string](#string) | | The field type URL, without the scheme, for message or enumeration types. Example: `"type.googleapis.com/google.protobuf.Timestamp"`. | -| oneof_index | [int32](#int32) | | The index of the field type in `Type.oneofs`, for message or enumeration types. The first type has index 1; zero means the type is not in the list. | -| packed | [bool](#bool) | | Whether to use alternative packed wire representation. | -| options | [Option](#google.protobuf.Option) | repeated | The protocol buffer options. | -| json_name | [string](#string) | | The field JSON name. | -| default_value | [string](#string) | | The string value of the default value of this field. Proto2 syntax only. | - - - - - - - - -### Option -A protocol buffer option, which can be attached to a message, field, -enumeration, etc. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | The option's name. For protobuf built-in options (options defined in descriptor.proto), this is the short name. For example, `"map_entry"`. For custom options, it should be the fully-qualified name. For example, `"google.api.http"`. | -| value | [Any](#google.protobuf.Any) | | The option's value packed in an Any message. If the value is a primitive, the corresponding wrapper type defined in google/protobuf/wrappers.proto should be used. If the value is an enum, it should be stored as an int32 value using the google.protobuf.Int32Value type. | - - - - - - - - -### Type -A protocol buffer message type. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| name | [string](#string) | | The fully qualified message name. | -| fields | [Field](#google.protobuf.Field) | repeated | The list of fields. | -| oneofs | [string](#string) | repeated | The list of types appearing in `oneof` definitions in this type. | -| options | [Option](#google.protobuf.Option) | repeated | The protocol buffer options. | -| source_context | [SourceContext](#google.protobuf.SourceContext) | | The source context. | -| syntax | [Syntax](#google.protobuf.Syntax) | | The source syntax. | - - - - - - - - - - -### Field.Cardinality -Whether a field is optional, required, or repeated. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| CARDINALITY_UNKNOWN | 0 | For fields with unknown cardinality. | -| CARDINALITY_OPTIONAL | 1 | For optional fields. | -| CARDINALITY_REQUIRED | 2 | For required fields. Proto2 syntax only. | -| CARDINALITY_REPEATED | 3 | For repeated fields. | - - - - - -### Field.Kind -Basic field types. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| TYPE_UNKNOWN | 0 | Field type unknown. | -| TYPE_DOUBLE | 1 | Field type double. | -| TYPE_FLOAT | 2 | Field type float. | -| TYPE_INT64 | 3 | Field type int64. | -| TYPE_UINT64 | 4 | Field type uint64. | -| TYPE_INT32 | 5 | Field type int32. | -| TYPE_FIXED64 | 6 | Field type fixed64. | -| TYPE_FIXED32 | 7 | Field type fixed32. | -| TYPE_BOOL | 8 | Field type bool. | -| TYPE_STRING | 9 | Field type string. | -| TYPE_GROUP | 10 | Field type group. Proto2 syntax only, and deprecated. | -| TYPE_MESSAGE | 11 | Field type message. | -| TYPE_BYTES | 12 | Field type bytes. | -| TYPE_UINT32 | 13 | Field type uint32. | -| TYPE_ENUM | 14 | Field type enum. | -| TYPE_SFIXED32 | 15 | Field type sfixed32. | -| TYPE_SFIXED64 | 16 | Field type sfixed64. | -| TYPE_SINT32 | 17 | Field type sint32. | -| TYPE_SINT64 | 18 | Field type sint64. | - - - - - -### Syntax -The syntax in which a protocol buffer element is defined. - -| Name | Number | Description | -| ---- | ------ | ----------- | -| SYNTAX_PROTO2 | 0 | Syntax `proto2`. | -| SYNTAX_PROTO3 | 1 | Syntax `proto3`. | - - - - - - - - - - - -

      Top

      - -## google/protobuf/wrappers.proto - - - - - -### BoolValue -Wrapper message for `bool`. - -The JSON representation for `BoolValue` is JSON `true` and `false`. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [bool](#bool) | | The bool value. | - - - - - - - - -### BytesValue -Wrapper message for `bytes`. - -The JSON representation for `BytesValue` is JSON string. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [bytes](#bytes) | | The bytes value. | - - - - - - - - -### DoubleValue -Wrapper message for `double`. - -The JSON representation for `DoubleValue` is JSON number. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [double](#double) | | The double value. | - - - - - - - - -### FloatValue -Wrapper message for `float`. - -The JSON representation for `FloatValue` is JSON number. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [float](#float) | | The float value. | - - - - - - - - -### Int32Value -Wrapper message for `int32`. - -The JSON representation for `Int32Value` is JSON number. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [int32](#int32) | | The int32 value. | - - - - - - - - -### Int64Value -Wrapper message for `int64`. - -The JSON representation for `Int64Value` is JSON string. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [int64](#int64) | | The int64 value. | - - - - - - - - -### StringValue -Wrapper message for `string`. - -The JSON representation for `StringValue` is JSON string. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [string](#string) | | The string value. | - - - - - - - - -### UInt32Value -Wrapper message for `uint32`. - -The JSON representation for `UInt32Value` is JSON number. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [uint32](#uint32) | | The uint32 value. | - - - - - - - - -### UInt64Value -Wrapper message for `uint64`. - -The JSON representation for `UInt64Value` is JSON string. - - -| Field | Type | Label | Description | -| ----- | ---- | ----- | ----------- | -| value | [uint64](#uint64) | | The uint64 value. | - - - - - - - - - - - - - - -

      Top

      diff --git a/example-project/build.gradle b/example-project/build.gradle index ed58aa2..31366ed 100644 --- a/example-project/build.gradle +++ b/example-project/build.gradle @@ -5,7 +5,7 @@ buildscript { "grpc": '1.15.1', "kotlin": '1.3.11', "coroutines": '1.1.0', - "krotoplus": '0.2.2-SNAPSHOT' + "krotoplus": '0.2.2-RC1' ] } diff --git a/protoc-gen-kroto-plus/docs/build.gradle b/protoc-gen-kroto-plus/docs/build.gradle index 3458c60..e82ea76 100644 --- a/protoc-gen-kroto-plus/docs/build.gradle +++ b/protoc-gen-kroto-plus/docs/build.gradle @@ -3,15 +3,20 @@ apply plugin: 'com.google.protobuf' def isGoLangPresent = hasGolang() sourceSets{ - html { compileClasspath = configurations.compileOnly } - markdown { compileClasspath = configurations.compileOnly } + def protoSrcs = "${project(":protoc-gen-kroto-plus").projectDir}/src/main/proto" + + html { + proto{ srcDir protoSrcs } + compileClasspath = configurations.compileOnly + } + markdown { + proto{ srcDir protoSrcs } + compileClasspath = configurations.compileOnly + } } dependencies{ compileOnly "com.google.protobuf:protobuf-java:${versions.protobuf}" - - htmlProtobuf project(":protoc-gen-kroto-plus") - markdownProtobuf project(":protoc-gen-kroto-plus") }