feat: add broken link api support (#76)

Author: adamfweidman

package-lock.json

@@ -103,10 +103,151 @@ message GenericResultV1 {
   GenericError generic_error = 2;
 }
 
+// A status to accept. Either a status code class like "2xx", or an
+// integer status code like "200".
+message ResponseStatusCode {
+  // An HTTP status code class.
+  enum StatusClass {
+    // Default value that matches no status codes.
+    STATUS_CLASS_UNSPECIFIED = 0;
+    // The class of status codes between 100 and 199.
+    STATUS_CLASS_1XX = 100;
+    // The class of status codes between 200 and 299.
+    STATUS_CLASS_2XX = 200;
+    // The class of status codes between 300 and 399.
+    STATUS_CLASS_3XX = 300;
+    // The class of status codes between 400 and 499.
+    STATUS_CLASS_4XX = 400;
+    // The class of status codes between 500 and 599.
+    STATUS_CLASS_5XX = 500;
+    // The class of all status codes.
+    STATUS_CLASS_ANY = 1000;
+  }
+  // Either a specific value or a class of status codes.
+  oneof status_code {
+    // A status code to accept.
+    int32 status_value = 1;
+    // A class of status codes to accept.
+    StatusClass status_class = 2;
+  }
+}
+
+// Aggregate and individual results of a Broken Link Synthetic execution
+message BrokenLinksResultV1 {
+  // the total number of links checked as part of the execution
+  optional int64 link_count = 1;
+  // the total number of links that passed as part of the execution
+  optional int64 passing_link_count = 2;
+  // the total number of links that failed
+  optional int64 failing_link_count = 3;
+  // the total number of links that count not be reached
+  optional int64 unreachable_count = 4;
+  // the total number of links that returned 2xx status codes
+  optional int64 status2xx_count = 5;
+  // the total number of links that returned 3xx status codes
+  optional int64 status3xx_count = 6;
+  // the total number of links that returned 4xx status codes
+  optional int64 status4xx_count = 7;
+  // the total number of links that returned 5xx status codes
+  optional int64 status5xx_count = 8;
+
+  message BrokenLinkCheckerOptions {
+    // Origin uri from which to scrape all other links, this is the only
+    // required field.
+    string origin_uri = 1;
+    // Number of links to follow, default 50.
+    optional int64 link_limit = 2;
+    // HTML elements to scrape from origin_uri, default 'a'.
+    string query_selector_all = 3;
+    // Attributes to scrape from queried HTML elements, default ['href'].
+    repeated string get_attributes = 4;
+
+    // Possible orders for checking links that have been scraped.
+    enum LinkOrder {
+      // Default value that indicates no order.
+      LINK_ORDER_UNSPECIFIED = 0;
+      // First "n" number of links scraped.
+      FIRST_N = 1;
+      // Random selection of links scraped.
+      RANDOM = 2;
+    }
+
+    // order to check links scraped
+    LinkOrder link_order = 5;  // default FIRST_N
+    // Maximum amount of time to wait for HTTP response to complete per link,
+    // default 30000 milliseconds.
+    optional int64 link_timeout_millis = 6;
+    // Maximum number of times to retry a link that does not return the
+    // “expected_status_code”.
+    optional int64 max_retries = 7;
+
+    reserved 8;
+    reserved "max_redirects";
+
+    // HTML element to wait for before scraping links on origin_uri.
+    // Method documentation:
+    // https://pptr.dev/api/puppeteer.page.waitforselector. Type documentation:
+    // https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors
+    string wait_for_selector = 9;
+
+    // Individual link options.
+    message PerLinkOption {
+      // The expected status code or class.
+      ResponseStatusCode expected_status_code = 1;
+      // Maximum amount of time to wait for HTTP response to complete, for
+      // the given specified link passed in "per_link_options" map.
+      optional int64 link_timeout_millis = 2;
+    }
+    // individual link options, default None. string must be formatted as a
+    // fully qualified url
+    map<string, PerLinkOption> per_link_options = 10;
+  }
+
+  // Options set for broken link synthetic.
+  BrokenLinkCheckerOptions options = 9;
+
+  // Result of a single link checked / network request
+  message SyntheticLinkResult {
+    // Whether or not the status code is the same as "expected_status_code".
+    optional bool link_passed = 1;
+    // The expected status code or status class.
+    ResponseStatusCode expected_status_code = 2;
+    // Source_uri from which the target_uri is navigated from.
+    string source_uri = 3;
+    // target_uri navigated to from the source_uri.
+    string target_uri = 4;
+    // Anchor text on the source URI.
+    string anchor_text = 5;
+    // HTML element from which target_uri was scraped.
+    string html_element = 6;
+    // Status code returned by the target_uri.
+    optional int64 status_code = 7;
+    // 'BrokenLinksSynthetic_IncorrectStatusCode' if the expected and actual
+    // status codes differ. Otherwise, the class of the error thrown, eg
+    // 'connectionaborted', docs: https://pptr.dev/api/puppeteer.errorcode.
+    string error_type = 8;
+    // Error Message, if any
+    string error_message = 9;
+    // The start time of the link navigation in iso format.
+    string link_start_time = 10;
+    // The end time of the link navigation in iso format.
+    string link_end_time = 11;
+
+    // These fields only apply to the origin link.
+    optional bool is_origin = 12;
+  }
+
+  // link result for origin_uri
+  SyntheticLinkResult origin_link_result = 10;
+  // link results for all scraped and followed links
+  repeated SyntheticLinkResult followed_link_results = 11;
+}
+
 message SyntheticResult {
   oneof result {
     TestFrameworkResultV1 synthetic_test_framework_result_v1 = 1;
     GenericResultV1 synthetic_generic_result_v1 = 2;
+    BrokenLinksResultV1 synthetic_broken_links_result_v1 = 3;
   }
 
   // Used to determine information about the runtime environment that the