R/telemetry.R

Defines functions otel_emit_log otel_event_attributes otel_is_sensitive_event_field otel_translate_event_key otel_event_severity otel_end_async_parent otel_restore_parent_in_worker otel_start_async_parent otel_span_context_from_headers otel_capture_context otel_with_active_span with_otel_span otel_record_http_result otel_note_error otel_mark_span_ok otel_set_span_attributes otel_http_attributes otel_replace_shiny_attributes otel_client_attributes otel_with_trace_attribute otel_shiny_attributes otel_current_shiny_session otel_token_response_attributes otel_mtls_endpoint_alias_attributes otel_sender_constraint_token_attributes otel_sender_constraint_client_attributes otel_introspect_elements otel_required_acr_values otel_http_content_type otel_browser_cookie_path_root otel_client_auth_style otel_requested_max_age otel_claim_targets otel_claims_requested otel_scope_count otel_scope_string otel_scope_tokens otel_join_values otel_count_items otel_http_url_full otel_http_port otel_http_host otel_attributes otel_scalar_attribute warn_about_async_otel_workers otel_logging_enabled otel_tracing_enabled otel_telemetry_warning

# This file contains the helpers that connect shinyOAuth to OpenTelemetry
# OpenTelemetry is the tracing and logging system used to observe what code is
# doing
# Used for creating spans and logs without repeating cleanup and attribute
# rules

# 1 Telemetry setup ------------------------------------------------------------

## 1.1 Switches and warnings ---------------------------------------------------

# Keep one stable instrumentation name so OTEL groups shinyOAuth spans and
# logs under the same scope.
otel_tracer_name <- "io.github.lukakoning.shinyOAuth" # nolint

#' Warn about OpenTelemetry setup failures
#'
#' Used by span and log helpers.
#'
#' @param context Short label for the failing OpenTelemetry operation.
#' @param error Caught condition describing the failure.
#' @return No meaningful return value; emits a warning side effect.
#' @keywords internal
#' @noRd
otel_telemetry_warning <- function(context, error) {
  warn_pkg(
    "OpenTelemetry disabled for this operation",
    c(
      "!" = paste0(
        "OpenTelemetry ",
        context,
        " was disabled for this operation: ",
        conditionMessage(error)
      )
    )
  )
}

#' Check whether tracing is enabled
#'
#' Reads the `shinyOAuth.otel_tracing_enabled` option before spans are started.
#'
#' @return `TRUE` when `getOption("shinyOAuth.otel_tracing_enabled", TRUE)` is
#'   enabled; otherwise `FALSE`.
#' @keywords internal
#' @noRd
otel_tracing_enabled <- function() {
  isTRUE(getOption("shinyOAuth.otel_tracing_enabled", TRUE))
}

#' Check whether OTEL logging is enabled
#'
#' Reads the `shinyOAuth.otel_logging_enabled` option before OTEL log records
#' are emitted.
#'
#' @return `TRUE` when `getOption("shinyOAuth.otel_logging_enabled", TRUE)` is
#'   enabled; otherwise `FALSE`.
#' @keywords internal
#' @noRd
otel_logging_enabled <- function() {
  isTRUE(getOption("shinyOAuth.otel_logging_enabled", TRUE))
}

#' Warn about async OTEL worker configuration
#'
#' Warns once when async OAuth work may emit telemetry from worker processes in
#' addition to the main R process. Used by async module setup.
#'
#' @return Invisibly returns `TRUE` when a warning is emitted; otherwise
#'   invisibly returns `FALSE`.
#' @keywords internal
#' @noRd
warn_about_async_otel_workers <- function() {
  otel_active <-
    (otel_tracing_enabled() && isTRUE(otel::is_tracing_enabled())) ||
    (otel_logging_enabled() && isTRUE(otel::is_logging_enabled()))

  if (!isTRUE(otel_active)) {
    return(invisible(FALSE))
  }

  warn_pkg(
    "Verify OpenTelemetry is configured in async workers",
    c(
      "!" = paste(
        "{.code oauth_module_server(async = TRUE)} will emit telemetry from",
        "background worker processes as well as the main R process"
      ),
      "i" = paste(
        "When OTEL is configured via environment variables, shinyOAuth",
        "captures the current OTEL_* values for each async task and",
        "reapplies them inside the worker before running OAuth logic"
      ),
      "i" = paste(
        "You can enable or disable exporters after workers start, but do so",
        "before dispatching the async work that should use the new settings"
      ),
      "i" = paste(
        "If OTEL is configured from R code instead of environment variables,",
        "run the same setup in each worker or recreate workers after",
        "changing it"
      )
    ),
    .frequency = "once",
    .frequency_id = "oauth_module_server_async_otel_workers"
  )

  invisible(TRUE)
}

# 2 Value normalization --------------------------------------------------------

## 2.1 Scalar and list helpers -------------------------------------------------

#' Normalize one OTEL scalar attribute value
#'
#' Used by attribute builders throughout the package.
#'
#' @param value Candidate attribute value.
#' @return A single OTEL-safe scalar value, or `NULL` when `value` should be
#'   skipped.
#' @keywords internal
#' @noRd
otel_scalar_attribute <- function(value) {
  if (is.null(value) || length(value) == 0) {
    return(NULL)
  }

  if (inherits(value, "POSIXt")) {
    return(as.character(value[[1]]))
  }

  if (is.list(value)) {
    return(NULL)
  }

  value <- value[[1]]

  if (is.character(value)) {
    if (length(value) != 1L || is.na(value) || !nzchar(value)) {
      return(NULL)
    }
    return(value)
  }

  if (is.logical(value)) {
    if (length(value) != 1L || is.na(value)) {
      return(NULL)
    }
    return(value)
  }

  if (is.integer(value)) {
    if (length(value) != 1L || is.na(value)) {
      return(NULL)
    }
    return(value)
  }

  if (is.numeric(value)) {
    if (length(value) != 1L || is.na(value) || !is.finite(value)) {
      return(NULL)
    }
    return(as.numeric(value))
  }

  out <- tryCatch(as.character(value), error = function(...) NULL)
  if (
    is.null(out) || length(out) == 0L || is.na(out[[1]]) || !nzchar(out[[1]])
  ) {
    return(NULL)
  }

  out[[1]]
}

#' Build an OTEL attributes object
#'
#' Used by span and log helpers.
#'
#' @param x Named list of candidate attributes.
#' @return An `otel::as_attributes(...)` object, or `NULL` when no usable
#'   attributes remain.
#' @keywords internal
#' @noRd
otel_attributes <- function(x) {
  if (is.null(x) || !length(x)) {
    return(NULL)
  }

  attrs <- list()
  for (nm in names(x)) {
    if (!is_valid_string(nm)) {
      next
    }
    value <- otel_scalar_attribute(x[[nm]])
    if (!is.null(value)) {
      attrs[[nm]] <- value
    }
  }

  attrs <- compact_list(attrs)
  if (!length(attrs)) {
    return(NULL)
  }

  otel::as_attributes(attrs)
}

#' Extract an HTTP host for telemetry
#'
#' Used by HTTP attribute builders.
#'
#' @param url URL string to inspect.
#' @return Hostname string, or `NULL` when the URL cannot be parsed.
#' @keywords internal
#' @noRd
otel_http_host <- function(url) {
  if (!is_valid_string(url)) {
    return(NULL)
  }

  parsed <- tryCatch(httr2::url_parse(url), error = function(...) NULL)
  if (is.null(parsed)) {
    return(NULL)
  }

  host <- parsed$hostname %||% NULL
  if (!is_valid_string(host)) {
    return(NULL)
  }

  tolower(host)
}

#' Extract an HTTP port for telemetry
#'
#' Used by HTTP attribute builders.
#'
#' @param url URL string to inspect.
#' @return Integer port number, or `NULL` when the URL cannot be parsed.
#' @keywords internal
#' @noRd
otel_http_port <- function(url) {
  if (!is_valid_string(url)) {
    return(NULL)
  }

  parsed <- tryCatch(httr2::url_parse(url), error = function(...) NULL)
  if (is.null(parsed)) {
    return(NULL)
  }

  port <- parsed$port %||% NULL
  if (!is.null(port) && !is.na(port) && nzchar(as.character(port))) {
    return(as.integer(port))
  }

  scheme <- tolower(as.character(parsed$scheme %||% ""))
  if (identical(scheme, "https")) {
    return(443L)
  }
  if (identical(scheme, "http")) {
    return(80L)
  }

  NULL
}

#' Sanitize an HTTP URL for telemetry
#'
#' Used by HTTP attribute builders to preserve the request target without
#' logging query strings, fragments, or userinfo.
#'
#' @param url URL string to inspect.
#' @return Sanitized absolute URL string, or `NULL` when the URL cannot be
#'   parsed.
#' @keywords internal
#' @noRd
otel_http_url_full <- function(url) {
  if (!is_valid_string(url)) {
    return(NULL)
  }

  parsed <- tryCatch(httr2::url_parse(url), error = function(...) NULL)
  if (is.null(parsed)) {
    return(NULL)
  }

  parsed$query <- NULL
  parsed$fragment <- NULL
  parsed$username <- NULL
  parsed$password <- NULL
  parsed$scheme <- tolower(parsed$scheme %||% "")
  parsed$hostname <- tolower(parsed$hostname %||% "")

  sanitized <- tryCatch(httr2::url_build(parsed), error = function(...) NULL)
  if (!is_valid_string(sanitized)) {
    return(NULL)
  }

  sanitized
}

#' Count telemetry items
#'
#' Used by telemetry summary helpers.
#'
#' @param x Vector-like value or list to count.
#' @return Integer item count.
#' @keywords internal
#' @noRd
otel_count_items <- function(x) {
  if (is.null(x)) {
    return(0L)
  }

  if (is.list(x)) {
    return(as.integer(length(x)))
  }

  x <- tryCatch(as.vector(x), error = function(...) x)
  x <- x[!is.na(x)]
  as.integer(length(x))
}

#' Join telemetry values into one string
#'
#' Flattens a value or list of values into a stable, space-separated string.
#' Used by telemetry helpers that need compact summaries of scopes, claims, or
#' content types for span and log attributes.
#'
#' @param x Vector-like value or list to join.
#' @param sep Separator inserted between values.
#' @param sort_values Whether to sort the unique values before joining.
#' @return A length-1 character string, or `NULL` when there are no usable
#'   values.
#' @keywords internal
#' @noRd
otel_join_values <- function(x, sep = " ", sort_values = TRUE) {
  if (is.null(x)) {
    return(NULL)
  }

  if (is.list(x)) {
    x <- unlist(x, recursive = TRUE, use.names = FALSE)
  }

  x <- tryCatch(as.vector(x), error = function(...) x)
  x <- as.character(x)
  x <- x[!is.na(x)]
  x <- trimws(x)
  x <- unique(x[nzchar(x)])

  if (!length(x)) {
    return(NULL)
  }

  if (isTRUE(sort_values)) {
    x <- sort(x)
  }

  paste(x, collapse = sep)
}

# 3 OAuth value summaries ------------------------------------------------------

## 3.1 Scopes, claims, and response fields -------------------------------------

#' Normalize scope tokens for telemetry
#'
#' Used by login and token telemetry helpers.
#'
#' @param scopes Raw scope input.
#' @param provider Optional provider object used when deciding whether to force
#'   `openid`.
#' @param ensure_openid Whether `openid` should be prepended when appropriate.
#' @param allow_commas Whether one comma-delimited string should be split.
#' @return A character vector of normalized scope tokens.
#' @keywords internal
#' @noRd
otel_scope_tokens <- function(
  scopes,
  provider = NULL,
  ensure_openid = FALSE,
  allow_commas = FALSE
) {
  if (is.null(scopes)) {
    tokens <- character()
  } else if (
    isTRUE(allow_commas) &&
      length(scopes) == 1L &&
      is_valid_string(as.character(scopes)[[1]]) &&
      grepl(",", as.character(scopes)[[1]], fixed = TRUE) &&
      !grepl(" ", as.character(scopes)[[1]], fixed = TRUE)
  ) {
    tokens <- unlist(
      strsplit(as.character(scopes)[[1]], ",", fixed = TRUE),
      use.names = FALSE
    )
  } else {
    tokens <- as_scope_tokens(scopes)
  }

  tokens <- as.character(tokens)
  tokens <- tokens[!is.na(tokens)]
  tokens <- trimws(tokens)
  tokens <- unique(tokens[nzchar(tokens)])

  if (
    isTRUE(ensure_openid) &&
      !is.null(provider) &&
      is_valid_string(provider@issuer) &&
      !("openid" %in% tokens)
  ) {
    tokens <- c("openid", tokens)
  }

  tokens
}

#' Join scope tokens for telemetry
#'
#' Used by telemetry attribute builders.
#'
#' @param scopes Raw scope input.
#' @param provider Optional provider object used when deciding whether to force
#'   `openid`.
#' @param ensure_openid Whether `openid` should be prepended when appropriate.
#' @param allow_commas Whether one comma-delimited string should be split.
#' @return A single space-delimited scope string, or `NULL` when no scopes
#'   survive normalization.
#' @keywords internal
#' @noRd
otel_scope_string <- function(
  scopes,
  provider = NULL,
  ensure_openid = FALSE,
  allow_commas = FALSE
) {
  otel_join_values(
    otel_scope_tokens(
      scopes = scopes,
      provider = provider,
      ensure_openid = ensure_openid,
      allow_commas = allow_commas
    ),
    sep = " ",
    sort_values = FALSE
  )
}

#' Count normalized scope tokens
#'
#' Used by telemetry summaries.
#'
#' @param scopes Raw scope input.
#' @param provider Optional provider object used when deciding whether to force
#'   `openid`.
#' @param ensure_openid Whether `openid` should be prepended when appropriate.
#' @param allow_commas Whether one comma-delimited string should be split.
#' @return Integer count of normalized scope tokens.
#' @keywords internal
#' @noRd
otel_scope_count <- function(
  scopes,
  provider = NULL,
  ensure_openid = FALSE,
  allow_commas = FALSE
) {
  as.integer(length(otel_scope_tokens(
    scopes = scopes,
    provider = provider,
    ensure_openid = ensure_openid,
    allow_commas = allow_commas
  )))
}

#' Check whether claims were requested
#'
#' Used by login telemetry helpers.
#'
#' @param claims Claims value from the client configuration.
#' @return `TRUE` when claims appear to be present; otherwise `FALSE`.
#' @keywords internal
#' @noRd
otel_claims_requested <- function(claims) {
  if (is.null(claims)) {
    return(FALSE)
  }

  if (is.list(claims)) {
    return(length(claims) > 0L)
  }

  is_valid_string(tryCatch(as.character(claims)[[1]], error = function(...) {
    NA_character_
  }))
}

#' Summarize requested claim targets
#'
#' Used by login telemetry helpers.
#'
#' @param claims Claims value as a list or JSON string.
#' @return Comma-separated top-level claim target names, or `NULL` when they
#'   cannot be determined.
#' @keywords internal
#' @noRd
otel_claim_targets <- function(claims) {
  if (is.null(claims)) {
    return(NULL)
  }

  if (is.character(claims)) {
    parsed <- tryCatch(
      jsonlite::fromJSON(claims, simplifyVector = FALSE),
      error = function(...) NULL
    )
    if (is.null(parsed)) {
      return(NULL)
    }
    claims <- parsed
  }

  if (!is.list(claims) || !length(claims)) {
    return(NULL)
  }

  otel_join_values(names(claims), sep = ",", sort_values = TRUE)
}

#' Read a provider max_age value for telemetry
#'
#' Used by login telemetry helpers.
#'
#' @param provider Provider object whose `extra_auth_params` are inspected.
#' @return Non-negative numeric `max_age`, or `NULL` when absent or invalid.
#' @keywords internal
#' @noRd
otel_requested_max_age <- function(provider) {
  if (is.null(provider)) {
    return(NULL)
  }

  inspect_auth_max_age(provider@extra_auth_params)$value
}

#' Read the client auth style for telemetry
#'
#' Used by login and token telemetry helpers.
#'
#' @param client OAuth client object.
#' @return Normalized auth-style string, or `NULL` when no client is supplied.
#' @keywords internal
#' @noRd
otel_client_auth_style <- function(client) {
  if (is.null(client)) {
    return(NULL)
  }

  normalize_token_auth_style(client@provider@token_auth_style %||% "header")
}

#' Check whether the browser cookie path is rooted
#'
#' Used by module telemetry helpers.
#'
#' @param browser_cookie_path Configured cookie path.
#' @return `TRUE` when the cookie path is rooted at `/`, `FALSE` when it is a
#'   valid non-root path, or `NULL` when the value is invalid.
#' @keywords internal
#' @noRd
otel_browser_cookie_path_root <- function(browser_cookie_path) {
  if (is.null(browser_cookie_path)) {
    return(TRUE)
  }

  if (!is_valid_string(browser_cookie_path)) {
    return(NULL)
  }

  identical(browser_cookie_path, "/")
}

#' Normalize an HTTP content type for telemetry
#'
#' Used by HTTP and span helpers.
#'
#' @param content_type Optional explicit content type string.
#' @param resp Optional httr2 response used when `content_type` is missing.
#' @return Lowercase media type without parameters, or `NULL`.
#' @keywords internal
#' @noRd
otel_http_content_type <- function(content_type = NULL, resp = NULL) {
  if (!is.null(resp) && inherits(resp, "httr2_response")) {
    content_type <- content_type %||%
      tryCatch(
        httr2::resp_header(resp, "content-type"),
        error = function(...) NULL
      )
  }

  if (!is_valid_string(content_type)) {
    return(NULL)
  }

  content_type <- tolower(trimws(as.character(content_type)[[1]]))
  content_type <- trimws(strsplit(content_type, ";", fixed = TRUE)[[1]][1])
  if (!nzchar(content_type)) {
    return(NULL)
  }

  content_type
}

#' Join required ACR values for telemetry
#'
#' Used by login telemetry helpers.
#'
#' @param values Character vector of ACR values.
#' @return A single joined string, or `NULL` when no usable values remain.
#' @keywords internal
#' @noRd
otel_required_acr_values <- function(values) {
  otel_join_values(values, sep = " ", sort_values = FALSE)
}

#' Join introspection elements for telemetry
#'
#' Used by token and login telemetry helpers.
#'
#' @param values Character vector of introspection checks.
#' @return A single joined string, or `NULL` when no usable values remain.
#' @keywords internal
#' @noRd
otel_introspect_elements <- function(values) {
  otel_join_values(values, sep = ",", sort_values = TRUE)
}

#' Build sender-constraint capability telemetry attributes
#'
#' Used by span attribute builders so DPoP and mTLS client capabilities are
#' visible on OTEL spans.
#'
#' @param client Optional OAuth client object.
#' @return A compact named list of sender-constraint capability attributes.
#' @keywords internal
#' @noRd
otel_sender_constraint_client_attributes <- function(client = NULL) {
  if (is.null(client) || !S7::S7_inherits(client, class = OAuthClient)) {
    return(list())
  }

  compact_list(list(
    oauth.dpop.configured = client_has_dpop(client),
    oauth.mtls.client_certificate = client_has_mtls_certificate(client),
    oauth.mtls.client_auth = client_uses_mtls_auth(client),
    oauth.mtls.certificate_bound_tokens = client_requests_certificate_bound_tokens(
      client
    )
  ))
}

#' Build sender-constraint token telemetry attributes
#'
#' Used by token and userinfo spans to describe DPoP or mTLS bindings on the
#' effective token being processed.
#'
#' @param client Optional OAuth client object.
#' @param token Optional [OAuthToken] object or raw access-token string.
#' @param token_set Optional token response list containing `access_token`,
#'   `token_type`, and `cnf`.
#' @param effective_token_type Optional effective token type after local
#'   inference.
#' @return A compact named list of sender-constraint token attributes.
#' @keywords internal
#' @noRd
otel_sender_constraint_token_attributes <- function(
  client = NULL,
  token = NULL,
  token_set = NULL,
  effective_token_type = NULL
) {
  access_token <- NULL
  cnf <- NULL
  explicit_token_type <- NA_character_

  if (is.list(token_set)) {
    access_token <- token_set$access_token %||% NULL
    cnf <- token_set$cnf %||% NULL
    explicit_token_type <- token_set$token_type %||% NA_character_
  } else if (S7::S7_inherits(token, class = OAuthToken)) {
    access_token <- token@access_token
    cnf <- token@cnf
    explicit_token_type <- token@token_type %||% NA_character_
  } else if (is_valid_string(token)) {
    access_token <- token
  }

  dpop_bound <- is_valid_string(token_cnf_jkt(
    token = token,
    access_token = access_token,
    cnf = cnf
  ))
  mtls_bound <- is_valid_string(token_cnf_x5t_s256(
    token = token,
    access_token = access_token,
    cnf = cnf
  ))

  inferred_dpop <- FALSE
  if (
    !is_valid_string(effective_token_type) &&
      S7::S7_inherits(client, class = OAuthClient) &&
      client_has_dpop(client) &&
      isTRUE(dpop_bound)
  ) {
    effective_token_type <- "DPoP"
    inferred_dpop <- TRUE
  }

  if (
    !isTRUE(inferred_dpop) &&
      !is_valid_string(explicit_token_type) &&
      S7::S7_inherits(client, class = OAuthClient) &&
      client_has_dpop(client) &&
      isTRUE(dpop_bound) &&
      is_dpop_token_type(effective_token_type %||% NA_character_)
  ) {
    inferred_dpop <- TRUE
  }

  compact_list(list(
    oauth.dpop.bound = isTRUE(dpop_bound),
    oauth.dpop.token_type_inferred = isTRUE(inferred_dpop),
    oauth.mtls.bound = isTRUE(mtls_bound)
  ))
}

#' Build mTLS endpoint alias telemetry attributes
#'
#' Used by HTTP span helpers so traces show when an RFC 8705 alias URL was
#' selected instead of the provider's base endpoint.
#'
#' @param provider Optional OAuth provider object.
#' @param endpoint Logical endpoint name.
#' @param url Resolved request URL.
#' @return A named list containing `oauth.mtls.endpoint_alias` when an alias was
#'   selected, otherwise an empty list.
#' @keywords internal
#' @noRd
otel_mtls_endpoint_alias_attributes <- function(
  provider = NULL,
  endpoint,
  url = NULL
) {
  if (
    is.null(provider) ||
      !S7::S7_inherits(provider, class = OAuthProvider) ||
      !is_valid_string(url)
  ) {
    return(list())
  }

  alias_names <- switch(
    endpoint,
    par_endpoint = c("par_endpoint", "pushed_authorization_request_endpoint"),
    endpoint
  )

  for (alias_name in alias_names) {
    alias_url <- provider@mtls_endpoint_aliases[[alias_name]] %||% NA_character_
    if (is_valid_string(alias_url) && identical(alias_url, url)) {
      return(list(oauth.mtls.endpoint_alias = alias_name))
    }
  }

  list()
}

#' Build token response telemetry attributes
#'
#' Used after token exchange and refresh work completes.
#'
#' @param token_set Token response list returned by token exchange or refresh
#'   code.
#' @param client Optional OAuth client object.
#' @param effective_token_type Optional effective token type after local
#'   inference.
#' @return A compact named list of OTEL-safe token response attributes.
#' @keywords internal
#' @noRd
otel_token_response_attributes <- function(
  token_set,
  client = NULL,
  effective_token_type = NULL
) {
  if (!is.list(token_set) || !length(token_set)) {
    return(list())
  }

  scope_tokens <- otel_scope_tokens(
    token_set$scope %||% NULL,
    allow_commas = TRUE
  )
  expires_in_present <- !is.null(token_set$expires_in)

  compact_list(c(
    list(
      oauth.token_type = otel_scalar_attribute(token_set$token_type %||% NULL),
      oauth.received_id_token = isTRUE(is_valid_string(token_set$id_token)),
      oauth.received_refresh_token = isTRUE(is_valid_string(
        token_set$refresh_token
      )),
      oauth.expires_in_present = isTRUE(expires_in_present),
      oauth.expires_in_synthesized = !isTRUE(expires_in_present),
      oauth.scope.present = length(scope_tokens) > 0L,
      oauth.scopes.granted = otel_scope_string(
        token_set$scope %||% NULL,
        allow_commas = TRUE
      )
    ),
    otel_sender_constraint_token_attributes(
      client = client,
      token_set = token_set,
      effective_token_type = effective_token_type
    )
  ))
}

# 4 Request and session attributes ---------------------------------------------

## 4.1 Shiny and HTTP context builders -----------------------------------------

#' Capture the current Shiny session context for telemetry
#'
#' Used when callers do not pass session context explicitly.
#'
#' @return Session-context list, or `NULL` when no usable context is available.
#' @keywords internal
#' @noRd
otel_current_shiny_session <- function() {
  event <- tryCatch(augment_with_shiny_context(list()), error = function(...) {
    list()
  })
  event$shiny_session %||% NULL
}

#' Build Shiny session telemetry attributes
#'
#' Used by client, event, and span helpers.
#'
#' @param shiny_session Optional precomputed session context. When omitted, the
#'   current session is inspected.
#' @return A named list of session-related telemetry attributes.
#' @keywords internal
#' @noRd
otel_shiny_attributes <- function(shiny_session = NULL) {
  shiny_session <- shiny_session %||% otel_current_shiny_session()
  shiny_session <- normalize_shiny_session_context(shiny_session)
  if (is.null(shiny_session)) {
    return(list())
  }

  http <- shiny_session$http %||% NULL
  server_address <- NULL
  http_method <- NULL
  if (is.list(http)) {
    server_address <- http$host %||% NULL
    http_method <- http$method %||% NULL
  }

  compact_list(list(
    shiny.session_token_digest = string_digest(shiny_session$token %||% NULL),
    shiny.session.is_async = isTRUE(shiny_session$is_async),
    shiny.session.main_process_id = as.integer(
      shiny_session$main_process_id %||% NA_integer_
    ),
    shiny.session.process_id = as.integer(
      shiny_session$process_id %||% NA_integer_
    ),
    http.request.method = http_method,
    server.address = server_address
  ))
}

#' Ensure a trace id attribute is present
#'
#' Used by span and log builders.
#'
#' @param attributes Existing attribute list.
#' @param trace_id Optional explicit trace id override.
#' @return The original or augmented attribute list.
#' @keywords internal
#' @noRd
otel_with_trace_attribute <- function(attributes = NULL, trace_id = NULL) {
  attrs <- attributes %||% list()
  trace_id <- otel_scalar_attribute(trace_id %||% get_current_trace_id())
  if (is.null(trace_id)) {
    return(attrs)
  }
  if (!("shinyoauth.trace_id" %in% names(attrs))) {
    attrs[["shinyoauth.trace_id"]] <- trace_id
  }
  attrs
}

#' Build common client telemetry attributes
#'
#' Used by login, token, and module code.
#'
#' @param client Optional OAuth client object.
#' @param module_id Optional Shiny module id.
#' @param shiny_session Optional Shiny session context.
#' @param async Optional async execution flag.
#' @param phase Optional operation phase label.
#' @param extra Named list of extra attributes to merge in.
#' @return A named list of OTEL-safe attributes.
#' @keywords internal
#' @noRd
otel_client_attributes <- function(
  client = NULL,
  module_id = NULL,
  shiny_session = NULL,
  async = NULL,
  phase = NULL,
  extra = list()
) {
  provider <- NULL
  issuer <- NULL
  client_id_digest <- NULL
  if (!is.null(client)) {
    provider <- client@provider@name %||% NULL
    issuer <- client@provider@issuer %||% NULL
    client_id_digest <- string_digest(client@client_id)
  }

  compact_list(c(
    list(
      oauth.provider.name = provider,
      oauth.provider.issuer = issuer,
      oauth.client_id_digest = client_id_digest,
      shiny.module_id = module_id,
      oauth.async = async,
      oauth.phase = phase
    ),
    otel_sender_constraint_client_attributes(client = client),
    otel_shiny_attributes(shiny_session = shiny_session),
    extra
  ))
}

#' Replace stale Shiny telemetry attributes
#'
#' Used when async work resumes in a worker process.
#'
#' @param attributes Existing attribute list.
#' @param shiny_session Fresh Shiny session context.
#' @return Updated attribute list.
#' @keywords internal
#' @noRd
otel_replace_shiny_attributes <- function(
  attributes = NULL,
  shiny_session = NULL
) {
  attrs <- attributes %||% list()
  if (is.null(shiny_session)) {
    return(attrs)
  }

  if (length(attrs)) {
    shiny_attr_names <- names(attrs) %in%
      "shiny.session_token_digest" |
      startsWith(names(attrs), "shiny.session.")
    attrs <- attrs[!shiny_attr_names]
  }

  compact_list(c(
    attrs,
    otel_shiny_attributes(shiny_session = shiny_session)
  ))
}

#' Build HTTP telemetry attributes
#'
#' Used by HTTP span helpers.
#'
#' @param method Optional HTTP method.
#' @param url Optional request or response URL.
#' @param resp Optional httr2 response.
#' @param status_code Optional explicit status code.
#' @param content_type Optional explicit content type.
#' @param extra Named list of additional attributes to merge in.
#' @return A named list of HTTP telemetry attributes.
#' @keywords internal
#' @noRd
otel_http_attributes <- function(
  method = NULL,
  url = NULL,
  resp = NULL,
  status_code = NULL,
  content_type = NULL,
  extra = list()
) {
  if (!is.null(resp) && inherits(resp, "httr2_response")) {
    status_code <- status_code %||%
      tryCatch(
        httr2::resp_status(resp),
        error = function(...) NULL
      )
    url <- url %||% tryCatch(httr2::resp_url(resp), error = function(...) NULL)
    content_type <- content_type %||% otel_http_content_type(resp = resp)
  }

  compact_list(c(
    list(
      http.request.method = method,
      url.full = otel_http_url_full(url),
      http.response.status_code = as.integer(status_code %||% NA_integer_),
      http.response.content_type = otel_http_content_type(
        content_type = content_type
      ),
      server.address = otel_http_host(url),
      server.port = otel_http_port(url)
    ),
    extra
  ))
}

# 5 Span helpers ---------------------------------------------------------------

## 5.1 Span lifecycle ----------------------------------------------------------

#' Set span attributes
#'
#' Used by HTTP and error helpers.
#'
#' @param span Target span, defaulting to the active span.
#' @param attributes Named list of candidate attributes.
#' @return Invisibly returns `NULL`.
#' @keywords internal
#' @noRd
otel_set_span_attributes <- function(span = NULL, attributes = list()) {
  if (!otel_tracing_enabled()) {
    return(invisible(NULL))
  }

  attributes <- compact_list(attributes)
  if (!length(attributes)) {
    return(invisible(NULL))
  }

  span <- span %||% otel::get_active_span()
  for (nm in names(attributes)) {
    value <- otel_scalar_attribute(attributes[[nm]])
    if (!is.null(value)) {
      try(span$set_attribute(nm, value), silent = TRUE)
    }
  }

  invisible(NULL)
}

#' Mark a span as successful
#'
#' Used when an instrumented operation completes without error.
#'
#' @param span Target span, defaulting to the active span.
#' @return Invisibly returns `NULL`.
#' @keywords internal
#' @noRd
otel_mark_span_ok <- function(span = NULL) {
  if (!otel_tracing_enabled()) {
    return(invisible(NULL))
  }

  span <- span %||% otel::get_active_span()
  try(span$set_status("ok"), silent = TRUE)
  invisible(NULL)
}

#' Record an error on a span
#'
#' Used when an instrumented operation fails.
#'
#' @param error Condition object to record.
#' @param span Target span, defaulting to the active span.
#' @param attributes Named list of extra error-related attributes.
#' @return Invisibly returns `NULL`.
#' @keywords internal
#' @noRd
otel_note_error <- function(error, span = NULL, attributes = list()) {
  if (!otel_tracing_enabled()) {
    return(invisible(NULL))
  }

  span <- span %||% otel::get_active_span()
  if (is.null(error)) {
    return(invisible(NULL))
  }

  error_classes <- class(error)
  error_type <- if (
    is.character(error_classes) &&
      length(error_classes) >= 1L &&
      is_valid_string(error_classes[[1]])
  ) {
    error_classes[[1]]
  } else {
    "error"
  }
  exception_message <- if (isTRUE(allow_expose_error_body())) {
    conditionMessage(error)
  } else {
    NULL
  }

  span_attrs <- compact_list(c(
    list(
      error.type = error_type
    ),
    attributes
  ))
  event_attrs <- compact_list(c(
    list(
      exception.type = error_type,
      exception.message = exception_message
    ),
    attributes
  ))

  otel_set_span_attributes(span = span, attributes = span_attrs)
  try(
    span$add_event(
      "exception",
      attributes = otel_attributes(event_attrs)
    ),
    silent = TRUE
  )
  try(
    span$set_status(
      "error",
      description = error_type
    ),
    silent = TRUE
  )

  invisible(NULL)
}

#' Record an HTTP result on a span
#'
#' Used after outbound requests complete.
#'
#' @param resp httr2 response to inspect.
#' @param span Target span, defaulting to the active span.
#' @return Invisibly returns `NULL`.
#' @keywords internal
#' @noRd
otel_record_http_result <- function(resp, span = NULL) {
  if (!otel_tracing_enabled()) {
    return(invisible(NULL))
  }

  if (is.null(resp) || !inherits(resp, "httr2_response")) {
    return(invisible(NULL))
  }

  span <- span %||% otel::get_active_span()
  status_code <- tryCatch(httr2::resp_status(resp), error = function(...) NULL)
  content_type <- otel_http_content_type(resp = resp)
  otel_set_span_attributes(
    span = span,
    attributes = compact_list(c(
      list(
        http.response.status_code = as.integer(status_code %||% NA_integer_),
        http.response.content_type = content_type
      ),
      attr(resp, "shinyOAuth.otel_attributes", exact = TRUE) %||% list()
    ))
  )

  if (
    !is.numeric(status_code) || length(status_code) != 1L || is.na(status_code)
  ) {
    return(invisible(NULL))
  }

  if (status_code < 300L) {
    try(span$set_status("ok"), silent = TRUE)
  } else {
    try(
      span$set_status("error", description = paste0("HTTP ", status_code)),
      silent = TRUE
    )
  }

  invisible(NULL)
}

#' Run code inside a local active OTEL span
#'
#' Used around login, token, and module operations.
#'
#' @param name Span name.
#' @param code Unevaluated code block to run.
#' @param attributes Optional named attribute list.
#' @param options Optional span options list.
#' @param mark_ok Whether successful completion should set span status to `ok`.
#' @param parent Optional explicit parent context.
#' @return The evaluated result of `code`.
#' @keywords internal
#' @noRd
with_otel_span <- function(
  name,
  code,
  attributes = NULL,
  options = NULL,
  mark_ok = TRUE,
  parent = NULL
) {
  code <- substitute(code)
  if (!otel_tracing_enabled()) {
    return(eval(code, envir = parent.frame()))
  }

  span_options <- options %||% list()
  if (!is.null(parent) || (length(parent) == 1L && is.na(parent))) {
    span_options$parent <- parent
  }

  span_started <- FALSE
  tryCatch(
    {
      otel::start_local_active_span(
        name = name,
        attributes = otel_attributes(otel_with_trace_attribute(attributes)),
        options = span_options,
        activation_scope = environment()
      )
      span_started <- TRUE
    },
    error = function(e) {
      otel_telemetry_warning("span", e)
    }
  )
  ok <- FALSE
  err <- NULL

  on.exit(
    {
      if (isTRUE(span_started)) {
        if (isTRUE(ok) && isTRUE(mark_ok)) {
          otel_mark_span_ok()
        } else if (!is.null(err)) {
          otel_note_error(err)
        }
      }
    },
    add = TRUE
  )

  tryCatch(
    {
      result <- eval(code, envir = parent.frame())
      ok <- TRUE
      result
    },
    error = function(e) {
      err <<- e
      stop(e)
    }
  )
}

#' Run code with an existing active span
#'
#' Used when helper code needs to continue inside an already-created span.
#'
#' @param span Existing span to activate.
#' @param code Unevaluated code block to run.
#' @return The evaluated result of `code`.
#' @keywords internal
#' @noRd
otel_with_active_span <- function(span, code) {
  code <- substitute(code)
  if (!otel_tracing_enabled() || is.null(span)) {
    return(eval(code, envir = parent.frame()))
  }

  tryCatch(
    otel::local_active_span(
      span,
      end_on_exit = FALSE,
      activation_scope = environment()
    ),
    error = function(e) {
      otel_telemetry_warning("span activation", e)
    }
  )

  eval(code, envir = parent.frame())
}

#' Capture OTEL propagation headers
#'
#' Used before async work is dispatched to a worker.
#'
#' @param span Optional explicit span whose context should be serialized.
#' @return Header list for OTEL propagation, or `NULL` when no valid context is
#'   available.
#' @keywords internal
#' @noRd
otel_capture_context <- function(span = NULL) {
  if (!otel_tracing_enabled()) {
    return(NULL)
  }

  headers <- tryCatch(
    {
      if (!is.null(span)) {
        span$get_context()$to_http_headers()
      } else {
        otel::pack_http_context()
      }
    },
    error = function(...) NULL
  )
  if (is.null(headers) || !length(headers)) {
    return(NULL)
  }

  traceparent <- unname(headers[["traceparent"]] %||% NA_character_)
  if (
    isTRUE(
      identical(
        traceparent,
        "00-00000000000000000000000000000000-0000000000000000-00"
      )
    )
  ) {
    return(NULL)
  }

  headers
}

# 6 Async context handoff ------------------------------------------------------

## 6.1 Parent context propagation ----------------------------------------------

#' Rebuild an OTEL parent context from headers
#'
#' Used by async worker setup.
#'
#' @param otel_headers Header list or character value containing propagated OTEL
#'   context.
#' @return OTEL context object, or `NULL` when extraction fails.
#' @keywords internal
#' @noRd
otel_span_context_from_headers <- function(otel_headers) {
  if (is.null(otel_headers) || !length(otel_headers)) {
    return(NULL)
  }

  if (is.character(otel_headers)) {
    if (
      length(otel_headers) == 1L &&
        is_valid_string(as.character(otel_headers)[[1]])
    ) {
      header_name <- (names(otel_headers) %||% "traceparent")[[1]]
      otel_headers <- stats::setNames(
        list(as.character(otel_headers)[[1]]),
        header_name
      )
    } else {
      otel_headers <- as.list(otel_headers)
    }
  }

  parent_ctx <- tryCatch(
    otel::extract_http_context(otel_headers),
    error = function(...) NULL
  )
  if (is.null(parent_ctx)) {
    return(NULL)
  }

  if (!isTRUE(tryCatch(parent_ctx$is_valid(), error = function(...) FALSE))) {
    return(NULL)
  }

  parent_ctx
}

#' Start an async parent span
#'
#' Used by async login and module code before work is handed off to a worker.
#'
#' @param name Span name.
#' @param attributes Optional named attribute list.
#' @param parent Optional explicit parent context passed to `otel::start_span()`.
#' @return A list with `span` and `headers` elements.
#' @keywords internal
#' @noRd
otel_start_async_parent <- function(
  name,
  attributes = NULL,
  parent = NA
) {
  if (!otel_tracing_enabled()) {
    return(list(span = NULL, headers = NULL))
  }

  span <- tryCatch(
    {
      otel::start_span(
        name = name,
        attributes = otel_attributes(otel_with_trace_attribute(attributes)),
        options = list(parent = parent)
      )
    },
    error = function(e) {
      otel_telemetry_warning("async parent span", e)
      NULL
    }
  )

  list(
    span = span,
    headers = if (is.null(span)) {
      NULL
    } else {
      otel_capture_context(span)
    }
  )
}

#' Restore an async parent context in a worker
#'
#' Used by worker-side async code.
#'
#' @param otel_headers Propagated header bundle.
#' @param name Child span name.
#' @param attributes Optional named attribute list.
#' @param shiny_session Optional fresh session context.
#' @return Started span object, or `NULL` when a child span cannot be created.
#' @keywords internal
#' @noRd
otel_restore_parent_in_worker <- function(
  otel_headers,
  name,
  attributes = NULL,
  shiny_session = NULL
) {
  if (!otel_tracing_enabled()) {
    return(NULL)
  }

  if (is.null(otel_headers) || !length(otel_headers)) {
    return(NULL)
  }

  parent_ctx <- otel_span_context_from_headers(otel_headers)
  if (is.null(parent_ctx)) {
    return(NULL)
  }

  attributes <- otel_replace_shiny_attributes(
    attributes = attributes,
    shiny_session = shiny_session
  )

  span <- tryCatch(
    {
      otel::start_span(
        name = name,
        attributes = otel_attributes(otel_with_trace_attribute(attributes)),
        options = list(parent = parent_ctx)
      )
    },
    error = function(e) {
      otel_telemetry_warning("worker span", e)
      NULL
    }
  )

  span
}

#' End an async parent span
#'
#' Used when async work returns to the caller.
#'
#' @param parent Parent-span bundle returned by `otel_start_async_parent()`.
#' @param status Outcome status to record.
#' @param error Optional condition to record for error outcomes.
#' @return Invisibly returns `NULL`.
#' @keywords internal
#' @noRd
otel_end_async_parent <- function(
  parent,
  status = c("ok", "error"),
  error = NULL
) {
  if (is.null(parent) || is.null(parent$span)) {
    return(invisible(NULL))
  }

  status <- match.arg(status)
  if (identical(status, "ok")) {
    otel_mark_span_ok(parent$span)
  } else {
    otel_note_error(error, span = parent$span)
  }

  try(otel::end_span(parent$span), silent = TRUE)
  invisible(NULL)
}

# 7 Event logging --------------------------------------------------------------

## 7.1 Audit and log shaping ---------------------------------------------------

#' Choose a log severity for an event
#'
#' Used by OTEL log emission helpers.
#'
#' @param type Event type key.
#' @param status Optional event status.
#' @param reason Optional event reason.
#' @return Severity string such as `"info"`, `"warn"`, or `"error"`.
#' @keywords internal
#' @noRd
otel_event_severity <- function(type, status = NULL, reason = NULL) {
  if (!is_valid_string(type)) {
    return("info")
  }

  status <- otel_scalar_attribute(status)
  reason <- otel_scalar_attribute(reason)
  if (identical(type, "audit_userinfo")) {
    return(if (identical(status, "ok")) "info" else "error")
  }

  if (identical(type, "audit_token_revocation")) {
    if (is_valid_string(status) && grepl("^http_", status)) {
      return("warn")
    }
    return("info")
  }

  if (identical(type, "audit_token_introspection")) {
    if (
      identical(status, "ok") ||
        identical(status, "introspection_unsupported") ||
        identical(status, "missing_token")
    ) {
      return("info")
    }
    if (is_valid_string(status)) {
      return("warn")
    }
  }

  if (identical(type, "audit_session_cleared")) {
    if (reason %in% c("refresh_failed_async", "refresh_failed_sync")) {
      return("error")
    }
    return("info")
  }

  if (
    type %in%
      c(
        "audit_callback_validation_failed",
        "audit_invalid_browser_token",
        "audit_browser_cookie_error",
        "audit_callback_iss_missing",
        "audit_callback_iss_mismatch",
        "audit_callback_query_rejected",
        "audit_refresh_failed_but_kept_session",
        "audit_state_parse_failure",
        "audit_state_store_lookup_failed",
        "audit_state_store_removal_failed",
        "audit_error_state_consumption_failed"
      )
  ) {
    return("warn")
  }

  if (
    type %in%
      c(
        "error",
        "http_error",
        "transport_error",
        "audit_token_exchange_error",
        "audit_login_failed"
      )
  ) {
    return("error")
  }

  # Catch-all: treat any unrecognised type containing "_error" or "_failed"
  # as a warning so that new failure events are never silently logged at info.
  if (grepl("_error$|_failed$", type)) {
    return("warn")
  }

  "info"
}

#' Translate an event field name to an OTEL key
#'
#' Used when OTEL log records are built.
#'
#' @param name Event field name.
#' @return Mapped OTEL attribute key, the original name when no mapping is
#'   needed, or `NULL` for invalid input.
#' @keywords internal
#' @noRd
otel_translate_event_key <- function(name) {
  if (!is_valid_string(name)) {
    return(NULL)
  }

  switch(
    name,
    provider = "oauth.provider.name",
    client_provider = "oauth.provider.name",
    issuer = "oauth.provider.issuer",
    client_issuer = "oauth.provider.issuer",
    client_id_digest = "oauth.client_id_digest",
    module_id = "shiny.module_id",
    phase = "oauth.phase",
    trace_id = "shinyoauth.trace_id",
    type = "event.type",
    status = "oauth.status",
    name
  )
}

#' Detect sensitive OTEL event field names
#'
#' Used to keep secrets and request artifacts out of OTEL log attributes.
#'
#' @param name Event field name.
#' @return `TRUE` when the field name should be filtered; otherwise `FALSE`.
#' @keywords internal
#' @noRd
otel_is_sensitive_event_field <- function(name) {
  if (!is_valid_string(name)) {
    return(FALSE)
  }

  normalized_name <- tolower(gsub("[^A-Za-z0-9]+", "_", trimws(name)))

  normalized_name %in%
    c(
      "access_token",
      "refresh_token",
      "id_token",
      "code",
      "state",
      "browser_token"
    ) ||
    grepl("(^|_)client_secret$", normalized_name) ||
    grepl("(^|_)client_assertion$", normalized_name) ||
    grepl("(^|_)code_verifier$", normalized_name) ||
    grepl("(^|_)nonce$", normalized_name) ||
    grepl("(^|_)dpop_proof$", normalized_name) ||
    grepl("(^|_)request_uri$", normalized_name) ||
    grepl("(^|_)request$", normalized_name)
}

#' Build OTEL-safe event attributes
#'
#' Used by OTEL log emission helpers.
#'
#' @param event Audit or trace event list.
#' @return Named list of OTEL-safe log attributes, or `NULL` for invalid or
#'   empty input.
#' @keywords internal
#' @noRd
otel_event_attributes <- function(event) {
  if (!is.list(event) || !length(event)) {
    return(NULL)
  }

  attrs <- list()
  for (nm in names(event)) {
    if (!is_valid_string(nm) || nm %in% c("timestamp", "shiny_session")) {
      next
    }
    if (otel_is_sensitive_event_field(nm)) {
      next
    }
    if (is.list(event[[nm]])) {
      next
    }
    key <- otel_translate_event_key(nm)
    if (!is_valid_string(key)) {
      next
    }
    value <- otel_scalar_attribute(event[[nm]])
    if (!is.null(value)) {
      attrs[[key]] <- value
    }
  }

  c(attrs, otel_shiny_attributes(event$shiny_session %||% NULL))
}

#' Emit an OTEL log record
#'
#' Used by audit hooks and telemetry emitters.
#'
#' @param event Audit or trace event list.
#' @return Invisibly returns `NULL`.
#' @keywords internal
#' @noRd
otel_emit_log <- function(event) {
  if (!otel_logging_enabled()) {
    return(invisible(NULL))
  }

  if (!is.list(event) || !length(event)) {
    return(invisible(NULL))
  }

  severity <- otel_event_severity(
    event$type %||% NULL,
    status = event$status %||% NULL,
    reason = event$reason %||% NULL
  )
  msg <- otel_scalar_attribute(event$message %||% NULL) %||%
    otel_scalar_attribute(event$type %||% NULL) %||%
    "shinyOAuth"
  otel::log(
    msg = msg,
    severity = severity,
    attributes = otel_attributes(otel_event_attributes(event))
  )

  invisible(NULL)
}

Try the shinyOAuth package in your browser

Any scripts or data that you put into this service are public.

shinyOAuth documentation built on May 23, 2026, 9:06 a.m.