wowlab_analytics/analytics/

decode.rs

use prost::Message;
use wowlab_types::{
    constants::{HUNDRED, MS_PER_SECOND, PROTO_DPS_SCALE},
    numeric::u64_to_f64,
    proto,
};

use super::{
    convert::{
        convert_actions, convert_auras, convert_cooldowns, convert_damage_profile,
        convert_dictionary, convert_execution, convert_resources, convert_timeline, decode_hdr,
        histogram_view_from_hdr, pct, percentiles_from_hdr,
    },
    tournament::{
        JobResultView, TournamentStatsView, TournamentView, convert_permutation_summaries,
        convert_slot_rankings,
    },
    views::{AnalyticsView, CoreView, DistributionView, HistogramView, PercentilesView},
};

const X10000_SCALE: f64 = 10000.0;
const Z_SCORE_95: f64 = 1.96;

/// Failure to decode or validate an analytics protobuf payload.
#[derive(Debug, thiserror::Error)]
#[error("{kind}")]
pub struct AnalyticsDecodeError {
    #[source]
    kind: AnalyticsDecodeErrorKind,
}

#[derive(Debug, thiserror::Error)]
enum AnalyticsDecodeErrorKind {
    #[error("decode ResultViewV1: {0}")]
    ResultView(#[source] prost::DecodeError),
    #[error("decode TimelineViewV1: {0}")]
    TimelineView(#[source] prost::DecodeError),
    #[error("decode ChunkTelemetry: {0}")]
    ChunkTelemetry(#[source] prost::DecodeError),
    #[error("ResultViewV1 missing core")]
    MissingResultCore,
}

/// Protobuf or validation stage that rejected an analytics payload.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum AnalyticsDecodeStage {
    ResultView,
    TimelineView,
    ChunkTelemetry,
    ResultCore,
}

impl AnalyticsDecodeError {
    const fn result_view(source: prost::DecodeError) -> Self {
        Self {
            kind: AnalyticsDecodeErrorKind::ResultView(source),
        }
    }

    const fn timeline_view(source: prost::DecodeError) -> Self {
        Self {
            kind: AnalyticsDecodeErrorKind::TimelineView(source),
        }
    }

    const fn chunk_telemetry(source: prost::DecodeError) -> Self {
        Self {
            kind: AnalyticsDecodeErrorKind::ChunkTelemetry(source),
        }
    }

    const fn missing_result_core() -> Self {
        Self {
            kind: AnalyticsDecodeErrorKind::MissingResultCore,
        }
    }

    /// Return the stage that rejected the payload.
    #[must_use]
    pub const fn stage(&self) -> AnalyticsDecodeStage {
        match self.kind {
            AnalyticsDecodeErrorKind::ResultView(_) => AnalyticsDecodeStage::ResultView,
            AnalyticsDecodeErrorKind::TimelineView(_) => AnalyticsDecodeStage::TimelineView,
            AnalyticsDecodeErrorKind::ChunkTelemetry(_) => AnalyticsDecodeStage::ChunkTelemetry,
            AnalyticsDecodeErrorKind::MissingResultCore => AnalyticsDecodeStage::ResultCore,
        }
    }

    /// Return whether the decoded result omitted its required core section.
    #[must_use]
    pub const fn is_missing_result_core(&self) -> bool {
        matches!(self.kind, AnalyticsDecodeErrorKind::MissingResultCore)
    }
}

fn decode_protobuf<M>(
    bytes: &[u8],
    context: fn(prost::DecodeError) -> AnalyticsDecodeError,
) -> Result<M, AnalyticsDecodeError>
where
    M: Message + Default,
{
    match M::decode(bytes) {
        Ok(message) => Ok(message),
        Err(source) => Err(context(source)),
    }
}

/// Decode `ResultViewV1` and `TimelineViewV1` protobuf bytes into a chart-ready [`AnalyticsView`].
///
/// # Errors
///
/// Returns an error when either protobuf payload is invalid or the result has no core section.
pub fn decode_and_derive(
    result_bytes: &[u8],
    timeline_bytes: &[u8],
) -> Result<AnalyticsView, AnalyticsDecodeError> {
    let result_view: proto::ResultViewV1 =
        decode_protobuf(result_bytes, AnalyticsDecodeError::result_view)?;

    let timeline_view: proto::TimelineViewV1 =
        decode_protobuf(timeline_bytes, AnalyticsDecodeError::timeline_view)?;

    let Some(core_pb) = result_view.core else {
        return Err(AnalyticsDecodeError::missing_result_core());
    };

    let total_fight_time_ms = core_pb.total_fight_time_ms;
    let fight_time_s = u64_to_f64(total_fight_time_ms) / MS_PER_SECOND;

    let core = CoreView {
        iterations: core_pb.iterations,
        chunks_completed: core_pb.chunks_completed,
        chunks_total: core_pb.chunks_total,
        total_fight_time_ms,
        mean_dps: f64::from(core_pb.mean_dps_x10) / PROTO_DPS_SCALE,
        min_dps: f64::from(core_pb.min_dps_x10) / PROTO_DPS_SCALE,
        max_dps: f64::from(core_pb.max_dps_x10) / PROTO_DPS_SCALE,
        std_dps: f64::from(core_pb.std_dps_x10) / PROTO_DPS_SCALE,
        ci95_half_pct: f64::from(core_pb.ci95_half_pct_x10000) / X10000_SCALE,
    };

    let distribution = result_view.distribution.map(|dist| {
        let histogram = dist.histogram.as_ref().and_then(histogram_view_from_hdr);

        let percentiles = dist.percentiles.map(|p| PercentilesView {
            p01: f64::from(p.p01_x10) / PROTO_DPS_SCALE,
            p05: f64::from(p.p05_x10) / PROTO_DPS_SCALE,
            p10: f64::from(p.p10_x10) / PROTO_DPS_SCALE,
            p25: f64::from(p.p25_x10) / PROTO_DPS_SCALE,
            p50: f64::from(p.p50_x10) / PROTO_DPS_SCALE,
            p75: f64::from(p.p75_x10) / PROTO_DPS_SCALE,
            p90: f64::from(p.p90_x10) / PROTO_DPS_SCALE,
            p95: f64::from(p.p95_x10) / PROTO_DPS_SCALE,
            p99: f64::from(p.p99_x10) / PROTO_DPS_SCALE,
        });

        DistributionView {
            sample_count: dist.sample_count,
            histogram: histogram.unwrap_or_else(|| HistogramView {
                bin_count: 0,
                min_dps: 0.0,
                max_dps: 0.0,
                counts: vec![],
                underflow: 0,
                overflow: 0,
            }),
            percentiles: percentiles.unwrap_or(PercentilesView {
                p01: 0.0,
                p05: 0.0,
                p10: 0.0,
                p25: 0.0,
                p50: 0.0,
                p75: 0.0,
                p90: 0.0,
                p95: 0.0,
                p99: 0.0,
            }),
        }
    });

    let action_rows = result_view.actions.map(|a| a.rows).unwrap_or_default();
    let actions = convert_actions(&action_rows, fight_time_s);

    let aura_rows = result_view.auras.map(|a| a.rows).unwrap_or_default();
    let auras = convert_auras(&aura_rows, total_fight_time_ms);

    let resource_rows = result_view.resources.map(|r| r.rows).unwrap_or_default();
    let resources = convert_resources(&resource_rows, total_fight_time_ms);

    let cooldown_rows = result_view.cooldowns.map(|c| c.rows).unwrap_or_default();
    let cooldowns = convert_cooldowns(&cooldown_rows);

    let execution = result_view.execution.as_ref().map(convert_execution);

    let damage_profile = result_view
        .damage_profile
        .as_ref()
        .map(convert_damage_profile);

    let timeline = convert_timeline(timeline_view);

    let dictionary = result_view
        .dictionary
        .map(convert_dictionary)
        .unwrap_or_default();

    Ok(AnalyticsView {
        core,
        distribution,
        actions,
        auras,
        resources,
        cooldowns,
        execution,
        damage_profile,
        timeline,
        dictionary,
    })
}

fn analytics_from_result_view(
    result_view: &proto::ResultViewV1,
    timeline_view: &proto::TimelineViewV1,
) -> Result<AnalyticsView, AnalyticsDecodeError> {
    let result_bytes = result_view.encode_to_vec();
    let timeline_bytes = timeline_view.encode_to_vec();

    decode_and_derive(&result_bytes, &timeline_bytes)
}

/// Decode the `JobResult` + `JobTimeline` envelope, falling back to [`decode_and_derive`] when the oneof is unset.
///
/// # Errors
///
/// Returns an error when the envelope or its embedded analytics payload cannot be decoded.
pub fn decode_job_result(
    result_bytes: &[u8],
    timeline_bytes: &[u8],
) -> Result<JobResultView, AnalyticsDecodeError> {
    let envelope = proto::JobResult::decode(result_bytes).ok();
    let timeline_envelope = proto::JobTimeline::decode(timeline_bytes).ok();

    let oneof = envelope.as_ref().and_then(|e| e.result.as_ref());
    let Some(oneof) = oneof else {
        let analytics = decode_and_derive(result_bytes, timeline_bytes)?;

        return Ok(JobResultView::Single { analytics });
    };

    match oneof {
        proto::job_result::Result::Single(single) => {
            let result_view = single.result.clone().unwrap_or_default();
            let timeline_view = match timeline_envelope.and_then(|t| t.timeline) {
                Some(proto::job_timeline::Timeline::Single(st)) => st.timeline.unwrap_or_default(),
                Some(proto::job_timeline::Timeline::Tournament(tt)) => {
                    tt.winner_timeline.unwrap_or_default()
                }
                None => proto::TimelineViewV1::default(),
            };
            let analytics = analytics_from_result_view(&result_view, &timeline_view)?;

            Ok(JobResultView::Single { analytics })
        }
        proto::job_result::Result::Tournament(tournament) => {
            let winner_timeline = match timeline_envelope.and_then(|t| t.timeline) {
                Some(proto::job_timeline::Timeline::Tournament(tt)) => tt.winner_timeline,
                Some(proto::job_timeline::Timeline::Single(st)) => st.timeline,
                None => None,
            };
            let winner_analytics = match tournament.winner_result.as_ref() {
                Some(result_view) => {
                    let tl = winner_timeline.unwrap_or_default();

                    Some(analytics_from_result_view(result_view, &tl)?)
                }
                None => None,
            };

            let stats_pb = tournament.stats.unwrap_or_default();
            let winner_dps = f64::from(stats_pb.winner_dps_x10) / PROTO_DPS_SCALE;
            let baseline_dps = f64::from(stats_pb.baseline_dps_x10) / PROTO_DPS_SCALE;
            let dps_gain = f64::from(stats_pb.dps_gain_x10) / PROTO_DPS_SCALE;
            let dps_gain_pct = pct(dps_gain, baseline_dps);

            let stats = TournamentStatsView {
                winner_dps,
                baseline_dps,
                dps_gain,
                dps_gain_pct,
                total_permutations: stats_pb.total_permutations,
                total_iterations: stats_pb.total_iterations,
                phases_completed: stats_pb.phases_completed,
            };

            let top_permutations = convert_permutation_summaries(
                &tournament.top_permutations,
                stats_pb.winner_dps_x10,
            );
            let slot_rankings = convert_slot_rankings(&tournament.slot_rankings);

            Ok(JobResultView::Tournament {
                analytics: winner_analytics,
                tournament: TournamentView {
                    stats,
                    top_permutations,
                    slot_rankings,
                },
            })
        }
    }
}

/// Decode a single `ChunkTelemetry` blob into an [`AnalyticsView`] (timeline always `None`).
///
/// # Errors
///
/// Returns an error when `chunk_bytes` is not a valid `ChunkTelemetry` protobuf payload.
pub fn decode_chunk_telemetry(chunk_bytes: &[u8]) -> Result<AnalyticsView, AnalyticsDecodeError> {
    let chunk: proto::ChunkTelemetry =
        decode_protobuf(chunk_bytes, AnalyticsDecodeError::chunk_telemetry)?;

    let total_fight_time_ms = chunk.total_fight_time_ms;
    let fight_time_s = u64_to_f64(total_fight_time_ms) / MS_PER_SECOND;
    let iterations = u64::from(chunk.iterations);

    let m2 = f64::from_bits(chunk.m2_dps_bits);
    let std_dps_x10 = if iterations > 1 {
        let var_sample = m2 / (u64_to_f64(iterations) - 1.0);

        var_sample.sqrt()
    } else {
        0.0
    };

    let mean_dps = f64::from(chunk.mean_dps_x10) / PROTO_DPS_SCALE;
    let ci95_half_pct = if iterations > 1 && mean_dps > 0.0 {
        let se = std_dps_x10 / (u64_to_f64(iterations)).sqrt();

        Z_SCORE_95 * se / f64::from(chunk.mean_dps_x10) * HUNDRED
    } else {
        0.0
    };

    let core = CoreView {
        iterations,
        chunks_completed: 1,
        chunks_total: 1,
        total_fight_time_ms,
        mean_dps,
        min_dps: f64::from(chunk.min_dps_x10) / PROTO_DPS_SCALE,
        max_dps: f64::from(chunk.max_dps_x10) / PROTO_DPS_SCALE,
        std_dps: std_dps_x10 / PROTO_DPS_SCALE,
        ci95_half_pct,
    };

    let distribution = chunk.histogram.as_ref().and_then(|hist| {
        let hdr = decode_hdr(hist)?;

        if hdr.is_empty() {
            return None;
        }

        let histogram_view = histogram_view_from_hdr(hist)?;
        let percentiles = percentiles_from_hdr(&hdr);

        Some(DistributionView {
            sample_count: hdr.len(),
            histogram: histogram_view,
            percentiles,
        })
    });

    let actions = convert_actions(&chunk.actions, fight_time_s);
    let auras = convert_auras(&chunk.auras, total_fight_time_ms);
    let resources = convert_resources(&chunk.resources, total_fight_time_ms);
    let cooldowns = convert_cooldowns(&chunk.cooldowns);
    let execution = chunk.execution.as_ref().map(convert_execution);
    let damage_profile = chunk.damage_profile.as_ref().map(convert_damage_profile);
    let dictionary = chunk.dictionary.map(convert_dictionary).unwrap_or_default();

    Ok(AnalyticsView {
        core,
        distribution,
        actions,
        auras,
        resources,
        cooldowns,
        execution,
        damage_profile,
        timeline: None,
        dictionary,
    })
}