Line data    Source code

       1              : #ifndef BIGQUERY_EMULATOR_BACKEND_ENGINE_SEMANTIC_ERROR_H_
       2              : #define BIGQUERY_EMULATOR_BACKEND_ENGINE_SEMANTIC_ERROR_H_
       3              : 
       4              : // Semantic-executor structured errors.
       5              : //
       6              : // Every evaluation failure surfaces an `absl::Status` whose code is
       7              : // `absl::StatusCode::kInvalidArgument` (the BigQuery REST envelope
       8              : // for an in-query runtime error) carrying a `SemanticErrorReason`
       9              : // payload. The gateway maps the payload onto the BigQuery REST
      10              : // `error.errors[0].reason` token; see
      11              : // `docs/ENGINE_POLICY.md` "Step 7".
      12              : //
      13              : // The plan rule is "no silent approximation": the semantic executor
      14              : // owns the BigQuery-exact error surface. Every reason in the enum
      15              : // below corresponds to a distinct BigQuery REST `reason` value the
      16              : // real product returns for the matching failure class.
      17              : 
      18              : #include <ostream>
      19              : #include <string>
      20              : 
      21              : #include "absl/status/status.h"
      22              : #include "absl/strings/string_view.h"
      23              : 
      24              : namespace bigquery_emulator {
      25              : namespace backend {
      26              : namespace engine {
      27              : namespace semantic {
      28              : 
      29              : // Classification for an evaluation-time failure. Each value lines up
      30              : // 1:1 with a BigQuery REST `error.errors[0].reason` token so the
      31              : // gateway can translate a `SemanticError` payload into the wire
      32              : // error envelope without losing fidelity. Adding a new value here
      33              : // MUST be paired with a matching gateway-side mapping update.
      34              : enum class SemanticErrorReason {
      35              :   // Generic INVALID_ARGUMENT (BigQuery REST `invalidQuery`). Use
      36              :   // sparingly; reach for one of the more specific reasons below
      37              :   // whenever possible.
      38              :   kInvalidArgument = 0,
      39              :   // Division (or modulo) by zero. BigQuery surfaces this as
      40              :   // `divisionByZero` in the REST error envelope.
      41              :   kDivisionByZero = 1,
      42              :   // Arithmetic overflow on the current numeric type. BigQuery
      43              :   // surfaces this as `overflow`.
      44              :   kOverflow = 2,
      45              :   // A function / shape the semantic executor recognizes but has
      46              :   // not yet implemented. BigQuery surfaces this as `notImplemented`;
      47              :   // the coordinator may translate it to gRPC UNIMPLEMENTED so the
      48              :   // gateway folds it into the standard `notImplemented` reason.
      49              :   kNotImplemented = 3,
      50              : };
      51              : 
      52              : // String form of `reason` used in log lines / debug output. The
      53              : // returned `string_view` references a static literal; callers do
      54              : // not own it.
      55              : absl::string_view SemanticErrorReasonName(SemanticErrorReason reason);
      56              : 
      57              : // BigQuery REST `error.errors[0].reason` token for `reason`. The
      58              : // returned `string_view` references a static literal.
      59              : absl::string_view BigQueryReasonToken(SemanticErrorReason reason);
      60              : 
      61              : // Build the `absl::Status` payload that carries the structured
      62              : // error. The status code is INVALID_ARGUMENT for every reason
      63              : // except `kNotImplemented`, which uses UNIMPLEMENTED so the gateway
      64              : // maps it onto BigQuery's `notImplemented` reason without an
      65              : // explicit payload lookup. The `message` is rendered verbatim onto
      66              : // the status message.
      67              : absl::Status MakeSemanticError(SemanticErrorReason reason,
      68              :                                absl::string_view message);
      69              : 
      70              : // Extract the `SemanticErrorReason` payload from `status`. Returns
      71              : // `kInvalidArgument` when `status` is OK or carries no semantic
      72              : // payload, so callers do not have to guard the call.
      73              : SemanticErrorReason GetSemanticErrorReason(const absl::Status& status);
      74              : 
      75              : // String key used to attach the reason on the absl::Status payload
      76              : // map. Exported so the coordinator / gateway can read the payload
      77              : // off a status that crossed an executor boundary.
      78              : inline constexpr absl::string_view kSemanticErrorReasonPayloadUrl =
      79              :     "type.googleapis.com/bigquery_emulator.semantic.ErrorReason";
      80              : 
      81            0 : inline std::ostream& operator<<(std::ostream& os, SemanticErrorReason reason) {
      82            0 :   return os << SemanticErrorReasonName(reason);
      83            0 : }
      84              : 
      85              : }  // namespace semantic
      86              : }  // namespace engine
      87              : }  // namespace backend
      88              : }  // namespace bigquery_emulator
      89              : 
      90              : #endif  // BIGQUERY_EMULATOR_BACKEND_ENGINE_SEMANTIC_ERROR_H_