diff --git a/.azure-pipelines/pipelines.yml b/.azure-pipelines/pipelines.yml index ab2a2b1f0f61a..02b31478f4ced 100644 --- a/.azure-pipelines/pipelines.yml +++ b/.azure-pipelines/pipelines.yml @@ -160,6 +160,24 @@ jobs: artifactName: docker condition: always() + - job: examples + dependsOn: ["docker"] + displayName: "Verify examples run as documented" + pool: + vmImage: "ubuntu-18.04" + steps: + - task: DownloadBuildArtifacts@0 + inputs: + buildType: current + artifactName: "docker" + itemPattern: "docker/envoy-docker-images.tar.xz" + downloadType: single + targetPath: $(Build.StagingDirectory) + - bash: ./ci/do_ci.sh verify_examples + env: + ENVOY_DOCKER_BUILD_DIR: $(Build.StagingDirectory) + NO_BUILD_SETUP: 1 + - job: macOS dependsOn: ["format"] timeoutInMinutes: 360 diff --git a/.bazelrc b/.bazelrc index b3ad31c0f60cf..d3326e1de0066 100644 --- a/.bazelrc +++ b/.bazelrc @@ -129,6 +129,7 @@ build:coverage --action_env=GCOV=llvm-profdata build:coverage --copt=-DNDEBUG # 1.5x original timeout + 300s for trace merger in all categories build:coverage --test_timeout=390,750,1500,5700 +build:coverage --define=dynamic_link_tests=true build:coverage --define=ENVOY_CONFIG_COVERAGE=1 build:coverage --cxxopt="-DENVOY_CONFIG_COVERAGE=1" build:coverage --coverage_support=@envoy//bazel/coverage:coverage_support diff --git a/DEPENDENCY_POLICY.md b/DEPENDENCY_POLICY.md new file mode 100644 index 0000000000000..50aad88708aaf --- /dev/null +++ b/DEPENDENCY_POLICY.md @@ -0,0 +1,103 @@ +# Envoy External Dependency Policy + +Envoy has an evolving policy on external dependencies, tracked at +https://github.com/envoyproxy/envoy/issues/10471. This will become stricter over time, below we +detail the policy as it currently applies. + +## External dependencies dashboard + +The list of external dependencies in Envoy with their current version is available at +https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/external_deps + +## Declaring external dependencies + +In general, all external dependencies for the Envoy proxy binary build and test should be declared +in either [bazel/repository_locations.bzl](bazel/repository_locations.bzl) or +[api/bazel/repository_locations.bzl](api/bazel/repository_locations.bzl), unless listed under +[policy exceptions](#policy-exceptions). + +An example entry for the `nghttp2` dependency is: + +```python +com_github_nghttp2_nghttp2 = dict( + project_name = "Nghttp2", + project_url = "https://nghttp2.org", + version = "1.41.0", + sha256 = "eacc6f0f8543583ecd659faf0a3f906ed03826f1d4157b536b4b385fe47c5bb8", + strip_prefix = "nghttp2-{version}", + urls = ["https://github.com/nghttp2/nghttp2/releases/download/v{version}/nghttp2-{version}.tar.gz"], + use_category = ["dataplane"], + cpe = "cpe:2.3:a:nghttp2:nghttp2:*", +), +``` + +Dependency declarations must: + +* Provide a meaningful project name and URL. +* State the version in the `version` field. String interpolation should be used in `strip_prefix` + and `urls` to reference the version. If you need to reference version `X.Y.Z` as `X_Y_Z`, this + may appear in a string as `{underscore_version}`, similarly for `X-Y-Z` you can use + `{dash_version}`. +* Versions should prefer release versions over master branch GitHub SHA tarballs. A comment is + necessary if the latter is used. This comment should contain the reason that a non-release + version is being used and the YYYY-MM-DD when the last update was performed. +* Provide accurate entries for `use_category`. Please think carefully about whether there are data + or control plane implications of the dependency. +* CPEs are compulsory for all dependencies that are not purely build/test. + [CPEs](https://en.wikipedia.org/wiki/Common_Platform_Enumeration) provide metadata that allow us + to correlate with related CVEs in dashboards and other tooling, and also provide a machine + consumable join key. You can consult the latest [CPE + dictionary](https://nvd.nist.gov/products/cpe) to find a CPE for a dependency.`"N/A"` should only + be used if no CPE for the project is available in the CPE database. CPEs should be _versionless_ + with a `:*` suffix, since the version can be computed from `version`. + +When build or test code references Python modules, they should be imported via `pip3_import` in +[bazel/repositories_extra.bzl](bazel/repositories_extra.bzl). Python modules should not be listed in +`repository_locations.bzl` entries. `requirements.txt` files for Python dependencies must pin to +exact versions, e.g. `PyYAML==5.3.1` and ideally also include a [SHA256 +checksum](https://davidwalsh.name/hashin). + +Pure developer tooling and documentation builds may reference Python via standalone +`requirements.txt`, following the above policy. + +## New external dependencies + +* Any new dependency on the Envoy data or control plane that impacts Envoy core (i.e. is not + specific to a single non-core extension) must be cleared with the Envoy security team, please file + an issue and tag + [@envoyproxy/security-team](https://github.com/orgs/envoyproxy/teams/security-team). While policy + is still [evolving](robust_to_untrusted_downstream_and_upstream), criteria that will be used in + evaluation include: + * Does the project have release versions? How often do releases happen? + * Does the project have a security vulnerability disclosure process and contact details? + * Does the project have effective governance, e.g. multiple maintainers, a governance policy? + * Does the project have a code review culture? Are patches reviewed by independent maintainers + prior to merge? + * Does the project enable mandatory GitHub 2FA for contributors? + * Does the project have evidence of high test coverage, fuzzing, static analysis (e.g. CodeQL), + etc.? + +* Dependencies for extensions that are tagged as `robust_to_untrusted_downstream` or + `robust_to_untrusted_downstream_and_upstream` should be sensitive to the same set of concerns + as the core data plane. + +## Maintaining existing dependencies + +We rely on community volunteers to help track the latest versions of dependencies. On a best effort +basis: + +* Core Envoy dependencies will be updated by the Envoy maintainers/security team. + +* Extension [CODEOWNERS](CODEOWNERS) should update extension specific dependencies. + +Where possible, we prefer the latest release version for external dependencies, rather than master +branch GitHub SHA tarballs. + +## Policy exceptions + +The following dependencies are exempt from the policy: + +* Any developer-only facing tooling or the documentation build. + +* Transitive build time dependencies, e.g. Go projects vendored into + [protoc-gen-validate](https://github.com/envoyproxy/protoc-gen-validate). diff --git a/EXTENSION_POLICY.md b/EXTENSION_POLICY.md index d7f1df8334c5d..0063a2a2139c4 100644 --- a/EXTENSION_POLICY.md +++ b/EXTENSION_POLICY.md @@ -33,6 +33,8 @@ The following procedure will be used when proposing new extensions for inclusion 4. Any extension added via this process becomes a full part of the repository. This means that any API breaking changes in the core code will be automatically fixed as part of the normal PR process by other contributors. + 5. Any new dependencies added for this extension must comply with + [DEPENDENCY_POLICY.md](DEPENDENCY_POLICY.md), please follow the steps detailed there. ## Removing existing extensions @@ -56,3 +58,54 @@ may be a single individual, but it is always preferred to have multiple reviewer In the event that the Extension PR author is a sponsoring maintainer and no other sponsoring maintainer is available, another maintainer may be enlisted to perform a minimal review for style and common C++ anti-patterns. The Extension PR must still be approved by a non-maintainer reviewer. + +## Extension stability and security posture + +Every extension is expected to be tagged with a `status` and `security_posture` in its +`envoy_cc_extension` rule. + +The `status` is one of: +* `stable`: The extension is stable and is expected to be production usable. This is the default if + no `status` is specified. +* `alpha`: The extension is functional but has not had substantial production burn time, use only + with this caveat. +* `wip`: The extension is work-in-progress. Functionality is incomplete and it is not intended for + production use. + +The extension status may be adjusted by the extension [CODEOWNERS](./CODEOWNERS) and/or Envoy +maintainers based on an assessment of the above criteria. Note that the status of the extension +reflects the implementation status. It is orthogonal to the API stability, for example, an extension +with configuration `envoy.foo.v3alpha.Bar` might have a `stable` implementation and +`envoy.foo.v3.Baz` can have a `wip` implementation. + +The `security_posture` is one of: +* `robust_to_untrusted_downstream`: The extension is hardened against untrusted downstream traffic. It + assumes that the upstream is trusted. +* `robust_to_untrusted_downstream_and_upstream`: The extension is hardened against both untrusted + downstream and upstream traffic. +* `requires_trusted_downstream_and_upstream`: The extension is not hardened and should only be used in deployments + where both the downstream and upstream are trusted. +* `unknown`: This is functionally equivalent to `requires_trusted_downstream_and_upstream`, but acts + as a placeholder to allow us to identify extensions that need classifying. +* `data_plane_agnostic`: Not relevant to data plane threats, e.g. stats sinks. + +An assessment of a robust security posture for an extension is subject to the following guidelines: + +* Does the extension have fuzz coverage? If it's only receiving fuzzing + courtesy of the generic listener/network/HTTP filter fuzzers, does it have a + dedicated fuzzer for any parts of the code that would benefit? +* Does the extension have unbounded internal buffering? Does it participate in + flow control via watermarking as needed? +* Does the extension have at least one deployment with live untrusted traffic + for a period of time, N months? +* Does the extension rely on dependencies that meet our [extension maturity + model](https://github.com/envoyproxy/envoy/issues/10471)? +* Is the extension reasonable to audit by Envoy security team? +* Is the extension free of obvious scary things, e.g. `memcpy`, does it have gnarly parsing code, etc? +* Does the extension have active [CODEOWNERS](CODEOWNERS) who are willing to + vouch for the robustness of the extension? +* Is the extension absent a [low coverage + exception](https://github.com/envoyproxy/envoy/blob/master/test/per_file_coverage.sh#L5)? + +The current stability and security posture of all extensions can be seen +[here](https://www.envoyproxy.io/docs/envoy/latest/intro/arch_overview/security/threat_model#core-and-extensions). diff --git a/GOVERNANCE.md b/GOVERNANCE.md index ce60a6e82ca7e..923559eea7ad2 100644 --- a/GOVERNANCE.md +++ b/GOVERNANCE.md @@ -150,11 +150,47 @@ If a maintainer is no longer interested or cannot perform the maintainer duties should volunteer to be moved to emeritus status. In extreme cases this can also occur by a vote of the maintainers per the voting process below. +# xDS API shepherds + +The [xDS API shepherds](https://github.com/orgs/envoyproxy/teams/api-shepherds) are responsible for +approving any PR that modifies the [api/](api/) tree. They ensure that API [style](api/STYLE.md) and +[versioning](api/API_VERSIONING.md) policies are enforced and that a consistent approach is taken +towards API evolution. + +The xDS API shepherds are also the xDS API maintainers; they work collaboratively with the community +to drive the xDS API roadmap and review major proposed design changes. The API shepherds are +intended to be representative of xDS client and control plane developers who are actively working on +xDS development and evolution. + +As with maintainers, an API shepherd should be spending at least 25% of their time working on xDS +developments and expect to be active in this space in the near future. API shepherds are expected to +take on API shepherd review load and participate in meetings. They should be active on Slack `#xds` +and responsive to GitHub issues and PRs on which they are tagged. + +The API shepherds are distinct to the [UDPA working +group](https://github.com/cncf/udpa/blob/master/README.md), which aims to evolve xDS directionally +towards a universal dataplane API. API shepherds are responsible for the execution of the xDS +day-to-day and guiding xDS implementation changes. Proposals from UDPA-WG will be aligned with the +xDS API shepherds to ensure that xDS is heading towards the UDPA goal. xDS API shepherds operate +under the [envoyproxy](https://github.com/envoyproxy) organization but are expected to keep in mind +the needs of all xDS clients (currently Envoy and gRPC, but we are aware of other in-house +implementations) and the goals of UDPA-WG. + +If you wish to become an API shepherd and satisfy the above criteria, please contact an existing +API shepherd. We will factor in PR and review history to determine if the above API shepherd +requirements are met. We may ask you to shadow an existing API shepherd for a period of time to +build confidence in consistent application of the API guidelines to PRs. + # Extension addition policy Adding new [extensions](REPO_LAYOUT.md#sourceextensions-layout) has a dedicated policy. Please see [this](./EXTENSION_POLICY.md) document for more information. +# Exernal dependency policy + +Adding new external dependencies has a dedicated policy. Please see [this](DEPENDENCY_POLICY.md) +document for more information. + # Conflict resolution and voting In general, we prefer that technical issues and maintainer membership are amicably worked out diff --git a/api/envoy/admin/v3/init_dump.proto b/api/envoy/admin/v3/init_dump.proto new file mode 100644 index 0000000000000..3df9bfb51da68 --- /dev/null +++ b/api/envoy/admin/v3/init_dump.proto @@ -0,0 +1,32 @@ +syntax = "proto3"; + +package envoy.admin.v3; + +import "udpa/annotations/status.proto"; +import "udpa/annotations/versioning.proto"; + +option java_package = "io.envoyproxy.envoy.admin.v3"; +option java_outer_classname = "InitDumpProto"; +option java_multiple_files = true; +option (udpa.annotations.file_status).package_version_status = ACTIVE; + +// [#protodoc-title: InitDump] + +// Dumps of unready targets of envoy init managers. Envoy's admin fills this message with init managers, +// which provides the information of their unready targets. +// The :ref:`/init_dump ` will dump all unready targets information. +message UnreadyTargetsDumps { + // Message of unready targets information of an init manager. + message UnreadyTargetsDump { + // Name of the init manager. Example: "init_manager_xxx". + string name = 1; + + // Names of unready targets of the init manager. Example: "target_xxx". + repeated string target_names = 2; + } + + // You can choose specific component to dump unready targets with mask query parameter. + // See :ref:`/init_dump?mask={} ` for more information. + // The dumps of unready targets of all init managers. + repeated UnreadyTargetsDump unready_targets_dumps = 1; +} diff --git a/api/envoy/admin/v4alpha/init_dump.proto b/api/envoy/admin/v4alpha/init_dump.proto new file mode 100644 index 0000000000000..81c423e52024d --- /dev/null +++ b/api/envoy/admin/v4alpha/init_dump.proto @@ -0,0 +1,37 @@ +syntax = "proto3"; + +package envoy.admin.v4alpha; + +import "udpa/annotations/status.proto"; +import "udpa/annotations/versioning.proto"; + +option java_package = "io.envoyproxy.envoy.admin.v4alpha"; +option java_outer_classname = "InitDumpProto"; +option java_multiple_files = true; +option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSION_CANDIDATE; + +// [#protodoc-title: InitDump] + +// Dumps of unready targets of envoy init managers. Envoy's admin fills this message with init managers, +// which provides the information of their unready targets. +// The :ref:`/init_dump ` will dump all unready targets information. +message UnreadyTargetsDumps { + option (udpa.annotations.versioning).previous_message_type = "envoy.admin.v3.UnreadyTargetsDumps"; + + // Message of unready targets information of an init manager. + message UnreadyTargetsDump { + option (udpa.annotations.versioning).previous_message_type = + "envoy.admin.v3.UnreadyTargetsDumps.UnreadyTargetsDump"; + + // Name of the init manager. Example: "init_manager_xxx". + string name = 1; + + // Names of unready targets of the init manager. Example: "target_xxx". + repeated string target_names = 2; + } + + // You can choose specific component to dump unready targets with mask query parameter. + // See :ref:`/init_dump?mask={} ` for more information. + // The dumps of unready targets of all init managers. + repeated UnreadyTargetsDump unready_targets_dumps = 1; +} diff --git a/api/envoy/config/bootstrap/v3/bootstrap.proto b/api/envoy/config/bootstrap/v3/bootstrap.proto index 56166456f23f5..a1e981fcbddab 100644 --- a/api/envoy/config/bootstrap/v3/bootstrap.proto +++ b/api/envoy/config/bootstrap/v3/bootstrap.proto @@ -40,7 +40,7 @@ option (udpa.annotations.file_status).package_version_status = ACTIVE; // ` for more detail. // Bootstrap :ref:`configuration overview `. -// [#next-free-field: 26] +// [#next-free-field: 27] message Bootstrap { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v2.Bootstrap"; @@ -108,6 +108,40 @@ message Bootstrap { // identification purposes (e.g. in generated headers). core.v3.Node node = 1; + // A list of :ref:`Node ` field names + // that will be included in the context parameters of the effective + // *UdpaResourceLocator* that is sent in a discovery request when resource + // locators are used for LDS/CDS. Any non-string field will have its JSON + // encoding set as the context parameter value, with the exception of + // metadata, which will be flattened (see example below). The supported field + // names are: + // - "cluster" + // - "id" + // - "locality.region" + // - "locality.sub_zone" + // - "locality.zone" + // - "metadata" + // - "user_agent_build_version.metadata" + // - "user_agent_build_version.version" + // - "user_agent_name" + // - "user_agent_version" + // + // The node context parameters act as a base layer dictionary for the context + // parameters (i.e. more specific resource specific context parameters will + // override). Field names will be prefixed with “udpa.node.” when included in + // context parameters. + // + // For example, if node_context_params is ``["user_agent_name", "metadata"]``, + // the implied context parameters might be:: + // + // node.user_agent_name: "envoy" + // node.metadata.foo: "{\"bar\": \"baz\"}" + // node.metadata.some: "42" + // node.metadata.thing: "\"thing\"" + // + // [#not-implemented-hide:] + repeated string node_context_params = 26; + // Statically specified resources. StaticResources static_resources = 2; diff --git a/api/envoy/config/bootstrap/v4alpha/bootstrap.proto b/api/envoy/config/bootstrap/v4alpha/bootstrap.proto index 24faad401e7d4..989ecd30ddc4c 100644 --- a/api/envoy/config/bootstrap/v4alpha/bootstrap.proto +++ b/api/envoy/config/bootstrap/v4alpha/bootstrap.proto @@ -38,7 +38,7 @@ option (udpa.annotations.file_status).package_version_status = NEXT_MAJOR_VERSIO // ` for more detail. // Bootstrap :ref:`configuration overview `. -// [#next-free-field: 26] +// [#next-free-field: 27] message Bootstrap { option (udpa.annotations.versioning).previous_message_type = "envoy.config.bootstrap.v3.Bootstrap"; @@ -106,6 +106,40 @@ message Bootstrap { // identification purposes (e.g. in generated headers). core.v4alpha.Node node = 1; + // A list of :ref:`Node ` field names + // that will be included in the context parameters of the effective + // *UdpaResourceLocator* that is sent in a discovery request when resource + // locators are used for LDS/CDS. Any non-string field will have its JSON + // encoding set as the context parameter value, with the exception of + // metadata, which will be flattened (see example below). The supported field + // names are: + // - "cluster" + // - "id" + // - "locality.region" + // - "locality.sub_zone" + // - "locality.zone" + // - "metadata" + // - "user_agent_build_version.metadata" + // - "user_agent_build_version.version" + // - "user_agent_name" + // - "user_agent_version" + // + // The node context parameters act as a base layer dictionary for the context + // parameters (i.e. more specific resource specific context parameters will + // override). Field names will be prefixed with “udpa.node.” when included in + // context parameters. + // + // For example, if node_context_params is ``["user_agent_name", "metadata"]``, + // the implied context parameters might be:: + // + // node.user_agent_name: "envoy" + // node.metadata.foo: "{\"bar\": \"baz\"}" + // node.metadata.some: "42" + // node.metadata.thing: "\"thing\"" + // + // [#not-implemented-hide:] + repeated string node_context_params = 26; + // Statically specified resources. StaticResources static_resources = 2; diff --git a/api/envoy/config/route/v3/scoped_route.proto b/api/envoy/config/route/v3/scoped_route.proto index f2b28ed974c01..d6611b0b1d06b 100644 --- a/api/envoy/config/route/v3/scoped_route.proto +++ b/api/envoy/config/route/v3/scoped_route.proto @@ -104,6 +104,9 @@ message ScopedRouteConfiguration { repeated Fragment fragments = 1 [(validate.rules).repeated = {min_items: 1}]; } + // Whether the RouteConfiguration should be loaded on demand. + bool on_demand = 4; + // The name assigned to the routing scope. string name = 1 [(validate.rules).string = {min_bytes: 1}]; diff --git a/api/envoy/config/route/v4alpha/scoped_route.proto b/api/envoy/config/route/v4alpha/scoped_route.proto index b1f6915c161b0..33fc756a60a4b 100644 --- a/api/envoy/config/route/v4alpha/scoped_route.proto +++ b/api/envoy/config/route/v4alpha/scoped_route.proto @@ -104,6 +104,9 @@ message ScopedRouteConfiguration { repeated Fragment fragments = 1 [(validate.rules).repeated = {min_items: 1}]; } + // Whether the RouteConfiguration should be loaded on demand. + bool on_demand = 4; + // The name assigned to the routing scope. string name = 1 [(validate.rules).string = {min_bytes: 1}]; diff --git a/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto b/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto index ebb110fcc202e..68c5c8cad2a32 100644 --- a/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto +++ b/api/envoy/extensions/filters/network/http_connection_manager/v3/http_connection_manager.proto @@ -298,7 +298,8 @@ message HttpConnectionManager { // An optional override that the connection manager will write to the server // header in responses. If not set, the default is *envoy*. - string server_name = 10; + string server_name = 10 + [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; // Defines the action to be applied to the Server header on the response path. // By default, Envoy will overwrite the header with the value specified in diff --git a/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto b/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto index 631913354644e..9db92927ebbe1 100644 --- a/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto +++ b/api/envoy/extensions/filters/network/http_connection_manager/v4alpha/http_connection_manager.proto @@ -297,7 +297,8 @@ message HttpConnectionManager { // An optional override that the connection manager will write to the server // header in responses. If not set, the default is *envoy*. - string server_name = 10; + string server_name = 10 + [(validate.rules).string = {well_known_regex: HTTP_HEADER_VALUE strict: false}]; // Defines the action to be applied to the Server header on the response path. // By default, Envoy will overwrite the header with the value specified in diff --git a/api/envoy/extensions/transport_sockets/tls/v3/tls.proto b/api/envoy/extensions/transport_sockets/tls/v3/tls.proto index 7ee7920c724d1..f746f3d2f1cf3 100644 --- a/api/envoy/extensions/transport_sockets/tls/v3/tls.proto +++ b/api/envoy/extensions/transport_sockets/tls/v3/tls.proto @@ -99,7 +99,7 @@ message DownstreamTlsContext { } // TLS context shared by both client and server TLS contexts. -// [#next-free-field: 13] +// [#next-free-field: 14] message CommonTlsContext { option (udpa.annotations.versioning).previous_message_type = "envoy.api.v2.auth.CommonTlsContext"; @@ -238,4 +238,8 @@ message CommonTlsContext { // // There is no default for this parameter. If empty, Envoy will not expose ALPN. repeated string alpn_protocols = 4; + + // Custom TLS handshaker. If empty, defaults to native TLS handshaking + // behavior. + config.core.v3.TypedExtensionConfig custom_handshaker = 13; } diff --git a/api/envoy/extensions/transport_sockets/tls/v4alpha/tls.proto b/api/envoy/extensions/transport_sockets/tls/v4alpha/tls.proto index a73ba6e002ba2..44963f6870732 100644 --- a/api/envoy/extensions/transport_sockets/tls/v4alpha/tls.proto +++ b/api/envoy/extensions/transport_sockets/tls/v4alpha/tls.proto @@ -98,7 +98,7 @@ message DownstreamTlsContext { } // TLS context shared by both client and server TLS contexts. -// [#next-free-field: 13] +// [#next-free-field: 14] message CommonTlsContext { option (udpa.annotations.versioning).previous_message_type = "envoy.extensions.transport_sockets.tls.v3.CommonTlsContext"; @@ -243,4 +243,8 @@ message CommonTlsContext { // // There is no default for this parameter. If empty, Envoy will not expose ALPN. repeated string alpn_protocols = 4; + + // Custom TLS handshaker. If empty, defaults to native TLS handshaking + // behavior. + config.core.v4alpha.TypedExtensionConfig custom_handshaker = 13; } diff --git a/api/envoy/extensions/watchdog/profile_action/v3alpha/profile_action.proto b/api/envoy/extensions/watchdog/profile_action/v3alpha/profile_action.proto index 2bb03f6031322..02636d0fb25f0 100644 --- a/api/envoy/extensions/watchdog/profile_action/v3alpha/profile_action.proto +++ b/api/envoy/extensions/watchdog/profile_action/v3alpha/profile_action.proto @@ -25,11 +25,8 @@ message ProfileActionConfig { // File path to the directory to output profiles. string profile_path = 2 [(validate.rules).string = {min_bytes: 1}]; - // Limits the max number of profiles that can be generated by a thread over - // its lifetime to avoid filling the disk. We keep a map of - // to track the number of profiles triggered by a particular thread. Only one - // thread is counted as triggering the profile even though multiple threads - // might have been eligible for triggering the profile. + // Limits the max number of profiles that can be generated by this action + // over its lifetime to avoid filling the disk. // If not set (i.e. it's 0), a default of 10 will be used. - uint64 max_profiles_per_thread = 3; + uint64 max_profiles = 3; } diff --git a/api/envoy/service/health/v3/BUILD b/api/envoy/service/health/v3/BUILD index ad01f3f340298..e3e214b25d3f1 100644 --- a/api/envoy/service/health/v3/BUILD +++ b/api/envoy/service/health/v3/BUILD @@ -7,6 +7,7 @@ licenses(["notice"]) # Apache 2 api_proto_package( has_services = True, deps = [ + "//envoy/config/cluster/v3:pkg", "//envoy/config/core/v3:pkg", "//envoy/config/endpoint/v3:pkg", "//envoy/service/discovery/v2:pkg", diff --git a/api/envoy/service/health/v3/hds.proto b/api/envoy/service/health/v3/hds.proto index 24fa7e9b5de8d..d73757f7a4fb0 100644 --- a/api/envoy/service/health/v3/hds.proto +++ b/api/envoy/service/health/v3/hds.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.service.health.v3; +import "envoy/config/cluster/v3/cluster.proto"; import "envoy/config/core/v3/base.proto"; import "envoy/config/core/v3/health_check.proto"; import "envoy/config/endpoint/v3/endpoint_components.proto"; @@ -168,6 +169,11 @@ message ClusterHealthCheck { repeated config.core.v3.HealthCheck health_checks = 2; repeated LocalityEndpoints locality_endpoints = 3; + + // Optional map that gets filtered by :ref:`health_checks.transport_socket_match_criteria ` + // on connection when health checking. For more details, see + // :ref:`config.cluster.v3.Cluster.transport_socket_matches `. + repeated config.cluster.v3.Cluster.TransportSocketMatch transport_socket_matches = 4; } message HealthCheckSpecifier { diff --git a/api/envoy/service/health/v4alpha/BUILD b/api/envoy/service/health/v4alpha/BUILD index 448d869e456a2..60bd19511855e 100644 --- a/api/envoy/service/health/v4alpha/BUILD +++ b/api/envoy/service/health/v4alpha/BUILD @@ -7,6 +7,7 @@ licenses(["notice"]) # Apache 2 api_proto_package( has_services = True, deps = [ + "//envoy/config/cluster/v4alpha:pkg", "//envoy/config/core/v4alpha:pkg", "//envoy/config/endpoint/v3:pkg", "//envoy/service/health/v3:pkg", diff --git a/api/envoy/service/health/v4alpha/hds.proto b/api/envoy/service/health/v4alpha/hds.proto index a14e4c9327bac..537d20b58cbb3 100644 --- a/api/envoy/service/health/v4alpha/hds.proto +++ b/api/envoy/service/health/v4alpha/hds.proto @@ -2,6 +2,7 @@ syntax = "proto3"; package envoy.service.health.v4alpha; +import "envoy/config/cluster/v4alpha/cluster.proto"; import "envoy/config/core/v4alpha/base.proto"; import "envoy/config/core/v4alpha/health_check.proto"; import "envoy/config/endpoint/v3/endpoint_components.proto"; @@ -173,6 +174,11 @@ message ClusterHealthCheck { repeated config.core.v4alpha.HealthCheck health_checks = 2; repeated LocalityEndpoints locality_endpoints = 3; + + // Optional map that gets filtered by :ref:`health_checks.transport_socket_match_criteria ` + // on connection when health checking. For more details, see + // :ref:`config.cluster.v3.Cluster.transport_socket_matches `. + repeated config.cluster.v4alpha.Cluster.TransportSocketMatch transport_socket_matches = 4; } message HealthCheckSpecifier { diff --git a/bazel/coverage/fuzz_coverage_wrapper.sh b/bazel/coverage/fuzz_coverage_wrapper.sh index 0510befd60bc4..42d705f7f1345 100755 --- a/bazel/coverage/fuzz_coverage_wrapper.sh +++ b/bazel/coverage/fuzz_coverage_wrapper.sh @@ -12,6 +12,6 @@ mkdir -p fuzz_corpus/seed_corpus cp -r $@ fuzz_corpus/seed_corpus # TODO(asraa): When fuzz targets are stable, remove error suppression and run coverage while fuzzing. -LLVM_PROFILE_FILE= ${TEST_BINARY} fuzz_corpus -seed=${FUZZ_CORPUS_SEED:-1} -max_total_time=${FUZZ_CORPUS_TIME:-60} -max_len=2048 || true +LLVM_PROFILE_FILE= ${TEST_BINARY} fuzz_corpus -seed=${FUZZ_CORPUS_SEED:-1} -max_total_time=${FUZZ_CORPUS_TIME:-60} -max_len=2048 -rss_limit_mb=8192 || true -${TEST_BINARY} fuzz_corpus -runs=0 +${TEST_BINARY} fuzz_corpus -rss_limit_mb=8192 -runs=0 diff --git a/bazel/dependency_imports.bzl b/bazel/dependency_imports.bzl index 4d958fddba763..92c837a4f06a2 100644 --- a/bazel/dependency_imports.bzl +++ b/bazel/dependency_imports.bzl @@ -10,6 +10,7 @@ load("@configs_pip3//:requirements.bzl", configs_pip_install = "pip_install") load("@headersplit_pip3//:requirements.bzl", headersplit_pip_install = "pip_install") load("@kafka_pip3//:requirements.bzl", kafka_pip_install = "pip_install") load("@protodoc_pip3//:requirements.bzl", protodoc_pip_install = "pip_install") +load("@thrift_pip3//:requirements.bzl", thrift_pip_install = "pip_install") load("@rules_antlr//antlr:deps.bzl", "antlr_dependencies") # go version for rules_go @@ -59,3 +60,4 @@ def envoy_dependency_imports(go_version = GO_VERSION): headersplit_pip_install() kafka_pip_install() protodoc_pip_install() + thrift_pip_install() diff --git a/bazel/external/apache_thrift.BUILD b/bazel/external/apache_thrift.BUILD deleted file mode 100644 index db12d91f0b841..0000000000000 --- a/bazel/external/apache_thrift.BUILD +++ /dev/null @@ -1,29 +0,0 @@ -load("@rules_python//python:defs.bzl", "py_library") - -licenses(["notice"]) # Apache 2 - -# The apache-thrift distribution does not keep the thrift files in a directory with the -# expected package name (it uses src/Thrift.py vs src/thrift/Thrift.py), so we provide a -# genrule to copy src/**/*.py to thrift/**/*.py. -src_files = glob(["src/**/*.py"]) - -genrule( - name = "thrift_files", - srcs = src_files, - outs = [f.replace("src/", "thrift/") for f in src_files], - cmd = "\n".join( - ["mkdir -p $$(dirname $(location %s)) && cp $(location %s) $(location :%s)" % ( - f, - f, - f.replace("src/", "thrift/"), - ) for f in src_files], - ), - visibility = ["//visibility:private"], -) - -py_library( - name = "apache_thrift", - srcs = [":thrift_files"], - visibility = ["//visibility:public"], - deps = ["@six"], -) diff --git a/bazel/foreign_cc/luajit.patch b/bazel/foreign_cc/luajit.patch index efa91d3d71c77..b454b7dfd1492 100644 --- a/bazel/foreign_cc/luajit.patch +++ b/bazel/foreign_cc/luajit.patch @@ -59,7 +59,7 @@ EOF @setlocal -@set LJCOMPILE=cl /nologo /c /O2 /W3 /D_CRT_SECURE_NO_DEPRECATE /D_CRT_STDIO_INLINE=__declspec(dllexport)__inline -+@set LJCOMPILE=cl /nologo /c /W3 /D_CRT_SECURE_NO_DEPRECATE /D_CRT_STDIO_INLINE=__declspec(dllexport)__inline ++@set LJCOMPILE=cl /nologo /c /W3 /D_CRT_SECURE_NO_DEPRECATE /D_CRT_STDIO_INLINE=__declspec(dllexport)__inline /DLUAJIT_ENABLE_LUA52COMPAT @set LJLINK=link /nologo @set LJMT=mt /nologo @set LJLIB=lib /nologo /nodefaultlib diff --git a/bazel/foreign_cc/moonjit.patch b/bazel/foreign_cc/moonjit.patch index cbd72dd2a8516..99ac22fb04fe4 100644 --- a/bazel/foreign_cc/moonjit.patch +++ b/bazel/foreign_cc/moonjit.patch @@ -113,7 +113,7 @@ index c2d2c212..71f24422 100644 @rem Add more debug flags here, e.g. DEBUGCFLAGS=/DLUA_USE_APICHECK @set DEBUGCFLAGS= -@set LJCOMPILE=cl /nologo /c /O2 /W3 /D_CRT_SECURE_NO_DEPRECATE /D_CRT_STDIO_INLINE=__declspec(dllexport)__inline -+@set LJCOMPILE=cl /nologo /c /W3 /D_CRT_SECURE_NO_DEPRECATE /D_CRT_STDIO_INLINE=__declspec(dllexport)__inline ++@set LJCOMPILE=cl /nologo /c /W3 /D_CRT_SECURE_NO_DEPRECATE /D_CRT_STDIO_INLINE=__declspec(dllexport)__inline /DLUAJIT_ENABLE_LUA52COMPAT @set LJLINK=link /nologo @set LJMT=mt /nologo @set LJLIB=lib /nologo /nodefaultlib diff --git a/bazel/repositories.bzl b/bazel/repositories.bzl index f66dc9f180ed7..ce30752e1e948 100644 --- a/bazel/repositories.bzl +++ b/bazel/repositories.bzl @@ -95,10 +95,6 @@ _default_envoy_build_config = repository_rule( # Python dependencies. def _python_deps(): # TODO(htuch): convert these to pip3_import. - _repository_impl( - name = "com_github_apache_thrift", - build_file = "@envoy//bazel/external:apache_thrift.BUILD", - ) _repository_impl( name = "com_github_twitter_common_lang", build_file = "@envoy//bazel/external:twitter_common_lang.BUILD", diff --git a/bazel/repositories_extra.bzl b/bazel/repositories_extra.bzl index ca93f0829c781..8e19344926b84 100644 --- a/bazel/repositories_extra.bzl +++ b/bazel/repositories_extra.bzl @@ -7,24 +7,59 @@ def _python_deps(): pip_repositories() pip3_import( + # project_name = "PyYAML", + # project_url = "https://github.com/yaml/pyyaml", + # version = "5.3.1", + # use_category = ["other"], + # cpe = "cpe:2.3:a:pyyaml:pyyaml:*", name = "config_validation_pip3", requirements = "@envoy//tools/config_validation:requirements.txt", + extra_pip_args = ["--require-hashes"], ) pip3_import( + # project_name = "Jinja", + # project_url = "http://palletsprojects.com/p/jinja", + # version = "2.11.2", + # use_category = ["test"], + # cpe = "cpe:2.3:a:palletsprojects:jinja:*", name = "configs_pip3", requirements = "@envoy//configs:requirements.txt", + extra_pip_args = ["--require-hashes"], ) pip3_import( + # project_name = "Jinja", + # project_url = "http://palletsprojects.com/p/jinja", + # version = "2.11.2", + # use_category = ["test"], + # cpe = "cpe:2.3:a:palletsprojects:jinja:*", name = "kafka_pip3", requirements = "@envoy//source/extensions/filters/network/kafka:requirements.txt", + extra_pip_args = ["--require-hashes"], ) pip3_import( name = "headersplit_pip3", requirements = "@envoy//tools/envoy_headersplit:requirements.txt", + extra_pip_args = ["--require-hashes"], ) pip3_import( + # project_name = "PyYAML", + # project_url = "https://github.com/yaml/pyyaml", + # version = "5.3.1", + # use_category = ["other"], + # cpe = "cpe:2.3:a:pyyaml:pyyaml:*", name = "protodoc_pip3", requirements = "@envoy//tools/protodoc:requirements.txt", + extra_pip_args = ["--require-hashes"], + ) + pip3_import( + # project_name = "Apache Thrift", + # project_url = "http://thrift.apache.org/", + # version = "0.11.0", + # use_category = ["dataplane"], + # cpe = "cpe:2.3:a:apache:thrift:*", + name = "thrift_pip3", + requirements = "@envoy//test/extensions/filters/network/thrift_proxy:requirements.txt", + extra_pip_args = ["--require-hashes"], ) # Envoy deps that rely on a first stage of dependency loading in envoy_dependencies(). diff --git a/bazel/repository_locations.bzl b/bazel/repository_locations.bzl index c0dfc2522310c..e1cddcc8513df 100644 --- a/bazel/repository_locations.bzl +++ b/bazel/repository_locations.bzl @@ -125,16 +125,6 @@ DEPENDENCY_REPOSITORIES_SPEC = dict( use_category = ["dataplane", "controlplane"], cpe = "N/A", ), - com_github_apache_thrift = dict( - project_name = "Apache Thrift", - project_url = "http://thrift.apache.org/", - version = "0.11.0", - sha256 = "7d59ac4fdcb2c58037ebd4a9da5f9a49e3e034bf75b3f26d9fe48ba3d8806e6b", - strip_prefix = "thrift-{version}", - urls = ["https://files.pythonhosted.org/packages/c6/b4/510617906f8e0c5660e7d96fbc5585113f83ad547a3989b80297ac72a74c/thrift-{version}.tar.gz"], - use_category = ["dataplane"], - cpe = "cpe:2.3:a:apache:thrift:*", - ), com_github_c_ares_c_ares = dict( project_name = "c-ares", project_url = "https://c-ares.haxx.se/", @@ -520,7 +510,7 @@ DEPENDENCY_REPOSITORIES_SPEC = dict( ), io_opencensus_cpp = dict( project_name = "OpenCensus C++", - project_url = "https://pypi.org/project/six/", + project_url = "https://github.com/census-instrumentation/opencensus-cpp", # 2020-06-01 version = "7877337633466358ed680f9b26967da5b310d7aa", sha256 = "12ff300fa804f97bd07e2ff071d969e09d5f3d7bbffeac438c725fa52a51a212", @@ -643,7 +633,7 @@ DEPENDENCY_REPOSITORIES_SPEC = dict( version = "2.4.1", sha256 = "2177cbd14118999e1d76fec628ca78ace7e6f841219dbc6035027c796bbe1a2a", strip_prefix = "kafka_2.12-{version}", - urls = ["http://us.mirrors.quenda.co/apache/kafka/{version}/kafka_2.12-{version}.tgz"], + urls = ["https://mirrors.gigenet.com/apache/kafka/{version}/kafka_2.12-{version}.tgz"], use_category = ["test"], ), kafka_python_client = dict( diff --git a/ci/do_ci.sh b/ci/do_ci.sh index 15242773be40b..2f5f183ea9379 100755 --- a/ci/do_ci.sh +++ b/ci/do_ci.sh @@ -12,8 +12,11 @@ if [[ "$1" == "fix_format" || "$1" == "check_format" || "$1" == "check_repositor fi SRCDIR="${PWD}" -. "$(dirname "$0")"/setup_cache.sh -. "$(dirname "$0")"/build_setup.sh $build_setup_args +NO_BUILD_SETUP="${NO_BUILD_SETUP:-}" +if [[ -z "$NO_BUILD_SETUP" ]]; then + . "$(dirname "$0")"/setup_cache.sh + . "$(dirname "$0")"/build_setup.sh $build_setup_args +fi cd "${SRCDIR}" if [[ "${ENVOY_BUILD_ARCH}" == "x86_64" ]]; then @@ -399,6 +402,23 @@ elif [[ "$CI_TARGET" == "docs" ]]; then echo "generating docs..." docs/build.sh exit 0 +elif [[ "$CI_TARGET" == "verify_examples" ]]; then + echo "verify examples..." + docker load < "$ENVOY_DOCKER_BUILD_DIR/docker/envoy-docker-images.tar.xz" + images=($(docker image list --format "{{.Repository}}")) + tags=($(docker image list --format "{{.Tag}}")) + for i in "${!images[@]}"; do + if [[ "${images[i]}" =~ "envoy" ]]; then + docker tag "${images[$i]}:${tags[$i]}" "${images[$i]}:latest" + fi + done + docker images + sudo apt-get update -y + sudo apt-get install -y -qq --no-install-recommends redis-tools + export DOCKER_NO_PULL=1 + umask 027 + ci/verify_examples.sh + exit 0 else echo "Invalid do_ci.sh target, see ci/README.md for valid targets." exit 1 diff --git a/ci/verify_examples.sh b/ci/verify_examples.sh index 711ceb5f25a30..4e459464aeda4 100755 --- a/ci/verify_examples.sh +++ b/ci/verify_examples.sh @@ -1,43 +1,67 @@ -#!/bin/bash +#!/bin/bash -E -set -e +TESTFILTER="${1:-*}" +FAILED=() +SRCDIR="${SRCDIR:-$(pwd)}" +EXCLUDED_BUILD_CONFIGS=${EXCLUDED_BUILD_CONFIGS:-"^./jaeger-native-tracing|docker-compose"} -verify() { - echo $1 - CONTAINER_ID="$(docker ps -aqf name=$1)" - if [ "false" == "$(docker inspect -f {{.State.Running}} ${CONTAINER_ID})" ] - then - echo "error: $1 not running" - exit 1 - fi + +trap_errors () { + local frame=0 command line sub file + if [[ -n "$example" ]]; then + command=" (${example})" + fi + set +v + while read -r line sub file < <(caller "$frame"); do + if [[ "$frame" -ne "0" ]]; then + FAILED+=(" > ${sub}@ ${file} :${line}") + else + FAILED+=("${sub}@ ${file} :${line}${command}") + fi + ((frame++)) + done + set -v +} + +trap trap_errors ERR +trap exit 1 INT + + +run_examples () { + local examples example + cd "${SRCDIR}/examples" || exit 1 + examples=$(find . -mindepth 1 -maxdepth 1 -type d -name "$TESTFILTER" | sort) + for example in $examples; do + pushd "$example" > /dev/null || return 1 + ./verify.sh + popd > /dev/null || return 1 + done } -# Test front proxy example -cd examples/front-proxy -docker-compose up --build -d -for CONTAINER_NAME in "frontproxy_front-envoy" "frontproxy_service1" "frontproxy_service2" -do - verify $CONTAINER_NAME -done -cd ../ - -# Test grpc bridge example -# install go -GO_VERSION="1.14.7" -curl -O https://storage.googleapis.com/golang/go$GO_VERSION.linux-amd64.tar.gz -tar -xf go$GO_VERSION.linux-amd64.tar.gz -sudo mv go /usr/local -export PATH=$PATH:/usr/local/go/bin -export GOPATH=$HOME/go -mkdir -p $GOPATH/src/github.com/envoyproxy/envoy/examples/ -cp -r grpc-bridge $GOPATH/src/github.com/envoyproxy/envoy/examples/ -# build example -cd $GOPATH/src/github.com/envoyproxy/envoy/examples/grpc-bridge -./script/bootstrap -./script/build -# verify example works -docker-compose up --build -d -for CONTAINER_NAME in "grpcbridge_python" "grpcbridge_grpc" -do - verify $CONTAINER_NAME -done +verify_build_configs () { + local config configs missing + missing=() + cd "${SRCDIR}/examples" || return 1 + configs="$(find . -name "*.yaml" -o -name "*.lua" | grep -vE "${EXCLUDED_BUILD_CONFIGS}" | cut -d/ -f2-)" + for config in $configs; do + grep "\"$config\"" BUILD || missing+=("$config") + done + if [[ -n "${missing[*]}" ]]; then + for config in "${missing[@]}"; do + echo "Missing config: $config" >&2 + done + return 1 + fi +} + +verify_build_configs +run_examples + + +if [[ "${#FAILED[@]}" -ne "0" ]]; then + echo "TESTS FAILED:" + for failed in "${FAILED[@]}"; do + echo "$failed" >&2 + done + exit 1 +fi diff --git a/ci/windows_ci_steps.sh b/ci/windows_ci_steps.sh index b88dc6697dbfd..498445d9b9490 100755 --- a/ci/windows_ci_steps.sh +++ b/ci/windows_ci_steps.sh @@ -25,7 +25,9 @@ if [ ! -e "/$drive/$drive" ]; then fi BAZEL_STARTUP_OPTIONS="--output_base=c:/_eb" -BAZEL_BUILD_OPTIONS="-c opt --config=msvc-cl --show_task_finish --verbose_failures \ +# Default to msvc-cl if not overridden +BAZEL_BUILD_EXTRA_OPTIONS=${BAZEL_BUILD_EXTRA_OPTIONS:---config=msvc-cl} +BAZEL_BUILD_OPTIONS="-c opt --show_task_finish --verbose_failures \ --test_output=errors ${BAZEL_BUILD_EXTRA_OPTIONS} ${BAZEL_EXTRA_TEST_OPTIONS}" # Test to validate updates of all dependency libraries in bazel/external and bazel/foreign_cc diff --git a/configs/requirements.txt b/configs/requirements.txt index b52f9745422be..07e1fe994fc33 100644 --- a/configs/requirements.txt +++ b/configs/requirements.txt @@ -1,2 +1,37 @@ -Jinja2==2.11.2 -MarkupSafe==1.1.1 +Jinja2==2.11.2 \ + --hash=sha256:89aab215427ef59c34ad58735269eb58b1a5808103067f7bb9d5836c651b3bb0 \ + --hash=sha256:f0a4641d3cf955324a89c04f3d94663aa4d638abe8f733ecd3582848e1c37035 +MarkupSafe==1.1.1 \ + --hash=sha256:00bc623926325b26bb9605ae9eae8a215691f33cae5df11ca5424f06f2d1f473 \ + --hash=sha256:09027a7803a62ca78792ad89403b1b7a73a01c8cb65909cd876f7fcebd79b161 \ + --hash=sha256:09c4b7f37d6c648cb13f9230d847adf22f8171b1ccc4d5682398e77f40309235 \ + --hash=sha256:1027c282dad077d0bae18be6794e6b6b8c91d58ed8a8d89a89d59693b9131db5 \ + --hash=sha256:13d3144e1e340870b25e7b10b98d779608c02016d5184cfb9927a9f10c689f42 \ + --hash=sha256:24982cc2533820871eba85ba648cd53d8623687ff11cbb805be4ff7b4c971aff \ + --hash=sha256:29872e92839765e546828bb7754a68c418d927cd064fd4708fab9fe9c8bb116b \ + --hash=sha256:43a55c2930bbc139570ac2452adf3d70cdbb3cfe5912c71cdce1c2c6bbd9c5d1 \ + --hash=sha256:46c99d2de99945ec5cb54f23c8cd5689f6d7177305ebff350a58ce5f8de1669e \ + --hash=sha256:500d4957e52ddc3351cabf489e79c91c17f6e0899158447047588650b5e69183 \ + --hash=sha256:535f6fc4d397c1563d08b88e485c3496cf5784e927af890fb3c3aac7f933ec66 \ + --hash=sha256:596510de112c685489095da617b5bcbbac7dd6384aeebeda4df6025d0256a81b \ + --hash=sha256:62fe6c95e3ec8a7fad637b7f3d372c15ec1caa01ab47926cfdf7a75b40e0eac1 \ + --hash=sha256:6788b695d50a51edb699cb55e35487e430fa21f1ed838122d722e0ff0ac5ba15 \ + --hash=sha256:6dd73240d2af64df90aa7c4e7481e23825ea70af4b4922f8ede5b9e35f78a3b1 \ + --hash=sha256:717ba8fe3ae9cc0006d7c451f0bb265ee07739daf76355d06366154ee68d221e \ + --hash=sha256:79855e1c5b8da654cf486b830bd42c06e8780cea587384cf6545b7d9ac013a0b \ + --hash=sha256:7c1699dfe0cf8ff607dbdcc1e9b9af1755371f92a68f706051cc8c37d447c905 \ + --hash=sha256:88e5fcfb52ee7b911e8bb6d6aa2fd21fbecc674eadd44118a9cc3863f938e735 \ + --hash=sha256:8defac2f2ccd6805ebf65f5eeb132adcf2ab57aa11fdf4c0dd5169a004710e7d \ + --hash=sha256:98c7086708b163d425c67c7a91bad6e466bb99d797aa64f965e9d25c12111a5e \ + --hash=sha256:9add70b36c5666a2ed02b43b335fe19002ee5235efd4b8a89bfcf9005bebac0d \ + --hash=sha256:9bf40443012702a1d2070043cb6291650a0841ece432556f784f004937f0f32c \ + --hash=sha256:ade5e387d2ad0d7ebf59146cc00c8044acbd863725f887353a10df825fc8ae21 \ + --hash=sha256:b00c1de48212e4cc9603895652c5c410df699856a2853135b3967591e4beebc2 \ + --hash=sha256:b1282f8c00509d99fef04d8ba936b156d419be841854fe901d8ae224c59f0be5 \ + --hash=sha256:b2051432115498d3562c084a49bba65d97cf251f5a331c64a12ee7e04dacc51b \ + --hash=sha256:ba59edeaa2fc6114428f1637ffff42da1e311e29382d81b339c1817d37ec93c6 \ + --hash=sha256:c8716a48d94b06bb3b2524c2b77e055fb313aeb4ea620c8dd03a105574ba704f \ + --hash=sha256:cd5df75523866410809ca100dc9681e301e3c27567cf498077e8551b6d20e42f \ + --hash=sha256:cdb132fc825c38e1aeec2c8aa9338310d29d337bebbd7baa06889d09a60a1fa2 \ + --hash=sha256:e249096428b3ae81b08327a63a485ad0878de3fb939049038579ac0ef61e17e7 \ + --hash=sha256:e8313f01ba26fbbe36c7be1966a7b7424942f670f38e666995b88d012765b9be diff --git a/docs/root/_static/searchtools.js b/docs/root/_static/searchtools.js new file mode 100644 index 0000000000000..bd46e53c35018 --- /dev/null +++ b/docs/root/_static/searchtools.js @@ -0,0 +1,565 @@ +/* + * searchtools.js + * ~~~~~~~~~~~~~~~~ + * + * Sphinx JavaScript utilities for the full-text search. + * + * :copyright: Copyright 2007-2020 by the Sphinx team, see AUTHORS. + * :license: BSD, see LICENSE for details. + * + */ + +if (!Scorer) { + /** + * Simple result scoring code. + */ + var Scorer = { + // Implement the following function to further tweak the score for each result + // The function takes a result array [filename, title, anchor, descr, score] + // and returns the new score. + /* + score: function(result) { + return result[4]; + }, + */ + + // query matches the full name of an object + objNameMatch: 11, + // or matches in the last dotted part of the object name + objPartialMatch: 6, + // Additive scores depending on the priority of the object + objPrio: { + 0: 15, // used to be importantResults + 1: 5, // used to be objectResults + 2: -5, + }, // used to be unimportantResults + // Used when the priority is not in the mapping. + objPrioDefault: 0, + + // query found in title + title: 15, + partialTitle: 7, + // query found in terms + term: 5, + partialTerm: 2, + }; +} + +if (!splitQuery) { + function splitQuery(query) { + return query.split(/\s+/); + } +} + +/** + * Search Module + */ +var Search = { + _index: null, + _queued_query: null, + _pulse_status: -1, + + htmlToText: function (htmlString) { + var htmlElement = document.createElement("span"); + htmlElement.innerHTML = htmlString; + $(htmlElement).find(".headerlink").remove(); + docContent = $(htmlElement).find("[role=main]")[0]; + if (docContent === undefined) { + console.warn( + "Content block not found. Sphinx search tries to obtain it " + + "via '[role=main]'. Could you check your theme or template." + ); + return ""; + } + return docContent.textContent || docContent.innerText; + }, + + init: function () { + var params = $.getQueryParameters(); + if (params.q) { + var query = params.q[0]; + $('input[name="q"]')[0].value = query; + this.performSearch(query); + } + }, + + loadIndex: function (url) { + $.ajax({ + type: "GET", + url: url, + data: null, + dataType: "script", + cache: true, + complete: function (jqxhr, textstatus) { + if (textstatus != "success") { + document.getElementById("searchindexloader").src = url; + } + }, + }); + }, + + setIndex: function (index) { + var q; + this._index = index; + if ((q = this._queued_query) !== null) { + this._queued_query = null; + Search.query(q); + } + }, + + hasIndex: function () { + return this._index !== null; + }, + + deferQuery: function (query) { + this._queued_query = query; + }, + + stopPulse: function () { + this._pulse_status = 0; + }, + + startPulse: function () { + if (this._pulse_status >= 0) return; + function pulse() { + var i; + Search._pulse_status = (Search._pulse_status + 1) % 4; + var dotString = ""; + for (i = 0; i < Search._pulse_status; i++) dotString += "."; + Search.dots.text(dotString); + if (Search._pulse_status > -1) window.setTimeout(pulse, 500); + } + pulse(); + }, + + /** + * perform a search for something (or wait until index is loaded) + */ + performSearch: function (query) { + // create the required interface elements + this.out = $("#search-results"); + this.title = $("

" + _("Searching") + "

").appendTo(this.out); + this.dots = $("").appendTo(this.title); + this.status = $('

 

').appendTo(this.out); + this.output = $('