diff --git a/content/best-practices/1-1-1.md b/content/best-practices/1-1-1.md index 3f07e2f1c..62462cc64 100644 --- a/content/best-practices/1-1-1.md +++ b/content/best-practices/1-1-1.md @@ -4,6 +4,7 @@ weight = 105 linkTitle = "1-1-1 Best Practice" description = "All proto definitions should have one top-level element and build target per file." type = "docs" +aliases = "/programming-guides/1-1-1" +++ The 1-1-1 best practice is to keep every proto_library and .proto file as small diff --git a/content/best-practices/api.md b/content/best-practices/api.md index 3ba341af7..c954ec119 100644 --- a/content/best-practices/api.md +++ b/content/best-practices/api.md @@ -3,13 +3,14 @@ title = "API Best Practices" weight = 100 description = "A future-proof API is surprisingly hard to get right. The suggestions in this document make trade-offs to favor long-term, bug-free evolution." type = "docs" +aliases = "/programming-guides/api" +++ Updated for proto3. Patches welcome! This doc is a complement to -[Proto Best Practices](/programming-guides/dos-donts). -It's not a prescription for Java/C++/Go and other APIs. +[Proto Best Practices](/best-practices/dos-donts). It's +not a prescription for Java/C++/Go and other APIs. If you see a proto straying from these guidelines in a code review, point the author to this topic and help spread the word. @@ -730,31 +731,6 @@ your service name, even if it is defined inside a specific package. For example, a service named `Watcher` is likely to cause problems; something like `MyProjectWatcher` would be better. -## Ensure Every RPC Specifies and Enforces a (Permissive) Deadline {#every-rpc-deadline} - -By default, an RPC does not have a timeout. Since a request may tie up backend -resources that are only released on completion, setting a default deadline that -allows all well-behaving requests to finish is a good defensive practice. Not -enforcing one has in the past caused -severe problems for major services . RPC clients -should still set a deadline on outgoing RPCs and will typically do so by default -when they use standard frameworks. A deadline may and typically will be -overwritten by a shorter deadline attached to a request. - -Setting the `deadline` option clearly communicates the RPC -deadline to your clients, and is respected and enforced by standard frameworks: - -```proto -rpc Foo(FooRequest) returns (FooResponse) { - option deadline = x; // there is no globally good default -} -``` - -Choosing a deadline value will especially impact how your system acts under -load. For existing services, it is critical to evaluate existing client behavior -before enforcing new deadlines to avoid breaking clients (consult SRE). In some -cases, it may not be possible to enforce a shorter deadline after the fact. - ## Bound Request and Response Sizes {#bound-req-res-sizes} Request and response sizes should be bounded. diff --git a/content/best-practices/dos-donts.md b/content/best-practices/dos-donts.md index 71e9b21a5..df9610aec 100644 --- a/content/best-practices/dos-donts.md +++ b/content/best-practices/dos-donts.md @@ -3,6 +3,7 @@ title = "Proto Best Practices" weight = 90 description = "Shares vetted best practices for authoring Protocol Buffers." type = "docs" +aliases = "/programming-guides/dos-donts" +++ Clients and servers are never updated at exactly the same time - even when you diff --git a/content/editions/overview.md b/content/editions/overview.md index 514978349..ee46ea8ce 100644 --- a/content/editions/overview.md +++ b/content/editions/overview.md @@ -127,6 +127,8 @@ edition = "2023"; package com.example; +option features.utf8_validation = NONE; + message Player { // fields have explicit presence, so no explicit setting needed string name = 1 [default = "N/A"]; diff --git a/content/overview.md b/content/overview.md index 48d363960..3f34ec28d 100644 --- a/content/overview.md +++ b/content/overview.md @@ -279,7 +279,7 @@ Protocol buffers support many scalar value types, including integers that use both variable-length encoding and fixed sizes. You can also create your own composite data types by defining messages that are, themselves, data types that you can assign to a field. In addition to the simple and composite value types, -several [common types](/programming-guides/dos-donts#common) +several [common types](/best-practices/dos-donts#common) are published. ## History {#history} diff --git a/content/programming-guides/editions.md b/content/programming-guides/editions.md index fc98b7b03..7a9233a85 100644 --- a/content/programming-guides/editions.md +++ b/content/programming-guides/editions.md @@ -977,8 +977,8 @@ to store your protocol buffer messages, the changes that you can make in your proto definition are different. {{% /alert %}} Check -[Proto Best Practices](/programming-guides/dos-donts) and -the following rules: +[Proto Best Practices](/best-practices/dos-donts) and the +following rules: * Don't change the field numbers for any existing fields. "Changing" the field number is equivalent to deleting the field and adding a new field with the diff --git a/content/programming-guides/proto2.md b/content/programming-guides/proto2.md index dcdfdd789..5738877d4 100644 --- a/content/programming-guides/proto2.md +++ b/content/programming-guides/proto2.md @@ -1025,8 +1025,8 @@ to store your protocol buffer messages, the changes that you can make in your proto definition are different. {{% /alert %}} Check -[Proto Best Practices](/programming-guides/dos-donts) and -the following rules: +[Proto Best Practices](/best-practices/dos-donts) and the +following rules: * Don't change the field numbers for any existing fields. "Changing" the field number is equivalent to deleting the field and adding a new field with the diff --git a/content/programming-guides/proto3.md b/content/programming-guides/proto3.md index 2a0aab30d..b0974df15 100644 --- a/content/programming-guides/proto3.md +++ b/content/programming-guides/proto3.md @@ -978,8 +978,8 @@ to store your protocol buffer messages, the changes that you can make in your proto definition are different. {{% /alert %}} Check -[Proto Best Practices](/programming-guides/dos-donts) and -the following rules: +[Proto Best Practices](/best-practices/dos-donts) and the +following rules: * Don't change the field numbers for any existing fields. "Changing" the field number is equivalent to deleting the field and adding a new field with the diff --git a/content/programming-guides/serialization-not-canonical.md b/content/programming-guides/serialization-not-canonical.md index 22c10fb13..507bd23f7 100644 --- a/content/programming-guides/serialization-not-canonical.md +++ b/content/programming-guides/serialization-not-canonical.md @@ -7,7 +7,7 @@ type = "docs" Many people want a serialized proto to canonically represent the contents of diff --git a/content/reference/go/opaque-faq.md b/content/reference/go/opaque-faq.md index 1e460978b..1ae30c7a4 100644 --- a/content/reference/go/opaque-faq.md +++ b/content/reference/go/opaque-faq.md @@ -90,6 +90,13 @@ you need to migrate said file to editions first. 1. Run your unit and integration tests, and then roll out to a staging environment. +## Are Errors Ignored with Lazy Decoding? {#lazydecodingerrors} + +No. +[`proto.Marshal`](https://pkg.go.dev/google.golang.org/protobuf/proto?tab=doc#Marshal) +will always validate the wire format data, even when decoding is deferred until +first access. + ## Where Can I Ask Questions or Report Issues? {#questions} If you found an issue with the `open2opaque` migration tool (such as incorrectly diff --git a/content/reference/rust/rust-redaction.md b/content/reference/rust/rust-redaction.md index 710a2e83a..8f430dcf7 100644 --- a/content/reference/rust/rust-redaction.md +++ b/content/reference/rust/rust-redaction.md @@ -16,7 +16,7 @@ Use the standard `fmt::Debug` ("`{:?}`" in format strings) on Protobuf messages for human-readable strings for logging, error messages, exceptions, and similar use cases. The output of this debug info is not intended to be machine-readable (unlike `TextFormat` and `JSON` which are -[not be used for debug output](/programming-guides/dos-donts#text-format-interchange)). +[not be used for debug output](/best-practices/dos-donts#text-format-interchange)). Using `fmt::Debug` enables redaction of some sensitive fields.