src/net/instaweb/rewriter/critical_keys.proto

/*
 * Copyright 2013 Google Inc.
 *
 * 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.
 */

// Author: morlovich@google.com (Maksim Orlovich)

syntax = "proto2";

option optimize_for = LITE_RUNTIME;

package net_instaweb;

// This proto is used by classes such as CriticalImageFinder and
// CriticalSelectorFinder that aggregate beacon responses consisting of string
// keys. Each key (CSS selector or critical image URL depending on the class) is
// assigned a support value, which is decayed exponentially, allowing old keys
// to expire. This proto also has some legacy fields for a previous
// implementation that stored a history of beacon responses.
//
// Next free id: 10
message CriticalKeys {
  // The KeyEvidence proto aggregates multiple beacons returns in a scalable
  // way; support is exponentially decayed over time.
  message KeyEvidence {
    optional bytes key = 1;
    optional int32 support = 2;
  }

  // The PendingNonce proto describes the nonce of a beacon request that is
  // still valid (no response received, not timed out).  Note that these entries
  // might be cleared but left in place within the containing CriticalKeys when
  // they expire or the corresponding beacon result arrives.
  message PendingNonce {
    optional int64 timestamp_ms = 1;
    optional string nonce = 2;
  }

  // Ids 1-3 deleted, should not be reused.

  optional int64 next_beacon_timestamp_ms = 4;

  // This represents a serialized key/value map mapping keys to support for
  // their criticality. Support is added by beacon results, but decays
  // exponentially over time.
  repeated KeyEvidence key_evidence = 5;

  // This represents the valid beacon nonce values that will be accepted.
  repeated PendingNonce pending_nonce = 6;

  // This represents the maximum support value possible based on the number of
  // beacons that have been encountered so far.  This is used to determine
  // proportional support (for example, if we expect 80% of beacons to attest
  // that an image is critical, then support must be >=80% of this value).  If
  // we preserve k beacon results, this value will be k after the first beacon
  // result arrives, and will converge to k^2 over time.  The default value
  // ensures that support = 0 will be considered unsupported.
  optional int32 maximum_possible_support = 7 [default = 1];

  // Keep track of the number of valid beacons received. This can be used to
  // track how frequently beaconing needs to happen. When the number of beacons
  // received is low, use that as a signal to beacon more frequently. This
  // should also be reset when a new set of candidate keys is received to
  // retrigger beaconing.
  optional int64 valid_beacons_received = 8;

  // Count how many nonces have expired since the last valid beacon was
  // received. This can be used to disable or rate limit beaconing if it seems
  // that beacons are not being received by the server due to a
  // misconfiguration.
  optional int64 nonces_recently_expired = 9;
}