blob: ec43a3641a3bbd8f2c4053526fe69f7c68398467 [file] [log] [blame]
// Copyright 2018 The Feed Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
syntax = "proto2";
// import "google/protobuf/descriptor.proto";
package search.now.ui.piet;
option optimize_for=LITE_RUNTIME;
option java_package = "com.google.search.now.ui.piet";
option java_outer_classname = "ErrorsProto";
option cc_enable_arenas = true;
// Each error in Piet is described by a unique error code. Error levels indicate
// how the issue should be handled by server implementations and client
// implementations.
//
// Error handling in Piet is roughly modeled after Postel’s Law:
// “Be conservative in what you send, be liberal in what you accept”.
// https://en.wikipedia.org/wiki/Robustness_principle
//
// Servers will inform feature authors of problems in built protos as early and
// as loudly as possible, to ensure that we are conservative in sending protos
// to the client.
//
// Clients attempt their best in rendering protos, even if there are potential
// errors as long as there is a reasonable way to recover with work-arounds and
// defaults.
//
// Thus, two error levels are specified for each error code, allowing us to
// treat the same issue with different treatments on the server and client.
/* extend google.protobuf.EnumValueOptions {
// Determines how to treat a particular error code during server processing.
optional ErrorLevel server_error = 180986144
[default = UNKNOWN]; // Tag from CL number.
// Determines how to treat a particular error code during client processing.
optional ErrorLevel client_error = 180952597
[default = UNKNOWN]; // Tag from CL number.
} */
// clang-format off
// +----------+--------------------------+--------------------------+------------------------+
// | Level | Server | Client Prod Build | Client Dev Build |
// +----------+--------------------------+--------------------------+------------------------+
// | UNKNOWN | Should never be raised | Should never be raised | Should never be raised |
// +----------+--------------------------+--------------------------+------------------------+
// | FATAL | Log to Console | Log to Console | Crash |
// | | Fail when building proto | Log to Clearcut | |
// | | Fail tests | Drop all affected Frames | |
// +----------+--------------------------+--------------------------+------------------------+
// | ERROR | Log to Console | Log to Console | Crash |
// | | Refuse to build proto | Log to Clearcut | |
// | | Fail tests | Drop current Frame | |
// | | | Proceed with next Frame | |
// +----------+--------------------------+--------------------------+------------------------+
// | WARNING | Log to Console | Log to Console | Log to Console |
// | | OK to build proto | Log to Clearcut | Annotate Frame |
// | | Warn during tests | | |
// +----------+--------------------------+--------------------------+------------------------+
// | NOTICE | Log to Console | Nothing | Log to Console |
// | | OK to build proto | | |
// +----------+--------------------------+--------------------------+------------------------+
// | QUIET | Nothing | Nothing | Nothing |
// +----------+--------------------------+--------------------------+------------------------+
// clang-format on
//
// A note on client build types:
// * Dev: Only those builds used by developers who can see the source and have
// the power/ability to fix things should be considered Dev builds.
// E.g. AGSA built from source, or Chromium.
// * Prod: Most builds should be classified as prod, for the purposes of the
// table above.
// E.g. AGSA Stable, AGSA Alpha, AGSA Beta, Chrome Stable, Chrome Beta, Chrome
// Dev, Chrome Canary.
enum ErrorLevel {
// UNKNOWN is used when it is not possible to detect a particular kind of
// error, but is needed as a proto option. E.g. detecting a poor frame rate is
// not possible server-side, so `server_error = UNKNOWN` is appropriate for
// `ERR_POOR_FRAME_RATE`.
UNKNOWN = 0;
// Piet has encountered an invalid PietSharedState, which affects all Frames
// in the current response. Piet has determined that it cannot proceed with
// rendering any Frame at all.
FATAL = 1;
// Piet has encountered an invalid Frame, so it cannot proceed with rendering
// that particular Frame. It is possible to render all the other Frames in the
// current response.
ERROR = 2;
// Piet can use reasonably sane strategies to recover, but feature authors
// need to be aware that something unexpected happened.
WARNING = 3;
// Debug purposes only; notices are not visible in production builds.
NOTICE = 4;
// No reporting is performed; this class of errors can be silently ignored
// with no negative consequences. This level exists because certain types of
// errors can be treated as loud on the server but quiet on the client.
QUIET = 5;
}
enum ErrorCode {
// Not to be used for real errors; this only exists because proto enums must
// have a default value.
ERR_UNSPECIFIED = 0 /* [
// Die if ever used.
(server_error) = FATAL,
// Die if ever used.
(client_error) = FATAL
] */;
// ---------------------------------------------------------------------------
// Missing or Duplicate IDs.
// Fields start at ID 1.
// ---------------------------------------------------------------------------
// When a Template cannot be located, it only affects Frames that reference
// it, so we can proceed to render other unaffected Frames, making this an
// ERROR, not FATAL.
ERR_MISSING_TEMPLATE = 5 /* [
// Server should flag to feature authors when a Template is missing.
(server_error) = ERROR,
// Clients cannot render a Frame with missing Templates, so drop the Frame.
(client_error) = ERROR
] */;
// When two or more Templates with the same conflicting ID are found in
// PietSharedState, rendering of all Frames becomes unpredictable, making this
// FATAL.
ERR_DUPLICATE_TEMPLATE = 6 /* [
// Server should fail to build the proto containing duplicate Templates.
(server_error) = FATAL,
// Client should drop the affected Frame, but continue to render others.
(client_error) = ERROR
] */;
// When a stylesheet cannot be located, it only affects Frames that reference
// it, so we can proceed to render other unaffected Frames, making this an
// ERROR, not FATAL.
ERR_MISSING_STYLESHEET = 1 /* [
// Server should flag to feature authors when a Stylesheet is missing.
(server_error) = ERROR,
// Clients cannot render a Frame with missing Stylesheets, so drop the
// Frame.
(client_error) = ERROR
] */;
// When two or more Stylesheets with the same conflicting ID are found in
// PietSharedState, rendering of all Frames becomes unpredictable, making this
// FATAL.
ERR_DUPLICATE_STYLESHEET = 2 /* [
// Server should fail to build the proto containing duplicate Stylesheets.
(server_error) = FATAL,
// Client should drop the affected Frame, but continue to render others.
(client_error) = ERROR
] */;
ERR_MISSING_STYLE = 3 /* [
// Server should flag to feature authors when a Style is missing.
(server_error) = ERROR,
// Clients should use the default style instead.
(client_error) = NOTICE
] */;
// If two or more Styles with the same conflicting ID are found in the same
// BindingContext, rendering of the affected Frame is unpredictable.
ERR_DUPLICATE_STYLE = 4 /* [
// Server should flag to feature authors when duplicate styles are present.
(server_error) = ERROR,
// Clients prefer to avoid dropping Frames, so pick a matching style and
// continue to render. The choosing of which matching style is used is
// undefined.
(client_error) = WARNING
] */;
// If a BindingValue is missing for a BindingRef that is required (i.e. not
// marked is_optional), this error is raised.
ERR_MISSING_BINDING_VALUE = 8 /* [
// Server should flag to feature authors when an expected BindingValue is
// missing.
(server_error) = ERROR,
// Clients cannot render a Frame until all bindings are resolved, so drop
// this Frame.
(client_error) = ERROR
] */;
// If two or more BindingValues with the same conflicting ID are found in the
// same binding context, rendering of the affected Frame is unpredictable.
ERR_DUPLICATE_BINDING_VALUE = 9 /* [
// Server should flag to feature authors when duplicate BindingValues are
// present.
(server_error) = ERROR,
// Clients prefer to avoid dropping Frames, so pick the first matching
// BindingValue and continue to render.
(client_error) = ERROR
] */;
// BindingValues must be of the same type as the BindingRefs they are expected
// to replace at runtime.
ERR_BINDING_VALUE_TYPE_MISMATCH = 10 /* [
// Server should flag to feature authors when a BindingValue is of the wrong
// type.
(server_error) = ERROR,
// Clients cannot render a Frame with the wrong types of bindings, so drop
// this Frame.
(client_error) = ERROR
] */;
// Bindings are not supported in Frames or within Bound Elements.
ERR_UNSUPPORTED_CONTEXT_FOR_BINDING = 11 /* [
// Bindings will not work in this context
(server_error) = ERROR,
// Clients might support bindings in this context.
(client_error) = WARNING
] */;
// ---------------------------------------------------------------------------
// Missing required proto fields, or invalid values.
// Fields start at ID 101.
// ---------------------------------------------------------------------------
// If and only if *all* fonts specified in the style are unavailable on the
// client at runtime, this error will be raised. If at least one font (from
// among the ordered list of fonts) is available, then this error MUST NOT be
// raised.
ERR_MISSING_FONTS = 101 /* [
// Server won’t know about available fonts.
(server_error) = UNKNOWN,
// Client SHOULD use the default font.
(client_error) = NOTICE
] */;
// If and only if *all* ImageSources specified for a single ImageElement lack
// a valid URL this error should be raised. If at least one URL is present,
// this error MUST NOT be raised. Note that this error is only related to
// whether a URL is present or absent. Adverse network conditions should have
// no impact on this, and MUST NOT raise this error.
ERR_MISSING_IMAGE_URL = 102 /* [
// Server should flag to feature authors when image URLs are absent.
(server_error) = ERROR,
// Clients prefer to avoid dropping Frames, so they continue to render the
// rest of the Frame, substituting the missing image with a gray box.
(client_error) = WARNING
] */;
// If and only if *all* ImageSources specified for a single ImageElement
// cannot be located at runtime (due of a temporary network issue, or if the
// asset cannot be located in the app binary), this error should be raised.
// If at least one URL can be correctly resolved, this error MUST NOT be
// raised.
ERR_IMAGE_UNAVAILABLE = 103 /* [
// Servers will not be able to detect runtime issues with network conditions
// or app resources.
(server_error) = UNKNOWN,
// Clients may face adverse network conditions, preventing an image from
// being downloaded, or may receive a URL for an asset that does not exist.
(client_error) = WARNING
] */;
// If Piet encounters a CustomElement, and the Host is unable to locate a
// custom renderer for that CustomElement, this error will be raised.
ERR_MISSING_CUSTOM_ELEMENT_RENDERER = 104 /* [
// Server cannot know about the availability of renderers at runtime.
(server_error) = UNKNOWN,
// Piet will display an empty gray area where the CustomElement should have
// been rendered, but the rest of the Frame should be rendered.
(client_error) = WARNING
] */;
// Gradient directions should be in the range [0, 360).
ERR_INVALID_GRADIENT_DIRECTION = 105 /* [
// There is no good reason for the server to provide values outside this
// range.
(server_error) = WARNING,
// Clients should quietly clamp values to within the acceptable range.
(client_error) = QUIET
] */;
// If an Action Handler delegate (which is part of a Piet Host) encounters an
// `Action` proto that it cannot handle (e.g. because none of the extensions
// it can process are present), this error will be raised.
ERR_MISSING_ACTION_HANDLER = 106 /* [
// Server cannot know about the availability of action handlers at runtime.
(server_error) = UNKNOWN,
// Interacting with such a Piet view will cause a warning to be displayed to
// the user.
(client_error) = WARNING
] */;
// If a GridCell with Content width has a content that is not TextElement or
// ImageElement, this error will be raised.
ERR_CONTENT_WIDTH_GRID_CELL_WITH_INVALID_CONTENT = 107 /* [
// Server should flag to feature authors when such data is given.
(server_error) = ERROR,
// Clients cannot render a Frame with this kind of error.
(client_error) = ERROR
] */;
// It does not make sense to have a GridCell where GridCellWidth is specified
// but nothing inside the GridCellWidth is populated. Looks like missing data.
ERR_GRID_CELL_WIDTH_WITHOUT_CONTENTS = 108 /* [
// Server should flag to feature authors when such data is given.
(server_error) = ERROR,
// Clients will use the default value but warn about missing data.
(client_error) = WARNING
] */;
// If a MediaQueryCondition is specified with any parameter unchanged from its
// default value, this error is raised.
ERR_INVALID_MEDIA_QUERY_CONDITION = 109 /* [
// Server should flag to feature authors when such data is given.
(server_error) = ERROR,
// Clients will ignore the MediaQueryCondition and continue rendering.
(client_error) = NOTICE
] */;
// If an Element is passed to an adapter but is missing the required type of
// content (ex. an Element without a TextElement in TextElementAdapter).
ERR_MISSING_ELEMENT_CONTENTS = 110 /* [
// Server should flag to feature authors when such data is given.
(server_error) = ERROR,
// Clients cannot render a Frame with this kind of error.
(client_error) = ERROR
] */;
// A proto is missing some of the content it is expected to have.
// Ex. getting an unrecognized value for an enum or oneof case.
ERR_MISSING_OR_UNHANDLED_CONTENT = 111 /* [
// Server should flag to feature authors when such data is given.
(server_error) = ERROR,
// Clients cannot render a Frame with this kind of error.
(client_error) = ERROR
] */;
// ---------------------------------------------------------------------------
// Performance Related.
// Fields start at ID 201.
// ---------------------------------------------------------------------------
// It is possible and likely that different client implementations of Piet
// will not support all features equally at all points of time. Incomplete
// implementations MAY raise this error to indicate their lack of support for
// certain Piet features. It is not guaranteed that every implementation will
// raise this error for every feature.
ERR_UNSUPPORTED_FEATURE = 201 /* [
// TODO: Expose a way for servers to know feature support across
// clients, which feature authors can use to decide whether to use a certain
// feature.
(server_error) = UNKNOWN,
// Clients should render the rest of the Frame except for the missing
// feature, with or without workarounds, e.g. if gradients are not
// supported, clients may choose to substitute a solid color instead.
(client_error) = WARNING
] */;
// Certain platforms, e.g. Android, have limitations on how large a proto can
// be, because it needs to be serialized/deserialized into structures with
// limited memory. On certain low-RAM devices, this error may be raised to
// inform the server of a potential performance implication.
ERR_PROTO_TOO_LARGE = 202 /* [
// Servers should not dictate how large a proto can be.
(server_error) = UNKNOWN,
// Clients that cannot handle large protos should raise this error.
(client_error) = ERROR
] */;
// If a Piet renderer is unable to render content at 60 fps, it attempts to
// inform the server. Feature authors can monitor the number of dropped frames
// and consider if they want to make improvements, e.g. simplifying the visual
// design to reduce nesting levels.
ERR_POOR_FRAME_RATE = 203 /* [
// Servers will not know about client frame rates.
(server_error) = UNKNOWN,
// Warnings should be logged to the server.
(client_error) = WARNING
] */;
// ChunkedText should be used only when there's more than one chunk in it,
// othewise, either ParameterizedText, or Image should be used.
ERR_CHUNKED_TEXT_WITH_SINGLE_CHUNK = 204 /* [
// Server should bring up a warning in case this is used, this has only
// performance penalty.
(server_error) = WARNING,
// Clients should render if possible.
(client_error) = QUIET
] */;
// ---------------------------------------------------------------------------
// Accessibility Related.
// Fields start at ID 301.
// ---------------------------------------------------------------------------
// Piet will attempt to provide accessibility-related guidance whenever
// possible. These should all be server_error:NOTICE (server should flag to
// feature authors) & client_error:QUIET (clients have no way to recover).
//
// E.g. Click targets below a certain size (typically 44×44 dp) will be
// flagged for review.
// ERR_CLICK_TARGET_TOO_SMALL
//
// Color contrast between elements close to each other impacts accessibility.
// ERR_COLOR_CONTRAST_TOO_LOW
}