[
{
"path": ".config/dotnet-tools.json",
"content": "{\n \"version\": 1,\n \"isRoot\": true,\n \"tools\": {\n \"cake.tool\": {\n \"version\": \"6.1.0\",\n \"commands\": [\n \"dotnet-cake\"\n ]\n },\n \"dotnet-reportgenerator-globaltool\": {\n \"version\": \"5.5.4\",\n \"commands\": [\n \"reportgenerator\"\n ],\n \"rollForward\": false\n }\n }\n}\n"
},
{
"path": ".dockerignore",
"content": "*/*/bin\r\n*/*/obj\r\nartifacts/\r\nTestResults/\r\ntools/"
},
{
"path": ".editorconfig",
"content": "# Remove the line below if you want to inherit .editorconfig settings from higher directories\r\nroot = true\r\n\r\n# XML files\r\n[*.xml]\r\nindent_style = space\r\nindent_size = 2\r\n\r\n# C# files\r\n[*.cs]\r\n\r\n#### Core EditorConfig Options ####\r\n\r\n# Indentation and spacing\r\nindent_size = 4\r\nindent_style = space\r\ntab_width = 4\r\n\r\n# New line preferences\r\nend_of_line = crlf\r\ninsert_final_newline = true\r\n\r\n#### .NET Coding Conventions ####\r\n\r\n# Organize usings\r\ndotnet_separate_import_directive_groups = false\r\ndotnet_sort_system_directives_first = false\r\nfile_header_template = unset\r\n\r\n# this. and Me. preferences\r\ndotnet_style_qualification_for_event = false\r\ndotnet_style_qualification_for_field = false\r\ndotnet_style_qualification_for_method = false\r\ndotnet_style_qualification_for_property = false\r\n\r\n# Language keywords vs BCL types preferences\r\ndotnet_style_predefined_type_for_locals_parameters_members = true\r\ndotnet_style_predefined_type_for_member_access = true\r\n\r\n# Parentheses preferences\r\ndotnet_style_parentheses_in_arithmetic_binary_operators = always_for_clarity\r\ndotnet_style_parentheses_in_other_binary_operators = always_for_clarity\r\ndotnet_style_parentheses_in_other_operators = never_if_unnecessary\r\ndotnet_style_parentheses_in_relational_binary_operators = always_for_clarity\r\n\r\n# Modifier preferences\r\ndotnet_style_require_accessibility_modifiers = for_non_interface_members\r\n\r\n# Expression-level preferences\r\ndotnet_style_coalesce_expression = true\r\ndotnet_style_collection_initializer = true\r\ndotnet_style_explicit_tuple_names = true\r\ndotnet_style_namespace_match_folder = true\r\ndotnet_style_null_propagation = true\r\ndotnet_style_object_initializer = true\r\ndotnet_style_operator_placement_when_wrapping = beginning_of_line\r\ndotnet_style_prefer_auto_properties = true\r\ndotnet_style_prefer_collection_expression = false:suggestion\r\ndotnet_style_prefer_compound_assignment = true\r\ndotnet_style_prefer_conditional_expression_over_assignment = true\r\ndotnet_style_prefer_conditional_expression_over_return = true\r\ndotnet_style_prefer_foreach_explicit_cast_in_source = when_strongly_typed\r\ndotnet_style_prefer_inferred_anonymous_type_member_names = true\r\ndotnet_style_prefer_inferred_tuple_names = true\r\ndotnet_style_prefer_is_null_check_over_reference_equality_method = true\r\ndotnet_style_prefer_simplified_boolean_expressions = true\r\ndotnet_style_prefer_simplified_interpolation = true\r\n\r\n# Field preferences\r\ndotnet_style_readonly_field = true\r\n\r\n# Parameter preferences\r\ndotnet_code_quality_unused_parameters = all\r\n\r\n# Suppression preferences\r\ndotnet_remove_unnecessary_suppression_exclusions = none\r\n\r\n# New line preferences\r\ndotnet_style_allow_multiple_blank_lines_experimental = true\r\ndotnet_style_allow_statement_immediately_after_block_experimental = true\r\n\r\n#### C# Coding Conventions ####\r\n\r\n# var preferences\r\ncsharp_style_var_elsewhere = false\r\ncsharp_style_var_for_built_in_types = false\r\ncsharp_style_var_when_type_is_apparent = false\r\n\r\n# Expression-bodied members\r\ncsharp_style_expression_bodied_accessors = true:silent\r\ncsharp_style_expression_bodied_constructors = false:silent\r\ncsharp_style_expression_bodied_indexers = true:silent\r\ncsharp_style_expression_bodied_lambdas = true:silent\r\ncsharp_style_expression_bodied_local_functions = false:silent\r\ncsharp_style_expression_bodied_methods = false:silent\r\ncsharp_style_expression_bodied_operators = false:silent\r\ncsharp_style_expression_bodied_properties = true:silent\r\n\r\n# Pattern matching preferences\r\ncsharp_style_pattern_matching_over_as_with_null_check = true\r\ncsharp_style_pattern_matching_over_is_with_cast_check = true\r\ncsharp_style_prefer_extended_property_pattern = true\r\ncsharp_style_prefer_not_pattern = true\r\ncsharp_style_prefer_pattern_matching = true\r\ncsharp_style_prefer_switch_expression = true\r\n\r\n# Null-checking preferences\r\ncsharp_style_conditional_delegate_call = true\r\n\r\n# Modifier preferences\r\ncsharp_prefer_static_local_function = true\r\ncsharp_preferred_modifier_order = public,private,protected,internal,file,static,extern,new,virtual,abstract,sealed,override,readonly,unsafe,required,volatile,async\r\ncsharp_style_prefer_readonly_struct = true\r\ncsharp_style_prefer_readonly_struct_member = true\r\n\r\n# Code-block preferences\r\ncsharp_prefer_braces = true:silent\r\ncsharp_prefer_simple_using_statement = true:suggestion\r\ncsharp_style_namespace_declarations = block_scoped:silent\r\ncsharp_style_prefer_method_group_conversion = true:silent\r\ncsharp_style_prefer_primary_constructors = false:suggestion\r\ncsharp_style_prefer_top_level_statements = true:silent\r\n\r\n# Expression-level preferences\r\ncsharp_prefer_simple_default_expression = true\r\ncsharp_style_deconstructed_variable_declaration = true\r\ncsharp_style_implicit_object_creation_when_type_is_apparent = true\r\ncsharp_style_inlined_variable_declaration = true\r\ncsharp_style_prefer_index_operator = true\r\ncsharp_style_prefer_local_over_anonymous_function = true\r\ncsharp_style_prefer_null_check_over_type_check = true\r\ncsharp_style_prefer_range_operator = true\r\ncsharp_style_prefer_tuple_swap = true\r\ncsharp_style_prefer_utf8_string_literals = true\r\ncsharp_style_throw_expression = true\r\ncsharp_style_unused_value_assignment_preference = discard_variable\r\ncsharp_style_unused_value_expression_statement_preference = discard_variable\r\n\r\n# 'using' directive preferences\r\ncsharp_using_directive_placement = outside_namespace:silent\r\n\r\n# New line preferences\r\ncsharp_style_allow_blank_line_after_colon_in_constructor_initializer_experimental = true\r\ncsharp_style_allow_blank_line_after_token_in_arrow_expression_clause_experimental = true\r\ncsharp_style_allow_blank_line_after_token_in_conditional_expression_experimental = true\r\ncsharp_style_allow_blank_lines_between_consecutive_braces_experimental = true\r\ncsharp_style_allow_embedded_statements_on_same_line_experimental = true\r\n\r\n#### C# Formatting Rules ####\r\n\r\n# New line preferences\r\ncsharp_new_line_before_catch = true\r\ncsharp_new_line_before_else = true\r\ncsharp_new_line_before_finally = true\r\ncsharp_new_line_before_members_in_anonymous_types = true\r\ncsharp_new_line_before_members_in_object_initializers = true\r\ncsharp_new_line_before_open_brace = all\r\ncsharp_new_line_between_query_expression_clauses = true\r\n\r\n# Indentation preferences\r\ncsharp_indent_block_contents = true\r\ncsharp_indent_braces = false\r\ncsharp_indent_case_contents = true\r\ncsharp_indent_case_contents_when_block = true\r\ncsharp_indent_labels = one_less_than_current\r\ncsharp_indent_switch_labels = true\r\n\r\n# Space preferences\r\ncsharp_space_after_cast = false\r\ncsharp_space_after_colon_in_inheritance_clause = true\r\ncsharp_space_after_comma = true\r\ncsharp_space_after_dot = false\r\ncsharp_space_after_keywords_in_control_flow_statements = true\r\ncsharp_space_after_semicolon_in_for_statement = true\r\ncsharp_space_around_binary_operators = before_and_after\r\ncsharp_space_around_declaration_statements = false\r\ncsharp_space_before_colon_in_inheritance_clause = true\r\ncsharp_space_before_comma = false\r\ncsharp_space_before_dot = false\r\ncsharp_space_before_open_square_brackets = false\r\ncsharp_space_before_semicolon_in_for_statement = false\r\ncsharp_space_between_empty_square_brackets = false\r\ncsharp_space_between_method_call_empty_parameter_list_parentheses = false\r\ncsharp_space_between_method_call_name_and_opening_parenthesis = false\r\ncsharp_space_between_method_call_parameter_list_parentheses = false\r\ncsharp_space_between_method_declaration_empty_parameter_list_parentheses = false\r\ncsharp_space_between_method_declaration_name_and_open_parenthesis = false\r\ncsharp_space_between_method_declaration_parameter_list_parentheses = false\r\ncsharp_space_between_parentheses = false\r\ncsharp_space_between_square_brackets = false\r\n\r\n# Wrapping preferences\r\ncsharp_preserve_single_line_blocks = true\r\ncsharp_preserve_single_line_statements = true\r\n\r\n#### Naming styles ####\r\n\r\n# Naming rules\r\n\r\ndotnet_naming_rule.interface_should_be_begins_with_i.severity = suggestion\r\ndotnet_naming_rule.interface_should_be_begins_with_i.symbols = interface\r\ndotnet_naming_rule.interface_should_be_begins_with_i.style = begins_with_i\r\n\r\ndotnet_naming_rule.types_should_be_pascal_case.severity = suggestion\r\ndotnet_naming_rule.types_should_be_pascal_case.symbols = types\r\ndotnet_naming_rule.types_should_be_pascal_case.style = pascal_case\r\n\r\ndotnet_naming_rule.non_field_members_should_be_pascal_case.severity = suggestion\r\ndotnet_naming_rule.non_field_members_should_be_pascal_case.symbols = non_field_members\r\ndotnet_naming_rule.non_field_members_should_be_pascal_case.style = pascal_case\r\n\r\n# Symbol specifications\r\n\r\ndotnet_naming_symbols.interface.applicable_kinds = interface\r\ndotnet_naming_symbols.interface.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected\r\ndotnet_naming_symbols.interface.required_modifiers = \r\n\r\ndotnet_naming_symbols.types.applicable_kinds = class, struct, interface, enum\r\ndotnet_naming_symbols.types.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected\r\ndotnet_naming_symbols.types.required_modifiers = \r\n\r\ndotnet_naming_symbols.non_field_members.applicable_kinds = property, event, method\r\ndotnet_naming_symbols.non_field_members.applicable_accessibilities = public, internal, private, protected, protected_internal, private_protected\r\ndotnet_naming_symbols.non_field_members.required_modifiers = \r\n\r\n# Naming styles\r\n\r\ndotnet_naming_style.pascal_case.required_prefix = \r\ndotnet_naming_style.pascal_case.required_suffix = \r\ndotnet_naming_style.pascal_case.word_separator = \r\ndotnet_naming_style.pascal_case.capitalization = pascal_case\r\n\r\ndotnet_naming_style.begins_with_i.required_prefix = I\r\ndotnet_naming_style.begins_with_i.required_suffix = \r\ndotnet_naming_style.begins_with_i.word_separator = \r\ndotnet_naming_style.begins_with_i.capitalization = pascal_case\r\n\r\n[*.{cs,vb}]\r\ndotnet_style_operator_placement_when_wrapping = beginning_of_line\r\ntab_width = 4\r\nindent_size = 4\r\nend_of_line = crlf\r\ndotnet_style_coalesce_expression = true:suggestion\r\ninsert_final_newline = true\r\ndotnet_style_null_propagation = true:suggestion\r\ndotnet_style_prefer_is_null_check_over_reference_equality_method = true:suggestion\r\n"
},
{
"path": ".gitattributes",
"content": "# 2010\r\n*.txt -crlf\r\n\r\n# 2020\r\n*.txt text eol=lf "
},
{
"path": ".github/CODE_OF_CONDUCT.md",
"content": "# Contributor Covenant Code of Conduct\r\n\r\n## Our Pledge\r\n\r\nIn the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.\r\n\r\n## Our Standards\r\n\r\nExamples of behavior that contributes to creating a positive environment include:\r\n\r\n* Using welcoming and inclusive language\r\n* Being respectful of differing viewpoints and experiences\r\n* Gracefully accepting constructive criticism\r\n* Focusing on what is best for the community\r\n* Showing empathy towards other community members\r\n\r\nExamples of unacceptable behavior by participants include:\r\n\r\n* The use of sexualized language or imagery and unwelcome sexual attention or advances\r\n* Trolling, insulting/derogatory comments, and personal or political attacks\r\n* Public or private harassment\r\n* Publishing others' private information, such as a physical or electronic address, without explicit permission\r\n* Other conduct which could reasonably be considered inappropriate in a professional setting\r\n\r\n## Our Responsibilities\r\n\r\nProject maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.\r\n\r\nProject maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.\r\n\r\n## Scope\r\n\r\nThis Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.\r\n\r\n## Enforcement\r\n\r\nInstances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at tom@threemammals.co.uk. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.\r\n\r\nProject maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.\r\n\r\n## Attribution\r\n\r\nThis Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [http://contributor-covenant.org/version/1/4][version]\r\n\r\n[homepage]: http://contributor-covenant.org\r\n[version]: http://contributor-covenant.org/version/1/4/\r\n"
},
{
"path": ".github/CONTRIBUTING.md",
"content": "We love to receive contributions from the community so please keep them coming :) \r\n\r\nPull requests, issues and commentary welcome!\r\n\r\nPlease complete the relevant template for issues and PRs. Sometimes it's worth getting in touch with us to discuss changes \r\nbefore doing any work incase this is something we are already doing or it might not make sense. We can also give\r\nadvice on the easiest way to do things :)\r\n\r\nFinally we mark all existing issues as help wanted, small, medium and large effort. If you want to contribute for the first time I suggest looking at a help wanted & small effort issue :)\r\n"
},
{
"path": ".github/ISSUE_TEMPLATE.md",
"content": "## Expected Behavior / New Feature\r\n\r\n\r\n## Actual Behavior / Motivation for New Feature\r\n\r\n\r\n## Steps to Reproduce the Problem\r\n\r\n 1.\r\n 1.\r\n 1.\r\n\r\n## Specifications\r\n\r\n - Version:\r\n - Platform:\r\n - Subsystem:\r\n"
},
{
"path": ".github/PULL_REQUEST_TEMPLATE.md",
"content": "Fixes / New Feature #\r\n\r\n## Proposed Changes\r\n\r\n -\r\n -\r\n -\r\n"
},
{
"path": ".github/steps/check-dotnet.sh",
"content": "#!/bin/bash\n\n# First argument: target .NET major version (digit)\n# Default to 8 if no argument is provided\nDOTNET_VERSION=\"${1:-8}\"\n\n# Check .NET $DOTNET_VERSION\nDOTNET_INFO=$(dotnet --info)\necho Checking for .NET $DOTNET_VERSION SDK in dotnet info output...\necho -------------------------------------------------------------\n\n# Print matching lines\necho \"$DOTNET_INFO\" | grep -E \"^\\s*${DOTNET_VERSION}\\.0\\.[0-9]+\\s+\\[/usr/share/dotnet/sdk\\]\"\n\n# Set environment variable based on match\nif echo \"$DOTNET_INFO\" | grep -qE \"^\\s*${DOTNET_VERSION}\\.0\\.[0-9]+\\s+\\[/usr/share/dotnet/sdk\\]\"; then\n echo \"DOTNET${DOTNET_VERSION}_installed=true\" >> \"$GITHUB_ENV\"\nelse\n echo \"DOTNET${DOTNET_VERSION}_installed=false\" >> \"$GITHUB_ENV\"\nfi\n"
},
{
"path": ".github/steps/macos.add-dns-records.sh",
"content": "#!/bin/bash\nhosts=\"/etc/hosts\"\nif [ ! -f \"$hosts\" ]; then\n echo \"$hosts not found.\"\n exit 1\nfi\n\n# Find the line number of the last line that starts with \"##\"\nlast_index=$(grep -n '^##' \"$hosts\" | tail -n 1 | cut -d: -f1)\n\n# Check if the line exists\nif [ -z \"$last_index\" ]; then\n echo No lines start with '##' in $hosts\n exit 1\nfi\n\n# Insert DNS-record after the last \"##\" line\nrecord=\"127.0.0.1 threemammals.com\"\n# This 3-line sed script fixes the issue when embedded as a run-action script in GitHub Actions.\n# The problem prevents the workflow file from being parsed correctly, which stops the workflow from starting.\nsudo sed -i '' \"${last_index}a\\\\\n$record\n\" $hosts\n\necho \"Inserted '$record' after line $last_index.\"\necho DNS-record added to $hosts\necho ------------------------\ncat $hosts\necho ------------------------\n\n# The threemammals.com domain is registered for email services\n# https://registrar.ionos.com/domains_raa/whois\n# So, go ahead and clear the DNS cache\nsudo killall -HUP mDNSResponder\n\nping -c 3 threemammals.com\n\n# Additional Loopback IPs\necho -n \"Adding multiple aliases in a loop...\"\nfor i in {2..255}; do\n sudo ifconfig lo0 alias 127.0.0.$i up\ndone\necho DONE\necho ------------------------\necho Test Loopback IPs\nfor i in {2..255}; do\n echo ping 127.0.0.$i ...\n ping -c 1 127.0.0.$i\ndone\n"
},
{
"path": ".github/steps/macos.install-certificate.sh",
"content": "#!/bin/bash\n# Install mycert2.crt certificate\ncrt='./test/Ocelot.AcceptanceTests/mycert2.crt'\nopenssl version\necho Moving the certificate to the trusted CA store...\nif [ ! -f \"$crt\" ]; then\n echo \"Certificate file not found: $crt\"\n exit 1\nfi\ncert_root=\"/Library/Keychains/System.keychain\"\nsudo security add-trusted-cert -d -r trustRoot -k \"$cert_root\" \"$crt\"\necho Certificate added to trusted keychain.\n\necho Verifying installation by listing certificates in $cert_root ...\nsudo security find-certificate -a -c \"threemammals\" -p \"$cert_root\"\n\necho Verifying installation by openssl for $crt in $cert_root ...\n# Export the matching certificate(s) in PEM directly (security find-certificate -p)\ntmpcert=$(mktemp /tmp/mycert.XXXXXX.pem)\n# Use sudo + tee so the redirected file is written with appropriate permissions\nsudo security find-certificate -a -c \"threemammals\" -p \"$cert_root\" | sudo tee \"$tmpcert\" >/dev/null\nif [ ! -s \"$tmpcert\" ]; then\n echo \"Failed to export certificate to $tmpcert\"\n rm -f \"$tmpcert\"\n exit 1\nfi\nchmod 644 \"$tmpcert\"\nopenssl x509 -in \"$tmpcert\" -text -noout\nrm -f \"$tmpcert\"\necho Installation is DONE\n"
},
{
"path": ".github/steps/prepare-coveralls.sh",
"content": "#!/bin/bash\n# Prepare Coveralls\necho \"::group::Listing environment variables\"\nenv | sort\necho \"::endgroup::\"\n\necho ------------ Detect coverage file ------------ \ncoverage_1st_folder=$(ls -d /home/runner/work/Ocelot/Ocelot/artifacts/UnitTests/*/ | head -1)\necho \"Detected first folder : $coverage_1st_folder\"\ncoverage_file=\"${coverage_1st_folder%/}/coverage.cobertura.xml\"\necho \"Detecting file $coverage_file ...\"\nif [ -f \"$coverage_file\" ]; then\n echo \"Coverage file exists.\"\n echo \"COVERALLS_coverage_file_exists=true\" >> $GITHUB_ENV\n echo \"COVERALLS_coverage_file=$coverage_file\" >> $GITHUB_ENV\nelse\n echo \"Coverage file DOES NOT exist!\"\n echo \"COVERALLS_coverage_file_exists=false\" >> $GITHUB_ENV\nfi\n"
},
{
"path": ".github/steps/ubuntu.add-dns-records.sh",
"content": "#!/bin/bash\nhosts=\"/etc/hosts\"\nif [ ! -f \"$hosts\" ]; then\n echo \"$hosts not found.\"\n exit 1\nfi\n\nsudo sed -i '$a 127.0.0.1 threemammals.com' $hosts\n\necho DNS-record added to $hosts\necho ------------------------\ncat $hosts\necho ------------------------\n\nping -c 3 threemammals.com\n"
},
{
"path": ".github/steps/ubuntu.install-certificate.sh",
"content": "#!/bin/bash\n# Install mycert2.crt certificate\ncrt='./test/Ocelot.AcceptanceTests/mycert2.crt'\nif [ -f \"$crt\" ]; then\n echo mycert2.crt file found\nfi\n\nopenssl version\n\n# Copy the certificate to the system's trusted CA directory\necho Moving the certificate to the trusted CA store...\ncert='/usr/local/share/ca-certificates/mycert2.crt'\nsudo cp $crt $cert\n\necho Updating the trusted certificates...\nsudo update-ca-certificates # This will add mycert.crt to the trusted root storage\n\necho Verifying installation by listing in /etc/ssl/certs/ folder...\nsudo ls /etc/ssl/certs/ | grep mycert\n\necho Verifying installation by openssl for $cert file...\nsudo chmod 644 $cert # adjusting the permissions\nls -l $cert # verify ownership\nopenssl x509 -in $cert -text -noout\n\necho Installation is DONE\n"
},
{
"path": ".github/steps/windows.add-dns-records.ps1",
"content": "# Add DNS-records\nWrite-Host \"Hello from PowerShell\"\nGet-Date\n \n# Append entry to hosts file\nAdd-Content -Path \"$env:SystemRoot\\System32\\drivers\\etc\\hosts\" -Value \"127.0.0.1 threemammals.com\"\n\nWrite-Output \"------------------------\"\nGet-Content \"$env:SystemRoot\\System32\\drivers\\etc\\hosts\"\nWrite-Output \"------------------------\"\n\n# Ping 3 times\nTest-Connection -ComputerName \"threemammals.com\" -Count 3\n"
},
{
"path": ".github/steps/windows.install-certificate.ps1",
"content": "Write-Host \"Hello from PowerShell\"\nGet-Date\n\n# Install mycert2.crt certificate\n$crt = \".\\test\\Ocelot.AcceptanceTests\\mycert2.crt\"\nif (Test-Path $crt) {\n Write-Output \"mycert2.crt file found\"\n}\n\nopenssl version\n\nWrite-Output \"Moving the certificate to the trusted CA store...\"\n# Import into the Local Machine Trusted Root Certification Authorities store\n$crt = \".\\test\\Ocelot.AcceptanceTests\\mycert2.crt\"\nImport-Certificate -FilePath $crt -CertStoreLocation Cert:\\LocalMachine\\Root\n\nWrite-Output \"Verifying installation by listing trusted root certificates...\"\n# List certificates in the Trusted Root store and filter for 'mycert'\nGet-ChildItem -Path Cert:\\LocalMachine\\Root | Where-Object { $_.Subject -like \"*threemammals*\" }\n\nWrite-Output \"Verifying installation by openssl for $crt file...\"\n$cert = Get-ChildItem Cert:\\LocalMachine\\Root | Where-Object { $_.Subject -like \"*threemammals*\" }\n$cert_file = \"C:\\temp\\mycert2_installed.cer\"\nExport-Certificate -Cert $cert -FilePath $cert_file\nif (Test-Path $cert_file) {\n Write-Output \"$cert_file file found\"\n}\n\n# Display certificate details using OpenSSL (if installed)\nopenssl x509 -in $cert_file -text -noout\n\nWrite-Output \"Installation is DONE\"\n"
},
{
"path": ".github/workflows/develop.yml",
"content": "name: Develop\non:\n push:\n branches:\n - develop\n # - 'release/**' # for testing purposes\njobs:\n build-windows:\n runs-on: windows-latest\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: Setup .NET 10\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: 10.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: .NET Info\n run: dotnet --info\n - name: Add DNS-records\n run: ./.github/steps/windows.add-dns-records.ps1\n - name: Install certificate\n run: ./.github/steps/windows.install-certificate.ps1\n - name: Restore\n run: dotnet restore --locked-mode ./Ocelot.slnx\n - name: Build\n run: dotnet build --no-restore ./Ocelot.slnx --framework net10.0\n - name: Unit Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n - name: Acceptance Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n build-macos:\n needs: build-windows\n runs-on: macos-latest\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: SH-scripts executable\n run: |\n chmod +x .github/steps/*.sh\n ls -l .github/steps/*.sh\n - name: Setup .NET 10\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: 10.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: .NET Info\n run: dotnet --info\n - name: Add DNS-records\n run: ./.github/steps/macos.add-dns-records.sh\n - name: Install certificate\n run: ./.github/steps/macos.install-certificate.sh\n - name: Restore\n run: dotnet restore --locked-mode ./Ocelot.slnx\n - name: Build\n run: dotnet build --no-restore ./Ocelot.slnx --framework net10.0\n - name: Unit Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n - name: Acceptance Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n build-linux:\n needs: build-macos\n strategy:\n matrix:\n dotnet-version: [ '8', '9', '10' ]\n runs-on: ubuntu-latest\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: SH-scripts executable\n run: |\n chmod +x .github/steps/*.sh\n ls -l .github/steps/*.sh\n - name: Check .NET ${{ matrix.dotnet-version }}\n id: check-dotnet\n run: ./.github/steps/check-dotnet.sh ${{ matrix.dotnet-version }}\n - name: Setup .NET ${{ matrix.dotnet-version }}\n # if: env.DOTNET${{ matrix.dotnet-version }}_installed == 'false'\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: ${{ matrix.dotnet-version }}.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: .NET Info\n run: dotnet --info\n - name: Add DNS-records\n run: ./.github/steps/ubuntu.add-dns-records.sh \n - name: Install certificate\n run: ./.github/steps/ubuntu.install-certificate.sh\n - name: Restore\n run: dotnet restore --locked-mode ./Ocelot.slnx\n - name: Build\n run: dotnet build --no-restore ./Ocelot.slnx --framework net${{ matrix.dotnet-version }}.0\n - name: Unit Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n - name: Acceptance Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n build-cake:\n needs: build-linux\n runs-on: ubuntu-latest\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n with:\n fetch-depth: 0\n - name: SH-scripts executable\n run: chmod +x .github/steps/*.sh\n - name: Setup .NET 10\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: 10.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: Cake Build\n uses: cake-build/cake-action@v3\n with:\n target: UnitTests # LatestFramework\n - name: Coverage files\n run: ./.github/steps/prepare-coveralls.sh\n - name: Coveralls\n if: env.COVERALLS_coverage_file_exists == 'true'\n uses: coverallsapp/github-action@v2\n with:\n # fail-on-error: false\n file: ${{ env.COVERALLS_coverage_file }}\n continue-on-error: true\n - name: Codecov\n if: env.COVERALLS_coverage_file_exists == 'true'\n uses: codecov/codecov-action@v5\n with:\n token: ${{ secrets.CODECOV_TOKEN }}\n slug: ThreeMammals/Ocelot\n fail_ci_if_error: true\n files: ${{ env.COVERALLS_coverage_file }}\n flags: unittests\n continue-on-error: true\n"
},
{
"path": ".github/workflows/pr-closed.yml",
"content": "name: PR Closed\non:\n pull_request:\n types: [closed]\n\njobs:\n cleanup:\n runs-on: ubuntu-latest\n env:\n GH_TOKEN: ${{ github.token }}\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: Delete caches via gh CLI\n run: |\n pr_no=\"${{ github.event.pull_request.number }}\"\n echo Pull request $pr_no cache items to be deleted...\n gh cache list --ref refs/pull/$pr_no/merge \n echo --------------------------------------\n echo All cache items...\n gh cache list\n echo --------------------------------------\n # gh cache list --ref refs/pull/$pr_no/merge --json id --jq '.[].id' | xargs -n1 gh cache delete\n # Sometimes, items produced by other workflows get reused in the PR workflow\n # gh cache delete --all --succeed-on-no-caches\n echo \"PR $pr_no: deleting caches for refs/pull/$pr_no/merge...\"\n ids=$(gh cache list --ref refs/pull/$pr_no/merge --json id --jq '.[].id')\n if [ -z \"$ids\" ]; then\n echo \"No PR caches found.\"\n else\n echo \"$ids\" | xargs -r -I{} sh -c 'gh cache delete {} || echo \"delete {} failed (ignored)\"'\n fi\n echo DONE\n continue-on-error: true\n"
},
{
"path": ".github/workflows/pr.yml",
"content": "# This workflow will build a .NET project\n# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-net\nname: PR\non: pull_request\n\njobs:\n# build-linux:\n# runs-on: ubuntu-latest\n# continue-on-error: true\n# env:\n# # https://github.com/actions/setup-dotnet/blob/main/README.md#environment-variables\n# DOTNET_INSTALL_DIR: \"/usr/share/dotnet\" # don't override by /usr/lib/dotnet \n# NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n# steps:\n# - name: Checkout\n# uses: actions/checkout@v5\n# - name: SH-scripts executable\n# run: |\n# chmod +x .github/steps/*.sh\n# ls -l .github/steps/*.sh\n# - name: Check .NET 10\n# id: check-dotnet10\n# run: ./.github/steps/check-dotnet.sh 10\n# - name: Setup .NET 10\n# # if: env.DOTNET10_installed == 'false'\n# uses: actions/setup-dotnet@v5\n# with:\n# dotnet-version: 10.x\n# cache: true\n# cache-dependency-path: |\n# samples/**/packages.lock.json\n# src/**/packages.lock.json\n# test/**/packages.lock.json\n# - name: .NET Info\n# run: dotnet --info\n# - name: Add DNS-records\n# run: ./.github/steps/ubuntu.add-dns-records.sh \n# - name: Install certificate\n# run: ./.github/steps/ubuntu.install-certificate.sh\n# - name: Restore\n# run: dotnet restore --locked-mode ./Ocelot.slnx\n# - name: Build\n# run: dotnet build --no-restore ./Ocelot.slnx --framework net10.0\n# - name: Unit Tests\n# run: dotnet test --no-restore --no-build --verbosity normal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n# - name: Acceptance Tests\n# run: dotnet test --no-restore --no-build --verbosity normal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n# build-macos:\n# runs-on: macos-latest\n# continue-on-error: true\n# env:\n# NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n# steps:\n# - name: Checkout\n# uses: actions/checkout@v5\n# - name: SH-scripts executable\n# run: |\n# chmod +x .github/steps/*.sh\n# ls -l .github/steps/*.sh\n# - name: Setup .NET 10\n# uses: actions/setup-dotnet@v5\n# with:\n# dotnet-version: 10.x\n# cache: true\n# cache-dependency-path: |\n# samples/**/packages.lock.json\n# src/**/packages.lock.json\n# test/**/packages.lock.json\n# - name: .NET Info\n# run: dotnet --info\n# - name: Add DNS-records\n# run: ./.github/steps/macos.add-dns-records.sh \n# - name: Install certificate\n# run: ./.github/steps/macos.install-certificate.sh\n# - name: Restore\n# run: dotnet restore --locked-mode ./Ocelot.slnx\n# - name: Build\n# run: dotnet build --no-restore ./Ocelot.slnx --framework net10.0\n# - name: Unit Tests\n# run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n# - name: Acceptance Tests\n# run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n# build-windows:\n# runs-on: windows-latest\n# continue-on-error: true\n# env:\n# NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n# steps:\n# - name: Checkout\n# uses: actions/checkout@v5\n# - name: Setup .NET 10\n# uses: actions/setup-dotnet@v5\n# with:\n# dotnet-version: 10.x\n# cache: true\n# cache-dependency-path: |\n# samples/**/packages.lock.json\n# src/**/packages.lock.json\n# test/**/packages.lock.json\n# - name: .NET Info\n# run: dotnet --info\n# - name: Add DNS-records\n# run: ./.github/steps/windows.add-dns-records.ps1 \n# - name: Install certificate\n# run: ./.github/steps/windows.install-certificate.ps1\n# - name: Restore\n# run: dotnet restore --locked-mode ./Ocelot.slnx\n# - name: Build\n# run: dotnet build --no-restore ./Ocelot.slnx --framework net10.0\n# - name: Unit Tests\n# run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n# - name: Acceptance Tests\n# run: dotnet test --no-restore --no-build --verbosity minimal --framework net10.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n# build-success:\n# needs: [build-linux, build-macos, build-windows]\n# runs-on: ubuntu-latest\n# if: ${{ always() }} # run even Linux / MacOS / Windows build fails\n# steps:\n# - name: Decide success\n# run: |\n# linux_result=\"${{ needs.build-linux.result }}\"\n# macos_result=\"${{ needs.build-macos.result }}\"\n# windows_result=\"${{ needs.build-windows.result }}\"\n# if [[ $linux_result == \"success\" || $macos_result == \"success\" || $windows_result == \"success\" ]]; then\n# echo \"At least one succeeded\"\n# else\n# echo \"All failed\"\n# exit 1\n# fi\n\n build-cake:\n runs-on: ubuntu-latest\n # environment: Pull-Request\n env:\n # COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n with:\n fetch-depth: 0\n - name: SH-scripts executable\n run: |\n chmod +x .github/steps/*.sh\n ls -l .github/steps/*.sh\n - name: Check .NET 10\n id: check-dotnet10\n run: ./.github/steps/check-dotnet.sh 10\n - name: Setup .NET 10\n # if: env.DOTNET10_installed == 'false'\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: 10.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: .NET Info\n run: dotnet --info\n - name: Add DNS-records\n run: ./.github/steps/ubuntu.add-dns-records.sh \n - name: Install certificate\n run: ./.github/steps/ubuntu.install-certificate.sh\n - name: Cake Build\n uses: cake-build/cake-action@v3\n with:\n target: PullRequest\n verbosity: Verbose\n - name: Coverage files\n run: ./.github/steps/prepare-coveralls.sh\n - name: Coveralls\n if: env.COVERALLS_coverage_file_exists == 'true'\n uses: coverallsapp/github-action@v2\n with:\n # fail-on-error: false\n file: ${{ env.COVERALLS_coverage_file }}\n continue-on-error: true\n - name: Codecov\n if: env.COVERALLS_coverage_file_exists == 'true'\n uses: codecov/codecov-action@v5\n with:\n token: ${{ secrets.CODECOV_TOKEN }}\n slug: ThreeMammals/Ocelot\n fail_ci_if_error: true\n files: ${{ env.COVERALLS_coverage_file }}\n flags: unittests\n continue-on-error: true\n"
},
{
"path": ".github/workflows/release.yml",
"content": "name: Release\non:\n push:\n branches:\n - main\n - 'release/24.**'\njobs:\n build-windows:\n strategy:\n matrix:\n dotnet-version: [ '8', '9', '10' ]\n runs-on: windows-latest\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: Setup .NET ${{ matrix.dotnet-version }}\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: ${{ matrix.dotnet-version }}.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: .NET Info\n run: dotnet --info\n - name: Add DNS-records\n run: ./.github/steps/windows.add-dns-records.ps1\n - name: Install certificate\n run: ./.github/steps/windows.install-certificate.ps1\n - name: Restore\n run: dotnet restore --locked-mode ./Ocelot.Release.sln\n - name: Build\n run: dotnet build --no-restore ./Ocelot.Release.sln --framework net${{ matrix.dotnet-version }}.0\n - name: Unit Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n - name: Acceptance Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n build-macos:\n needs: build-windows\n strategy:\n matrix:\n dotnet-version: [ '8', '9', '10' ]\n runs-on: macos-latest\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: SH-scripts executable\n run: |\n chmod +x .github/steps/*.sh\n ls -l .github/steps/*.sh\n - name: Setup .NET ${{ matrix.dotnet-version }}\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: ${{ matrix.dotnet-version }}.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: .NET Info\n run: dotnet --info\n - name: Add DNS-records\n run: ./.github/steps/macos.add-dns-records.sh\n - name: Install certificate\n run: ./.github/steps/macos.install-certificate.sh\n - name: Restore\n run: dotnet restore --locked-mode ./Ocelot.Release.sln\n - name: Build\n run: dotnet build --no-restore ./Ocelot.Release.sln --framework net${{ matrix.dotnet-version }}.0\n - name: Unit Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n - name: Acceptance Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n build-linux:\n needs: build-macos\n strategy:\n matrix:\n dotnet-version: [ '8', '9', '10' ]\n runs-on: ubuntu-latest\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Checkout\n uses: actions/checkout@v5\n - name: SH-scripts executable\n run: |\n chmod +x .github/steps/*.sh\n ls -l .github/steps/*.sh\n - name: Check .NET ${{ matrix.dotnet-version }}\n id: check-dotnet\n run: ./.github/steps/check-dotnet.sh ${{ matrix.dotnet-version }}\n - name: Setup .NET ${{ matrix.dotnet-version }}\n # if: env.DOTNET${{ matrix.dotnet-version }}_installed == 'false'\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: ${{ matrix.dotnet-version }}.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: .NET Info\n run: dotnet --info\n - name: Add DNS-records\n run: ./.github/steps/ubuntu.add-dns-records.sh \n - name: Install certificate\n run: ./.github/steps/ubuntu.install-certificate.sh\n - name: Restore\n run: dotnet restore --locked-mode ./Ocelot.Release.sln\n - name: Build\n run: dotnet build --no-restore ./Ocelot.Release.sln --framework net${{ matrix.dotnet-version }}.0\n - name: Unit Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\n - name: Acceptance Tests\n run: dotnet test --no-restore --no-build --verbosity minimal --framework net${{ matrix.dotnet-version }}.0 --settings coverlet.runsettings ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\n\n release-cake:\n needs: build-linux\n runs-on: ubuntu-latest\n environment: build.cake # TODO Rename to Release\n env:\n NUGET_PACKAGES: ${{ github.workspace }}/.nuget/packages\n steps:\n - name: Env Variables\n env:\n # CAKE_RELEASE_MYVAR: ${{ vars.CAKE_RELEASE_MYVAR }}\n # TEMP_KEY: ${{ secrets.TEMP_KEY }} # leaked secret LoL\n GITHUB_CONTEXT: ${{ toJson(github) }}\n run: |\n echo \"github context >>>\" # https://docs.github.com/en/actions/writing-workflows/choosing-what-your-workflow-does/accessing-contextual-information-about-workflow-runs#github-context\n echo \"$GITHUB_CONTEXT\"\n echo \"<<<\"\n - name: Checkout\n uses: actions/checkout@v5\n with:\n fetch-depth: 0\n - name: SH-scripts executable\n run: |\n chmod +x .github/steps/*.sh\n ls -l .github/steps/*.sh\n - name: Check .NET 10\n id: check-dotnet\n run: ./.github/steps/check-dotnet.sh 10\n - name: Setup .NET 10\n uses: actions/setup-dotnet@v5\n with:\n dotnet-version: 10.x\n cache: true\n cache-dependency-path: |\n samples/**/packages.lock.json\n src/**/packages.lock.json\n test/**/packages.lock.json\n - name: Cake Build\n uses: cake-build/cake-action@v3\n with:\n target: Release\n env:\n OCELOT_GITHUB_API_KEY: ${{ secrets.OCELOT_GITHUB_API_KEY }}\n OCELOT_NUGET_API_KEY_2025: ${{ secrets.OCELOT_NUGET_API_KEY_2025 }}\n # COVERALLS_REPO_TOKEN: ${{ secrets.COVERALLS_REPO_TOKEN }}\n - name: Coverage files\n run: ./.github/steps/prepare-coveralls.sh\n - name: Coveralls\n if: env.COVERALLS_coverage_file_exists == 'true'\n uses: coverallsapp/github-action@v2\n with:\n file: ${{ env.COVERALLS_coverage_file }}\n compare-ref: main\n continue-on-error: true\n - name: Codecov\n if: env.COVERALLS_coverage_file_exists == 'true'\n uses: codecov/codecov-action@v5\n with:\n token: ${{ secrets.CODECOV_TOKEN }}\n slug: ThreeMammals/Ocelot\n fail_ci_if_error: true\n files: ${{ env.COVERALLS_coverage_file }}\n flags: unittests\n continue-on-error: true\n"
},
{
"path": ".gitignore",
"content": "## Ignore Visual Studio temporary files, build results, and\r\n## files generated by popular Visual Studio add-ons.\r\n##\r\n## Get latest from https://github.com/github/gitignore/blob/main/VisualStudio.gitignore\r\n\r\n# User-specific files\r\n*.rsuser\r\n*.suo\r\n*.user\r\n*.userosscache\r\n*.sln.docstates\r\n\r\n# User-specific files (MonoDevelop/Xamarin Studio)\r\n*.userprefs\r\n\r\n# Mono auto generated files\r\nmono_crash.*\r\n\r\n# Build results\r\n[Dd]ebug/\r\n[Dd]ebugPublic/\r\n[Rr]elease/\r\n[Rr]eleases/\r\nx64/\r\nx86/\r\n[Ww][Ii][Nn]32/\r\n[Aa][Rr][Mm]/\r\n[Aa][Rr][Mm]64/\r\nbld/\r\n[Bb]in/\r\n[Oo]bj/\r\n[Ll]og/\r\n[Ll]ogs/\r\n\r\n# Visual Studio 2015/2017 cache/options directory\r\n.vs/\r\n# Uncomment if you have tasks that create the project's static files in wwwroot\r\n#wwwroot/\r\n\r\n# Visual Studio 2017 auto generated files\r\nGenerated\\ Files/\r\n\r\n# MSTest test Results\r\n[Tt]est[Rr]esult*/\r\n[Bb]uild[Ll]og.*\r\n\r\n# NUnit\r\n*.VisualState.xml\r\nTestResult.xml\r\nnunit-*.xml\r\n\r\n# Build Results of an ATL Project\r\n[Dd]ebugPS/\r\n[Rr]eleasePS/\r\ndlldata.c\r\n\r\n# Benchmark Results\r\nBenchmarkDotNet.Artifacts/\r\n\r\n# .NET Core\r\nproject.lock.json\r\nproject.fragment.lock.json\r\nartifacts/\r\n\r\n# ASP.NET Scaffolding\r\nScaffoldingReadMe.txt\r\n\r\n# StyleCop\r\nStyleCopReport.xml\r\n\r\n# Files built by Visual Studio\r\n*_i.c\r\n*_p.c\r\n*_h.h\r\n*.ilk\r\n*.meta\r\n*.obj\r\n*.iobj\r\n*.pch\r\n*.pdb\r\n*.ipdb\r\n*.pgc\r\n*.pgd\r\n*.rsp\r\n*.sbr\r\n*.tlb\r\n*.tli\r\n*.tlh\r\n*.tmp\r\n*.tmp_proj\r\n*_wpftmp.csproj\r\n*.log\r\n*.tlog\r\n*.vspscc\r\n*.vssscc\r\n.builds\r\n*.pidb\r\n*.svclog\r\n*.scc\r\n\r\n# Chutzpah Test files\r\n_Chutzpah*\r\n\r\n# Visual C++ cache files\r\nipch/\r\n*.aps\r\n*.ncb\r\n*.opendb\r\n*.opensdf\r\n*.sdf\r\n*.cachefile\r\n*.VC.db\r\n*.VC.VC.opendb\r\n\r\n# Visual Studio profiler\r\n*.psess\r\n*.vsp\r\n*.vspx\r\n*.sap\r\n\r\n# Visual Studio Trace Files\r\n*.e2e\r\n\r\n# TFS 2012 Local Workspace\r\n$tf/\r\n\r\n# Guidance Automation Toolkit\r\n*.gpState\r\n\r\n# ReSharper is a .NET coding add-in\r\n_ReSharper*/\r\n*.[Rr]e[Ss]harper\r\n*.DotSettings.user\r\n\r\n# TeamCity is a build add-in\r\n_TeamCity*\r\n\r\n# DotCover is a Code Coverage Tool\r\n*.dotCover\r\n\r\n# AxoCover is a Code Coverage Tool\r\n.axoCover/*\r\n!.axoCover/settings.json\r\n\r\n# Coverlet is a free, cross platform Code Coverage Tool\r\ncoverage*.json\r\ncoverage*.xml\r\ncoverage*.info\r\n\r\n# Visual Studio code coverage results\r\n*.coverage\r\n*.coveragexml\r\n\r\n# NCrunch\r\n_NCrunch_*\r\n.*crunch*.local.xml\r\nnCrunchTemp_*\r\n\r\n# MightyMoose\r\n*.mm.*\r\nAutoTest.Net/\r\n\r\n# Web workbench (sass)\r\n.sass-cache/\r\n\r\n# Installshield output folder\r\n[Ee]xpress/\r\n\r\n# DocProject is a documentation generator add-in\r\nDocProject/buildhelp/\r\nDocProject/Help/*.HxT\r\nDocProject/Help/*.HxC\r\nDocProject/Help/*.hhc\r\nDocProject/Help/*.hhk\r\nDocProject/Help/*.hhp\r\nDocProject/Help/Html2\r\nDocProject/Help/html\r\n\r\n# Click-Once directory\r\npublish/\r\n\r\n# Publish Web Output\r\n*.[Pp]ublish.xml\r\n*.azurePubxml\r\n# Note: Comment the next line if you want to checkin your web deploy settings,\r\n# but database connection strings (with potential passwords) will be unencrypted\r\n*.pubxml\r\n*.publishproj\r\n\r\n# Microsoft Azure Web App publish settings. Comment the next line if you want to\r\n# checkin your Azure Web App publish settings, but sensitive information contained\r\n# in these scripts will be unencrypted\r\nPublishScripts/\r\n\r\n# NuGet Packages\r\n*.nupkg\r\n# NuGet Symbol Packages\r\n*.snupkg\r\n# The packages folder can be ignored because of Package Restore\r\n**/[Pp]ackages/*\r\n# except build/, which is used as an MSBuild target.\r\n!**/[Pp]ackages/build/\r\n# Uncomment if necessary however generally it will be regenerated when needed\r\n#!**/[Pp]ackages/repositories.config\r\n# NuGet v3's project.json files produces more ignorable files\r\n*.nuget.props\r\n*.nuget.targets\r\n\r\n# Microsoft Azure Build Output\r\ncsx/\r\n*.build.csdef\r\n\r\n# Microsoft Azure Emulator\r\necf/\r\nrcf/\r\n\r\n# Windows Store app package directories and files\r\nAppPackages/\r\nBundleArtifacts/\r\nPackage.StoreAssociation.xml\r\n_pkginfo.txt\r\n*.appx\r\n*.appxbundle\r\n*.appxupload\r\n\r\n# Visual Studio cache files\r\n# files ending in .cache can be ignored\r\n*.[Cc]ache\r\n# but keep track of directories ending in .cache\r\n!?*.[Cc]ache/\r\n\r\n# Others\r\nClientBin/\r\n~$*\r\n*~\r\n*.dbmdl\r\n*.dbproj.schemaview\r\n*.jfm\r\n*.pfx\r\n*.publishsettings\r\norleans.codegen.cs\r\n\r\n# Including strong name files can present a security risk\r\n# (https://github.com/github/gitignore/pull/2483#issue-259490424)\r\n#*.snk\r\n\r\n# Since there are multiple workflows, uncomment next line to ignore bower_components\r\n# (https://github.com/github/gitignore/pull/1529#issuecomment-104372622)\r\n#bower_components/\r\n\r\n# RIA/Silverlight projects\r\nGenerated_Code/\r\n\r\n# Backup & report files from converting an old project file\r\n# to a newer Visual Studio version. Backup files are not needed,\r\n# because we have git ;-)\r\n_UpgradeReport_Files/\r\nBackup*/\r\nUpgradeLog*.XML\r\nUpgradeLog*.htm\r\nServiceFabricBackup/\r\n*.rptproj.bak\r\n\r\n# SQL Server files\r\n*.mdf\r\n*.ldf\r\n*.ndf\r\n\r\n# Business Intelligence projects\r\n*.rdl.data\r\n*.bim.layout\r\n*.bim_*.settings\r\n*.rptproj.rsuser\r\n*- [Bb]ackup.rdl\r\n*- [Bb]ackup ([0-9]).rdl\r\n*- [Bb]ackup ([0-9][0-9]).rdl\r\n\r\n# Microsoft Fakes\r\nFakesAssemblies/\r\n\r\n# GhostDoc plugin setting file\r\n*.GhostDoc.xml\r\n\r\n# Node.js Tools for Visual Studio\r\n.ntvs_analysis.dat\r\nnode_modules/\r\n\r\n# Visual Studio 6 build log\r\n*.plg\r\n\r\n# Visual Studio 6 workspace options file\r\n*.opt\r\n\r\n# Visual Studio 6 auto-generated workspace file (contains which files were open etc.)\r\n*.vbw\r\n\r\n# Visual Studio 6 auto-generated project file (contains which files were open etc.)\r\n*.vbp\r\n\r\n# Visual Studio 6 workspace and project file (working project files containing files to include in project)\r\n*.dsw\r\n*.dsp\r\n\r\n# Visual Studio 6 technical files\r\n*.ncb\r\n*.aps\r\n\r\n# Visual Studio LightSwitch build output\r\n**/*.HTMLClient/GeneratedArtifacts\r\n**/*.DesktopClient/GeneratedArtifacts\r\n**/*.DesktopClient/ModelManifest.xml\r\n**/*.Server/GeneratedArtifacts\r\n**/*.Server/ModelManifest.xml\r\n_Pvt_Extensions\r\n\r\n# Paket dependency manager\r\n.paket/paket.exe\r\npaket-files/\r\n\r\n# FAKE - F# Make\r\n.fake/\r\n\r\n# CodeRush personal settings\r\n.cr/personal\r\n\r\n# Python Tools for Visual Studio (PTVS)\r\n__pycache__/\r\n*.pyc\r\n\r\n# Cake - Uncomment if you are using it\r\n# tools/**\r\n# !tools/packages.config\r\n\r\n# Tabs Studio\r\n*.tss\r\n\r\n# Telerik's JustMock configuration file\r\n*.jmconfig\r\n\r\n# BizTalk build output\r\n*.btp.cs\r\n*.btm.cs\r\n*.odx.cs\r\n*.xsd.cs\r\n\r\n# OpenCover UI analysis results\r\nOpenCover/\r\n\r\n# Azure Stream Analytics local run output\r\nASALocalRun/\r\n\r\n# MSBuild Binary and Structured Log\r\n*.binlog\r\n\r\n# NVidia Nsight GPU debugger configuration file\r\n*.nvuser\r\n\r\n# MFractors (Xamarin productivity tool) working folder\r\n.mfractor/\r\n\r\n# Local History for Visual Studio\r\n.localhistory/\r\n\r\n# Visual Studio History (VSHistory) files\r\n.vshistory/\r\n\r\n# BeatPulse healthcheck temp database\r\nhealthchecksdb\r\n\r\n# Backup folder for Package Reference Convert tool in Visual Studio 2017\r\nMigrationBackup/\r\n\r\n# Ionide (cross platform F# VS Code tools) working folder\r\n.ionide/\r\n\r\n# Fody - auto-generated XML schema\r\nFodyWeavers.xsd\r\n\r\n# VS Code files for those working on multiple tools\r\n.vscode/*\r\n!.vscode/settings.json\r\n!.vscode/tasks.json\r\n!.vscode/launch.json\r\n!.vscode/extensions.json\r\n*.code-workspace\r\n\r\n# Local History for Visual Studio Code\r\n.history/\r\n\r\n# Windows Installer files from build outputs\r\n*.cab\r\n*.msi\r\n*.msix\r\n*.msm\r\n*.msp\r\n\r\n# JetBrains Rider\r\n*.sln.iml\r\n.idea/\r\n\r\n# Visual Studio Test Results\r\n# Quick Facts: https://file.org/extension/trx#visualstudiotestresults\r\n# Running automated tests from the command line: https://learn.microsoft.com/en-us/previous-versions/ms182486(v=vs.140)\r\n# Run unit tests with Test Explorer: https://learn.microsoft.com/en-us/visualstudio/test/run-unit-tests-with-test-explorer\r\n*.trx\r\n\r\n# OCELOT\r\n\r\n# FAKE - F# Make\r\n.fake/\r\n!tools/packages.config\r\ntools/\r\n\r\n# ReportGenerator dotnet tool -> https://reportgenerator.io/\r\n**/coveragereport/\r\n\r\n# Ocelot acceptance test config\r\ntest/Ocelot.AcceptanceTests/ocelot.json\r\n\r\n# Read the Docs -> https://ocelot.readthedocs.io\r\ndocs/_build/\r\ndocs/_templates/\r\n"
},
{
"path": ".readthedocs.yaml",
"content": "# .readthedocs.yaml\n# Read the Docs configuration file\n# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details\n\n# Required\nversion: 2\n\n# Set the OS, Python version and other tools you might need\nbuild:\n os: ubuntu-24.04\n tools:\n python: \"latest\"\n # You can also specify other tool versions:\n # nodejs: \"19\"\n # rust: \"1.64\"\n # golang: \"1.19\"\n\n# Build documentation in the \"docs/\" directory with Sphinx\nsphinx:\n configuration: docs/conf.py\n\n# Optionally build your docs in additional formats such as PDF and ePub\nformats:\n - pdf\n - epub\n\n# Optional but recommended, declare the Python requirements required to build your documentation\n# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html\npython:\n install:\n - requirements: docs/requirements.txt\n"
},
{
"path": "GitVersion.yml",
"content": "mode: ContinuousDelivery\r\nbranches: {}\r\nignore:\r\n sha: []\r\n"
},
{
"path": "LICENSE.md",
"content": "The MIT License (MIT), Open Source Software,\r\nCopyright © 2016-2026 Tom Gardham-Pallister, Raman Maksimchuk and contributors.\r\n\r\nPermission is hereby granted, free of charge, to any person obtaining a copy of this open-source software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:\r\n\r\nThe above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.\r\n\r\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\r\n"
},
{
"path": "Ocelot.Samples.sln",
"content": "\nMicrosoft Visual Studio Solution File, Format Version 12.00\n# Visual Studio Version 18\nVisualStudioVersion = 18.3.11520.95 d18.3\nMinimumVisualStudioVersion = 10.0.40219.1\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot\", \"src\\Ocelot\\Ocelot.csproj\", \"{B37314F1-C1B5-4D38-8000-E6E96C0CBD30}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.Eureka.ApiGateway\", \"samples\\Eureka\\ApiGateway\\Ocelot.Samples.Eureka.ApiGateway.csproj\", \"{EA0E146F-2C2B-4176-B6EC-F62A587F5077}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.Eureka.DownstreamService\", \"samples\\Eureka\\DownstreamService\\Ocelot.Samples.Eureka.DownstreamService.csproj\", \"{B7317B64-2208-472D-90AC-F42B61956B79}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.GraphQL\", \"samples\\GraphQL\\Ocelot.Samples.GraphQL.csproj\", \"{6CCA3677-420A-4294-8D41-67CF3D818575}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.Kubernetes.ApiGateway\", \"samples\\Kubernetes\\ApiGateway\\Ocelot.Samples.Kubernetes.ApiGateway.csproj\", \"{721C1737-70CB-4B11-A19B-C7AAC6856CC7}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.Kubernetes.DownstreamService\", \"samples\\Kubernetes\\DownstreamService\\Ocelot.Samples.Kubernetes.DownstreamService.csproj\", \"{CE949A5D-9D25-46E3-B59A-DA63F7ED9A59}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.ServiceDiscovery.ApiGateway\", \"samples\\ServiceDiscovery\\ApiGateway\\Ocelot.Samples.ServiceDiscovery.ApiGateway.csproj\", \"{96B9F16E-C95D-425A-A419-40CB3C90CB77}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.ServiceDiscovery.DownstreamService\", \"samples\\ServiceDiscovery\\DownstreamService\\Ocelot.Samples.ServiceDiscovery.DownstreamService.csproj\", \"{60E14B1A-C295-453B-910E-58E09F5A28AA}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.ServiceFabric.ApiGateway\", \"samples\\ServiceFabric\\ApiGateway\\Ocelot.Samples.ServiceFabric.ApiGateway.csproj\", \"{115F7934-3326-492A-B131-64F0EAEBAD71}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.ServiceFabric.DownstreamService\", \"samples\\ServiceFabric\\DownstreamService\\Ocelot.Samples.ServiceFabric.DownstreamService.csproj\", \"{6C777A20-F557-45CF-B87B-11E3C6B29A36}\"\nEndProject\nProject(\"{9A19103F-16F7-4668-BE54-9A1E7A4F7556}\") = \"Ocelot.Samples.Web\", \"samples\\Web\\Ocelot.Samples.Web.csproj\", \"{EA553F5C-4B94-4E4A-8C3E-0124C5EA5F6E}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Samples.Basic\", \"samples\\Basic\\Ocelot.Samples.Basic.csproj\", \"{3225BD01-42ED-4362-9757-28CBFF6B2D70}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Samples.Configuration\", \"samples\\Configuration\\Ocelot.Samples.Configuration.csproj\", \"{FE091795-7FBF-4D82-ABD6-51405F210142}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Samples.Metadata\", \"samples\\Metadata\\Ocelot.Samples.Metadata.csproj\", \"{80EE7EA9-BB02-4F2D-B7E3-BB6A42F50658}\"\nEndProject\nGlobal\n\tGlobalSection(SolutionConfigurationPlatforms) = preSolution\n\t\tDebug|Any CPU = Debug|Any CPU\n\t\tRelease|Any CPU = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(ProjectConfigurationPlatforms) = postSolution\n\t\t{B37314F1-C1B5-4D38-8000-E6E96C0CBD30}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{B37314F1-C1B5-4D38-8000-E6E96C0CBD30}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{B37314F1-C1B5-4D38-8000-E6E96C0CBD30}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{B37314F1-C1B5-4D38-8000-E6E96C0CBD30}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{EA0E146F-2C2B-4176-B6EC-F62A587F5077}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{EA0E146F-2C2B-4176-B6EC-F62A587F5077}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{EA0E146F-2C2B-4176-B6EC-F62A587F5077}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{EA0E146F-2C2B-4176-B6EC-F62A587F5077}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{B7317B64-2208-472D-90AC-F42B61956B79}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{B7317B64-2208-472D-90AC-F42B61956B79}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{B7317B64-2208-472D-90AC-F42B61956B79}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{B7317B64-2208-472D-90AC-F42B61956B79}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{6CCA3677-420A-4294-8D41-67CF3D818575}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{6CCA3677-420A-4294-8D41-67CF3D818575}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{6CCA3677-420A-4294-8D41-67CF3D818575}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{6CCA3677-420A-4294-8D41-67CF3D818575}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{721C1737-70CB-4B11-A19B-C7AAC6856CC7}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{721C1737-70CB-4B11-A19B-C7AAC6856CC7}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{721C1737-70CB-4B11-A19B-C7AAC6856CC7}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{721C1737-70CB-4B11-A19B-C7AAC6856CC7}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{CE949A5D-9D25-46E3-B59A-DA63F7ED9A59}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{CE949A5D-9D25-46E3-B59A-DA63F7ED9A59}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{CE949A5D-9D25-46E3-B59A-DA63F7ED9A59}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{CE949A5D-9D25-46E3-B59A-DA63F7ED9A59}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{96B9F16E-C95D-425A-A419-40CB3C90CB77}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{96B9F16E-C95D-425A-A419-40CB3C90CB77}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{96B9F16E-C95D-425A-A419-40CB3C90CB77}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{96B9F16E-C95D-425A-A419-40CB3C90CB77}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{60E14B1A-C295-453B-910E-58E09F5A28AA}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{60E14B1A-C295-453B-910E-58E09F5A28AA}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{60E14B1A-C295-453B-910E-58E09F5A28AA}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{60E14B1A-C295-453B-910E-58E09F5A28AA}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{115F7934-3326-492A-B131-64F0EAEBAD71}.Debug|Any CPU.ActiveCfg = Debug|x64\n\t\t{115F7934-3326-492A-B131-64F0EAEBAD71}.Debug|Any CPU.Build.0 = Debug|x64\n\t\t{115F7934-3326-492A-B131-64F0EAEBAD71}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{115F7934-3326-492A-B131-64F0EAEBAD71}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{6C777A20-F557-45CF-B87B-11E3C6B29A36}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{6C777A20-F557-45CF-B87B-11E3C6B29A36}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{6C777A20-F557-45CF-B87B-11E3C6B29A36}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{6C777A20-F557-45CF-B87B-11E3C6B29A36}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{EA553F5C-4B94-4E4A-8C3E-0124C5EA5F6E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{EA553F5C-4B94-4E4A-8C3E-0124C5EA5F6E}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{EA553F5C-4B94-4E4A-8C3E-0124C5EA5F6E}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{EA553F5C-4B94-4E4A-8C3E-0124C5EA5F6E}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{3225BD01-42ED-4362-9757-28CBFF6B2D70}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{3225BD01-42ED-4362-9757-28CBFF6B2D70}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{3225BD01-42ED-4362-9757-28CBFF6B2D70}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{3225BD01-42ED-4362-9757-28CBFF6B2D70}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{FE091795-7FBF-4D82-ABD6-51405F210142}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{FE091795-7FBF-4D82-ABD6-51405F210142}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{FE091795-7FBF-4D82-ABD6-51405F210142}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{FE091795-7FBF-4D82-ABD6-51405F210142}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{80EE7EA9-BB02-4F2D-B7E3-BB6A42F50658}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{80EE7EA9-BB02-4F2D-B7E3-BB6A42F50658}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{80EE7EA9-BB02-4F2D-B7E3-BB6A42F50658}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{80EE7EA9-BB02-4F2D-B7E3-BB6A42F50658}.Release|Any CPU.Build.0 = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(SolutionProperties) = preSolution\n\t\tHideSolutionNode = FALSE\n\tEndGlobalSection\n\tGlobalSection(ExtensibilityGlobals) = postSolution\n\t\tSolutionGuid = {2C1620D4-EB38-4C3E-9FC5-029FB6B2F426}\n\tEndGlobalSection\nEndGlobal\n"
},
{
"path": "Ocelot.Samples.slnx",
"content": "\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "Ocelot.sln",
"content": "\nMicrosoft Visual Studio Solution File, Format Version 12.00\n# Visual Studio Version 18\nVisualStudioVersion = 18.3.11520.95\nMinimumVisualStudioVersion = 10.0.40219.1\nProject(\"{2150E333-8FDC-42A3-9474-1A3956D46DE8}\") = \"Solution Items\", \"Solution Items\", \"{3FA7C349-DBE8-4904-A2CE-015B8869CE6C}\"\n\tProjectSection(SolutionItems) = preProject\n\t\t.dockerignore = .dockerignore\n\t\t.editorconfig = .editorconfig\n\t\t.gitignore = .gitignore\n\t\t.readthedocs.yaml = .readthedocs.yaml\n\t\tbuild.cake = build.cake\n\t\tcodeanalysis.ruleset = codeanalysis.ruleset\n\t\tGitVersion.yml = GitVersion.yml\n\t\tLICENSE.md = LICENSE.md\n\t\tREADME.md = README.md\n\t\tReleaseNotes.md = ReleaseNotes.md\n\tEndProjectSection\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Testing\", \"testing\\Ocelot.Testing.csproj\", \"{D9DF2863-0608-4BBC-8D83-614E2894AF49}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.AcceptanceTests\", \"test\\Ocelot.AcceptanceTests\\Ocelot.AcceptanceTests.csproj\", \"{AA97C983-5A39-D35D-0274-08247BB08FAC}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Benchmarks\", \"test\\Ocelot.Benchmarks\\Ocelot.Benchmarks.csproj\", \"{075F01AD-8478-3463-2BB9-D04EE5C98321}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.ManualTest\", \"test\\Ocelot.ManualTest\\Ocelot.ManualTest.csproj\", \"{DE9F1F3D-7687-9248-E4D8-5684370E185F}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.UnitTests\", \"test\\Ocelot.UnitTests\\Ocelot.UnitTests.csproj\", \"{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot\", \"src\\Ocelot\\Ocelot.csproj\", \"{AB0A194F-36A2-D62B-51FD-44335BE12D1B}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Provider.Consul\", \"src\\Ocelot.Provider.Consul\\Ocelot.Provider.Consul.csproj\", \"{F38B5372-D141-3A0D-6FF8-30EFA93C7506}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Provider.Eureka\", \"src\\Ocelot.Provider.Eureka\\Ocelot.Provider.Eureka.csproj\", \"{3C77D0A0-173A-628F-FA3C-E113B9501E89}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Provider.Kubernetes\", \"src\\Ocelot.Provider.Kubernetes\\Ocelot.Provider.Kubernetes.csproj\", \"{1FD9E0B6-EC08-54E4-82F2-A215A388968D}\"\nEndProject\nProject(\"{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}\") = \"Ocelot.Provider.Polly\", \"src\\Ocelot.Provider.Polly\\Ocelot.Provider.Polly.csproj\", \"{1424441E-1143-0F05-1346-E90195CDE10E}\"\nEndProject\nGlobal\n\tGlobalSection(SolutionConfigurationPlatforms) = preSolution\n\t\tDebug|Any CPU = Debug|Any CPU\n\t\tDebug|x64 = Debug|x64\n\t\tDebug|x86 = Debug|x86\n\t\tRelease|Any CPU = Release|Any CPU\n\t\tRelease|x64 = Release|x64\n\t\tRelease|x86 = Release|x86\n\tEndGlobalSection\n\tGlobalSection(ProjectConfigurationPlatforms) = postSolution\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Release|x64.Build.0 = Release|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{D9DF2863-0608-4BBC-8D83-614E2894AF49}.Release|x86.Build.0 = Release|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Release|x64.Build.0 = Release|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{AA97C983-5A39-D35D-0274-08247BB08FAC}.Release|x86.Build.0 = Release|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Release|x64.Build.0 = Release|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{075F01AD-8478-3463-2BB9-D04EE5C98321}.Release|x86.Build.0 = Release|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Release|x64.Build.0 = Release|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{DE9F1F3D-7687-9248-E4D8-5684370E185F}.Release|x86.Build.0 = Release|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Release|x64.Build.0 = Release|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{47A6D609-F9EF-AE65-3904-5DBF15B0DEF1}.Release|x86.Build.0 = Release|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Release|x64.Build.0 = Release|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{AB0A194F-36A2-D62B-51FD-44335BE12D1B}.Release|x86.Build.0 = Release|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Release|x64.Build.0 = Release|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{F38B5372-D141-3A0D-6FF8-30EFA93C7506}.Release|x86.Build.0 = Release|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Release|x64.Build.0 = Release|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{3C77D0A0-173A-628F-FA3C-E113B9501E89}.Release|x86.Build.0 = Release|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Release|x64.Build.0 = Release|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{1FD9E0B6-EC08-54E4-82F2-A215A388968D}.Release|x86.Build.0 = Release|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Debug|Any CPU.ActiveCfg = Debug|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Debug|Any CPU.Build.0 = Debug|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Debug|x64.ActiveCfg = Debug|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Debug|x64.Build.0 = Debug|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Debug|x86.ActiveCfg = Debug|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Debug|x86.Build.0 = Debug|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Release|Any CPU.ActiveCfg = Release|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Release|Any CPU.Build.0 = Release|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Release|x64.ActiveCfg = Release|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Release|x64.Build.0 = Release|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Release|x86.ActiveCfg = Release|Any CPU\n\t\t{1424441E-1143-0F05-1346-E90195CDE10E}.Release|x86.Build.0 = Release|Any CPU\n\tEndGlobalSection\n\tGlobalSection(SolutionProperties) = preSolution\n\t\tHideSolutionNode = FALSE\n\tEndGlobalSection\n\tGlobalSection(ExtensibilityGlobals) = postSolution\n\t\tSolutionGuid = {21476EFF-778A-4F97-8A56-D1AF1CEC0C48}\n\tEndGlobalSection\nEndGlobal\n"
},
{
"path": "Ocelot.slnx",
"content": "\n \n \n \n \n \n \n \n \n \n \n\n"
},
{
"path": "README.md",
"content": "\r\n\r\n[](https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml)\r\n[](https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml)\r\n[](https://app.readthedocs.org/projects/ocelot/builds/?version__slug=develop)\r\n[](https://coveralls.io/github/ThreeMammals/Ocelot?branch=develop)\r\n[](https://codecov.io/gh/ThreeMammals/Ocelot)\r\n[](https://github.com/ThreeMammals/Ocelot/blob/main/LICENSE.md)\r\n[](https://www.nuget.org/packages/Ocelot/ \"Download Ocelot from NuGet.org\")\r\n[](https://www.nuget.org/packages/Ocelot/ \"Total Ocelot downloads from NuGet.org\")\r\n\r\n\r\n[~docspassing]: https://img.shields.io/badge/Docs-passing-44CC11?style=flat-square\r\n[~docsfailing]: https://img.shields.io/badge/Docs-failing-red?style=flat-square\r\n\r\n## About\r\nOcelot is a .NET [API gateway](https://www.bing.com/search?q=API+gateway).\r\nThis project is aimed at people using .NET running a microservices (service-oriented) architecture that needs a unified point of entry into their system.\r\nHowever, it will work with anything that speaks HTTP(S) and runs on any platform that [ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/) supports.\r\n\r\n\r\n\r\nOcelot consists of a series of ASP.NET Core [middlewares](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware/) arranged in a specific order.\r\nOcelot [custom middlewares](https://learn.microsoft.com/en-us/aspnet/core/fundamentals/middleware/write) manipulate the `HttpRequest` object into a state specified by its configuration until it reaches a request builder middleware, where it creates a `HttpRequestMessage` object, which is used to make a request to a downstream service.\r\nThe middleware that makes the request is the last thing in the Ocelot pipeline. It does not call the next middleware.\r\nThe response from the downstream service is retrieved as the request goes back up the Ocelot pipeline.\r\nThere is a piece of middleware that maps the `HttpResponseMessage` onto the `HttpResponse` object, and that is returned to the client.\r\nThat is basically it, with a bunch of other features!\r\n\r\n## Install\r\nOcelot is designed to work with [ASP.NET Core](https://learn.microsoft.com/en-us/aspnet/core/) and it targets `net9.0` [STS](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core#release-types) and `net8.0`, `net10.0` [LTS](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core#release-types) target framework monikers ([TFMs](https://learn.microsoft.com/en-us/dotnet/standard/frameworks#supported-target-frameworks)). [^1]\r\n\r\nInstall [Ocelot](https://www.nuget.org/packages/Ocelot) package and its dependencies using NuGet package manager:\r\n```powershell\r\nInstall-Package Ocelot\r\n```\r\nOr via the .NET CLI:\r\n```shell\r\ndotnet add package Ocelot\r\n```\r\n> All versions are available [on NuGet](https://www.nuget.org/packages/Ocelot#versions-body-tab).\r\n\r\n## Documentation\r\n- [RST-sources](https://github.com/ThreeMammals/Ocelot/tree/develop/docs):\r\n This includes the source code for the documentation (in reStructuredText format, .rst files), which is up to date for the current [development](https://github.com/ThreeMammals/Ocelot/tree/develop/).\r\n And the rendered HTML documentation is available [here](https://ocelot.readthedocs.io/en/develop/).\r\n- [Read the Docs](https://ocelot.readthedocs.io):\r\n This official website, in HTML format, contains a wealth of information and will be helpful if you want to understand the [features](#features) that Ocelot currently offers.\r\n The rendered HTML documentation, which is currently in [development](https://github.com/ThreeMammals/Ocelot/tree/develop/docs), is available [here](https://ocelot.readthedocs.io/en/develop/).\r\n- [Ask Ocelot Guru](https://gurubase.io/g/ocelot):\r\n It is an AI focused on Ocelot, designed to answer your questions. [^2]\r\n\r\n## Features\r\nThe primary features—[Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html) and [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html)—are always utilized by users, even in a minimal app setup, without customizations or extra configurations.\r\nOcelot's capabilities are categorized into three main groups of features: *solid*, *hybrid*, and *feature-family* groups, which are explained below.\r\n- *Solid features* are unique to Ocelot. They do not contain subfeatures and are not related to other features.\r\n- *Hybrid features*, on the other hand, have multiple relationships with other features and can be part of other features.\r\n- *Feature families* are large groups that consist of multiple subfeatures.\r\n\r\n| Group | Features |\r\n|-------|----------|\r\n|Primary|[Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html), [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html)|\r\n| Solid |[Caching](https://ocelot.readthedocs.io/en/latest/features/caching.html), [Delegating Handlers](https://ocelot.readthedocs.io/en/latest/features/delegatinghandlers.html), [Quality of Service](https://ocelot.readthedocs.io/en/latest/features/qualityofservice.html)[^3], [Rate Limiting](https://ocelot.readthedocs.io/en/latest/features/ratelimiting.html)|\r\n| Hybrid|[Administration](https://ocelot.readthedocs.io/en/latest/features/administration.html), [Aggregation](https://ocelot.readthedocs.io/en/latest/features/aggregation.html)[^4], [Authentication](https://ocelot.readthedocs.io/en/latest/features/authentication.html), [Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html), [Dependency Injection](https://ocelot.readthedocs.io/en/latest/features/dependencyinjection.html), [Load Balancer](https://ocelot.readthedocs.io/en/latest/features/loadbalancer.html)|\r\n|Family|[Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html), [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html), [Logging](https://ocelot.readthedocs.io/en/latest/features/logging.html), [Transformations](https://ocelot.readthedocs.io/en/latest/search.html?q=Transformation), [Service Discovery](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html)[^5] |\r\n\r\nFeature groups are explained in the table below\r\n\r\n| Feature | Relationships and Notes |\r\n|---------|-------------------------|\r\n| [Administration](https://ocelot.readthedocs.io/en/latest/features/administration.html) | [Administration](https://ocelot.readthedocs.io/en/latest/features/administration.html) heavily depends on [Authentication](https://ocelot.readthedocs.io/en/latest/features/authentication.html), and [Administration API](https://ocelot.readthedocs.io/en/latest/features/administration.html#administration-api) methods are part of [Authentication](https://ocelot.readthedocs.io/en/latest/features/authentication.html), [Caching](https://ocelot.readthedocs.io/en/latest/features/caching.html), and [Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html) |\r\n| [Aggregation](https://ocelot.readthedocs.io/en/latest/features/aggregation.html)[^4] | [Aggregation](https://ocelot.readthedocs.io/en/latest/features/aggregation.html) relies on [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html) |\r\n| [Authentication](https://ocelot.readthedocs.io/en/latest/features/authentication.html) | [Authentication](https://ocelot.readthedocs.io/en/latest/features/authentication.html) followed by [Authorization](https://ocelot.readthedocs.io/en/latest/features/authorization.html) |\r\n| [Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html) | [Configuration](https://ocelot.readthedocs.io/en/latest/features/configuration.html) depends on [Dependency Injection](https://ocelot.readthedocs.io/en/latest/features/dependencyinjection.html), including `GET`/`POST` operations via the [Administration REST API](https://ocelot.readthedocs.io/en/latest/features/administration.html#administration-api), a specialized [Websockets](https://ocelot.readthedocs.io/en/latest/features/websockets.html) scheme/protocol, advanced [Middleware Injection](https://ocelot.readthedocs.io/en/latest/features/middlewareinjection.html), and [Metadata](https://ocelot.readthedocs.io/en/latest/features/metadata.html)-based extensions |\r\n| [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html) | [Routing](https://ocelot.readthedocs.io/en/latest/features/routing.html) offers specialized [Websockets](https://ocelot.readthedocs.io/en/latest/features/websockets.html) and [Dynamic Routing](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html#dynamic-routing) modes but does not support [GraphQL](https://ocelot.readthedocs.io/en/latest/features/graphql.html)[^6] |\r\n| [Load Balancer](https://ocelot.readthedocs.io/en/latest/features/loadbalancer.html) | [Load Balancer](https://ocelot.readthedocs.io/en/latest/features/loadbalancer.html) is a critical dependency for [Service Discovery](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html) |\r\n| [Logging](https://ocelot.readthedocs.io/en/latest/features/logging.html) | [Logging](https://ocelot.readthedocs.io/en/latest/features/logging.html) includes [Error Handling](https://ocelot.readthedocs.io/en/latest/features/errorcodes.html) and [Tracing](https://ocelot.readthedocs.io/en/latest/features/tracing.html) |\r\n| [Service Discovery](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html)[^5] | [Service Discovery](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html) with the following discovery providers: [Consul](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html#consul), [Kubernetes](https://ocelot.readthedocs.io/en/latest/features/kubernetes.html), [Eureka](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html#eureka), and [Service Fabric](https://ocelot.readthedocs.io/en/latest/features/servicefabric.html) |\r\n| [Transformations](https://ocelot.readthedocs.io/en/latest/search.html?q=Transformation) | They provide transformations for [Claims](https://ocelot.readthedocs.io/en/latest/features/claimstransformation.html), [Headers](https://ocelot.readthedocs.io/en/latest/features/headerstransformation.html), and [Method](https://ocelot.readthedocs.io/en/latest/features/methodtransformation.html) |\r\n\r\n> Ocelot customizations can be configured using [Metadata](https://ocelot.readthedocs.io/en/latest/features/metadata.html), developed with [Delegating Handlers](https://ocelot.readthedocs.io/en/latest/features/delegatinghandlers.html), and in advanced scenarios, they can be developed and then configured with [Middleware Injection](https://ocelot.readthedocs.io/en/latest/features/middlewareinjection.html).\r\nFor further details, refer to the [Documentation](#documentation).\r\n\r\n## Contributing\r\nYou can see what we are working on in the [backlog](https://github.com/ThreeMammals/Ocelot/issues).\r\nWe love to receive contributions from the community, so please keep them coming.\r\nPull requests, issues, and commentary welcome! ![\"octocat\"](\"https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png\")
\r\n\r\nPlease complete the relevant [template](https://github.com/ThreeMammals/Ocelot/tree/main/.github) for [issues](https://github.com/ThreeMammals/Ocelot/blob/main/.github/ISSUE_TEMPLATE.md) and [pull requests](https://github.com/ThreeMammals/Ocelot/blob/main/.github/PULL_REQUEST_TEMPLATE.md).\r\nSometimes it's worth getting in touch with us to [discuss](https://github.com/ThreeMammals/Ocelot/discussions) changes before doing any work in case this is something we are already doing or it might not make sense.\r\nWe can also give advice on the easiest way to do things \r\n\r\nFinally, we mark all existing issues as [![label: help wanted][~helpwanted]](https://github.com/ThreeMammals/Ocelot/labels/help%20wanted)\r\n[![label: small effort][~smalleffort]](https://github.com/ThreeMammals/Ocelot/labels/small%20effort)\r\n[![label: medium effort][~mediumeffort]](https://github.com/ThreeMammals/Ocelot/labels/medium%20effort)\r\n[![label: large effort][~largeeffort]](https://github.com/ThreeMammals/Ocelot/labels/large%20effort).[^7]\r\nIf you want to contribute for the first time, we suggest looking at a [![label: help wanted][~helpwanted]](https://github.com/ThreeMammals/Ocelot/labels/help%20wanted) \r\n[![label: small effort][~smalleffort]](https://github.com/ThreeMammals/Ocelot/labels/small%20effort) \r\n[![label: good first issue][~goodfirstissue]](https://github.com/ThreeMammals/Ocelot/labels/good%20first%20issue) \r\n\r\n[~helpwanted]: https://img.shields.io/badge/-help%20wanted-128A0C.svg\r\n[~smalleffort]: https://img.shields.io/badge/-small%20effort-fef2c0.svg\r\n[~mediumeffort]: https://img.shields.io/badge/-medium%20effort-e0f42c.svg\r\n[~largeeffort]: https://img.shields.io/badge/-large%20effort-10526b.svg\r\n[~goodfirstissue]: https://img.shields.io/badge/-good%20first%20issue-ffc4d8.svg\r\n\r\n### Notes\r\n[^1]: Starting with version [21](https://github.com/ThreeMammals/Ocelot/releases/tag/21.0.0) and higher, the solution's code base supports [Multitargeting](https://learn.microsoft.com/en-us/visualstudio/msbuild/msbuild-multitargeting-overview) as SDK-style projects. It should be easier for teams to migrate to the currently supported [.NET 8, 9 and 10](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core#lifecycle) frameworks. Also, new features will be available for all .NET SDKs that we support via multitargeting. Find out more here: [Target frameworks in SDK-style projects](https://learn.microsoft.com/en-us/dotnet/standard/frameworks)\r\n[^2]: [Ocelot Guru](https://gurubase.io/g/ocelot) is an unofficial tool to get answers regarding Ocelot: please consider it an advanced search tool. Thus, we have an official [Questions & Answers](https://github.com/ThreeMammals/Ocelot/discussions/categories/q-a) category in the [Discussions](https://github.com/ThreeMammals/Ocelot/discussions) space.\r\n[^3]: Retry policies only via [Polly](https://github.com//App-vNext/Polly) library referenced within the [Ocelot.Provider.Polly](https://www.nuget.org/packages/Ocelot.Provider.Polly) extension package.\r\n[^4]: Previously, the [Aggregation](https://ocelot.readthedocs.io/en/latest/features/aggregation.html) feature was called [Request Aggregation](https://ocelot.readthedocs.io/en/23.4.3/features/requestaggregation.html) in versions [23.4.3](https://github.com/ThreeMammals/Ocelot/releases/tag/23.4.3) and earlier. Internally, within the Ocelot team, this feature is referred to as [Multiplexer](https://github.com/ThreeMammals/Ocelot/tree/main/src/Ocelot/Multiplexer).\r\n[^5]: Ocelot supports the following service discovery providers: (**1**) [Consul](https://www.consul.io) through the [Ocelot.Provider.Consul](https://www.nuget.org/packages/Ocelot.Provider.Consul) extension package, (**2**) [Kubernetes](https://kubernetes.io) via the [Ocelot.Provider.Kubernetes](https://www.nuget.org/packages/Ocelot.Provider.Kubernetes) extension package, and (**3**) [Netflix Eureka](https://spring.io/projects/spring-cloud-netflix), which utilizes the [Steeltoe.Discovery.Eureka](https://www.nuget.org/packages/Steeltoe.Discovery.Eureka) package referenced within the [Ocelot.Provider.Eureka](https://www.nuget.org/packages/Ocelot.Provider.Eureka) extension package. Additionally, Ocelot supports (**4**) Azure [Service Fabric](https://azure.microsoft.com/en-us/products/service-fabric/) for service discovery, along with special modes such as [Dynamic Routing](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html#dynamic-routing) and [Custom Providers](https://ocelot.readthedocs.io/en/latest/features/servicediscovery.html#custom-providers).\r\n[^6]: Ocelot does not directly support [GraphQL](https://graphql.org/). Developers can easily integrate the [GraphQL for .NET](https://github.com/graphql-dotnet/graphql-dotnet) library. \r\n[^7]: See all [labels](https://github.com/ThreeMammals/Ocelot/issues/labels) for the repository, which are useful for searching and filtering.\r\n\r\n"
},
{
"path": "ReleaseNotes.md",
"content": "\n## Pre-release 2 for [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) SDK (version [{0}](https://www.nuget.org/packages/Ocelot/{0}))\n> Milestone: [.NET 10](https://github.com/ThreeMammals/Ocelot/milestone/13)\n\nThis is **Pre-release 2** for the [.NET 10](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) SDK.\n\nVersion [{0}](https://www.nuget.org/packages/Ocelot/{0}) includes upgraded solutions and [NuGet packages](https://www.nuget.org/profiles/ThreeMammals) based on .NET SDK [10.0.201](https://dotnet.microsoft.com/en-us/download/dotnet/10.0), released on March 12, 2026.\nFor more details about SDK [10.0.201](https://dotnet.microsoft.com/en-us/download/dotnet/10.0), see the [Release notes](https://github.com/dotnet/core/blob/main/release-notes/10.0/10.0.5/10.0.5.md).\n\nDevelopment teams can start migrating their Ocelot-based projects using this [Beta 2](https://www.nuget.org/packages/Ocelot/{0}) release to upgrade to the .NET 10 SDK with Long-Term Support (LTS).\n"
},
{
"path": "build.cake",
"content": "#tool dotnet:?package=GitVersion.Tool&version=6.6.2\r\n#tool nuget:?package=ReportGenerator&version=5.5.4\r\n\r\n#addin nuget:?package=Cake.Http\r\n#addin nuget:?package=Newtonsoft.Json&version=13.0.4 // Switch to a MS lib!\r\n#addin nuget:?package=System.Text.Encodings.Web&version=10.0.5\r\n\r\n#r \"Spectre.Console\"\r\nusing Spectre.Console;\r\n\r\nusing System.Collections.Generic;\r\nusing System.Globalization;\r\nusing System.IO;\r\nusing System.Linq;\r\nusing System.Text.RegularExpressions;\r\nusing _File_ = System.IO.File;\r\nusing _Directory_ = System.IO.Directory;\r\n\r\nbool IsTechnicalRelease = false;\r\nconst string Release = \"Release\"; // task name, target, and Release config name\r\nconst string PullRequest = \"PullRequest\"; // task name, target, and PullRequest config name\r\nconst string LatestFramework = \"LatestFramework\"; // task name, target, and LatestFramework config name\r\nconst string AllTFMs = \"net8.0;net9.0;net10.0\";\r\nconst string LatestTFM = \"net10.0\";\r\nstring NL = Environment.NewLine;\r\n\r\n// Create a CultureInfo object for UK English\r\nCultureInfo ukCulture = new(\"en-GB\");\r\nCultureInfo.DefaultThreadCurrentCulture = ukCulture;\r\nCultureInfo.DefaultThreadCurrentUICulture = ukCulture;\r\nInformation(\"Current Culture: \" + CultureInfo.CurrentCulture);\r\nInformation(\"Current UI Culture: \" + CultureInfo.CurrentUICulture);\r\n\r\n// Display culture properties\r\nInformation(\"Culture Name: \" + ukCulture.Name); // en-GB\r\nInformation(\"Display Name: \" + ukCulture.DisplayName); // English (United Kingdom)\r\nInformation(\"English Name: \" + ukCulture.EnglishName); // English (United Kingdom)\r\nInformation(\"Native Name: \" + ukCulture.NativeName); // English (United Kingdom)\r\nInformation(\"Two-letter ISO Language Name: \" + ukCulture.TwoLetterISOLanguageName); // en\r\nInformation(\"Three-letter ISO Language Name: \" + ukCulture.ThreeLetterISOLanguageName); // eng\r\nInformation(\"Region ISO Code: \" + new RegionInfo(ukCulture.Name).TwoLetterISORegionName); // GB\r\n\r\n// Example: format a date and currency in UK style\r\nDateTime now = DateTime.Now;\r\ndecimal amount = 12345.67m;\r\nInformation(\"Date (UK format): \" + now.ToString(\"D\", ukCulture));\r\nInformation(\"Currency (UK format): \" + amount.ToString(\"C\", ukCulture));\r\n\r\nvar compileConfig = Argument(\"configuration\", Release); // compile\r\nvar artifactsDir = Directory(\"artifacts\"); // build artifacts\r\n\r\n// unit testing\r\nvar artifactsForUnitTestsDir = artifactsDir + Directory(\"UnitTests\");\r\nvar unitTestAssemblies = @\"./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj\";\r\n\r\n// acceptance testing\r\nvar artifactsForAcceptanceTestsDir = artifactsDir + Directory(\"AcceptanceTests\");\r\nvar acceptanceTestAssemblies = @\"./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj\";\r\n\r\n// benchmark testing\r\nvar artifactsForBenchmarkTestsDir = artifactsDir + Directory(\"BenchmarkTests\");\r\nvar benchmarkTestAssemblies = @\"./test/Ocelot.Benchmarks\";\r\n\r\n// packaging\r\nvar packagesDir = artifactsDir + Directory(\"Packages\");\r\nvar artifactsFile = packagesDir + File(\"artifacts.txt\");\r\nvar releaseNotesFile = packagesDir + File(\"ReleaseNotes.md\");\r\nvar releaseNotes = new List();\r\n\r\n// internal build variables - don't change these.\r\nstring committedVersion = \"0.0.0-dev\";\r\nGitVersion versioning = null;\r\n\r\nvar target = Argument(\"target\", \"Default\");\r\nvar slnFile = \"./Ocelot.slnx\";\r\n\r\nInformation($\"{NL}Target: {target}\");\r\nInformation($\"Build: {compileConfig}\");\r\nInformation($\"Solution: {slnFile}\");\r\n\r\nTaskTeardown(context => {\r\n\tAnsiConsole.Markup($\"[green]DONE[/] {context.Task.Name}\" + NL);\r\n});\r\n\r\nTask(\"Default\")\r\n\t.IsDependentOn(\"Build\");\r\nTask(\"Build\")\r\n\t.IsDependentOn(\"Tests\");\r\nTask(\"LatestFramework\")\r\n\t.IsDependentOn(\"Tests\");\r\nTask(\"PullRequest\")\r\n\t.IsDependentOn(\"Tests\");\r\n\r\nTask(\"ReleaseNotes\")\r\n\t.IsDependentOn(\"CreateReleaseNotes\");\r\n\r\nTask(\"Tests\")\r\n\t.IsDependentOn(\"UnitTests\")\r\n\t.IsDependentOn(\"AcceptanceTests\");\r\n\r\nTask(\"Release\")\r\n\t.IsDependentOn(\"Build\")\r\n\t.IsDependentOn(\"CreateReleaseNotes\")\r\n\t.IsDependentOn(\"CreateArtifacts\")\r\n\t.IsDependentOn(\"PublishGitHubRelease\")\r\n .IsDependentOn(\"PublishToNuget\");\r\n\r\nTask(\"Restore\")\r\n .Does(() =>\r\n\t{\r\n\t\tvar settings = new DotNetRestoreSettings\r\n\t\t{\r\n\t\t\tLockedMode = true, // equivalent to --locked-mode\r\n\t\t\t// UseLockFile = true, // equivalent to --use-lock-file\r\n\t\t\t// Sources = new[] { \"https://api.nuget.org/v3/index.json\" }\r\n\t\t};\r\n\t\tDotNetRestore(slnFile, settings);\r\n\t});\r\n\r\nTask(\"Compile\")\r\n\t.IsDependentOn(\"Clean\")\r\n\t.IsDependentOn(\"Version\")\r\n\t.IsDependentOn(\"Restore\")\r\n\t.Does(() =>\r\n\t{\t\r\n\t\tPreprocessReadMe();\r\n\t\tInformation(\"Branch: \" + GetBranchName());\r\n\t\tInformation(\"Build: \" + compileConfig);\r\n\t\tInformation(\"Solution: \" + slnFile);\r\n\t\tvar settings = new DotNetBuildSettings\r\n\t\t{\r\n\t\t\tConfiguration = compileConfig,\r\n\t\t\tNoRestore = true,\r\n\t\t};\r\n\t\tif (target == LatestFramework || target == PullRequest)\r\n\t\t{\r\n\t\t\tsettings.Framework = LatestTFM; // build using .NET 10 SDK only\r\n\t\t}\r\n\t\tstring frameworkInfo = string.IsNullOrEmpty(settings.Framework) ? AllTFMs : settings.Framework;\r\n\t\tInformation($\"Settings {nameof(DotNetBuildSettings.Framework)}: {frameworkInfo}\");\r\n\t\tInformation($\"Settings {nameof(DotNetBuildSettings.Configuration)}: {settings.Configuration}\");\r\n\t\tDotNetBuild(slnFile, settings);\r\n\t});\r\n\r\nTask(\"Clean\")\r\n\t.Does(() =>\r\n\t{\r\n if (DirectoryExists(artifactsDir))\r\n {\r\n DeleteDirectory(artifactsDir, new DeleteDirectorySettings {\r\n\t\t\t\tRecursive = true,\r\n\t\t\t\tForce = true\r\n\t\t\t});\r\n }\r\n CreateDirectory(artifactsDir);\r\n\t});\r\n\r\nTask(\"Version\")\r\n\t.Does(() =>\r\n\t{\r\n\t\tversioning = GetNuGetVersionForCommit();\r\n\t\tversioning.NuGetVersion ??= versioning.SemVer;\r\n\t\tif (target == Release && IsRunningInCICD() && IsMainBranch() && versioning.SemVer.Contains(\"-\")) // dash -> suffix in version\r\n\t\t\tversioning.NuGetVersion = versioning.MajorMinorPatch; // when releasing from main branch the tag should not contain suffix after dash char\r\n\r\n\t\tInformation(\"#########################\");\r\n\t\tInformation(\"# SemVer Information\");\r\n\t\tInformation(\"#========================\");\r\n\t\tInformation($\"# {nameof(versioning.NuGetVersion)}: {versioning.NuGetVersion}\");\r\n\t\tInformation($\"# {nameof(versioning.BranchName)}: {versioning.BranchName}\");\r\n\t\tInformation($\"# {nameof(versioning.MajorMinorPatch)}: {versioning.MajorMinorPatch}\");\r\n\t\tInformation($\"# {nameof(versioning.SemVer)}: {versioning.SemVer}\");\r\n\t\tInformation($\"# {nameof(versioning.InformationalVersion)}: {versioning.InformationalVersion}\");\r\n\t\tInformation(\"#########################\");\r\n\r\n\t\tInformation($\"Persisting version number... {nameof(versioning.NuGetVersion)} -> {versioning.NuGetVersion}\");\r\n\t\tPersistVersion(committedVersion, versioning.NuGetVersion);\r\n\t});\r\n\r\nTask(\"GitLogUniqContributors\")\r\n\t.Does(() =>\r\n\t{\r\n\t\tvar command = \"log --format=\\\"%aN|%aE\\\" \";\r\n\t\t// command += IsRunningInCICD() ? \"| sort | uniq\" :\r\n\t\t// \tIsRunningInPowershell() ? \"| Sort-Object -Unique\" : \"| sort | uniq\";\r\n\t\tList output = GitHelper(command);\r\n\t\toutput.Sort();\r\n\t\tList contributors = output.Distinct().ToList();\r\n\t\tcontributors.Sort();\r\n Information($\"Detected {contributors.Count} unique contributors:\");\r\n Information(string.Join(NL, contributors));\r\n\t\t// TODO Search example in bash: curl -L -H \"X-GitHub-Api-Version: 2022-11-28\" \"https://api.github.com/search/users?q=Chris+Swinchatt\"\r\n Information(NL + \"Unicode test: 1) Raynald Messié; 2) 彭伟 pengweiqhca\");\r\n AnsiConsole.Markup(\"Unicode test: 1) Raynald Messié; 2) 彭伟 pengweiqhca\" + NL);\r\n\t\t// Powershell life hack: $OutputEncoding = [Console]::InputEncoding = [Console]::OutputEncoding = New-Object System.Text.UTF8Encoding\r\n\t\t// https://stackoverflow.com/questions/40098771/changing-powershells-default-output-encoding-to-utf-8\r\n\t\t// https://stackoverflow.com/questions/49476326/displaying-unicode-in-powershell/49481797#49481797\r\n\t\t// https://stackoverflow.com/questions/57131654/using-utf-8-encoding-chcp-65001-in-command-prompt-windows-powershell-window/57134096#57134096\r\n\t});\r\n\r\nTask(\"CreateReleaseNotes\")\r\n\t.IsDependentOn(\"Version\")\r\n\t//.IsDependentOn(\"GitLogUniqContributors\")\r\n\t.Does(() =>\r\n\t{\r\n Information($\"Generating release notes at {releaseNotesFile}\");\r\n var lastReleaseTags = GitHelper(\"describe --tags --abbrev=0 --exclude net*\");\r\n var lastRelease = lastReleaseTags.First(t => !t.StartsWith(\"net\")); // skip 'net*-vX.Y.Z' tag and take 'major.minor.build'\r\n var releaseVersion = versioning.NuGetVersion;\r\n\r\n // Read main header from Git file, substitute version in header, and add content further...\r\n Information(\"{0} New release tag is \" + releaseVersion);\r\n Information(\"{1} Last release tag is \" + lastRelease);\r\n var body = _File_.ReadAllText(\"./ReleaseNotes.md\", System.Text.Encoding.UTF8);\r\n var releaseHeader = string.Format(body, releaseVersion, lastRelease);\r\n releaseNotes = new List { releaseHeader };\r\n if (IsTechnicalRelease)\r\n {\r\n WriteReleaseNotes();\r\n return;\r\n }\r\n\r\n const bool debugUserEmail = false;\r\n var shortlogSummary = GitHelper($\"shortlog --no-merges --numbered --summary --email {lastRelease}..HEAD\")\r\n .ToList();\r\n var re = new Regex(@\"^[\\s\\t]*(?'commits'\\d+)[\\s\\t]+(?'author'.*)[\\s\\t]+<(?'email'.*)>.*$\");\r\n static SummaryItem CreateSummaryItem(System.Text.RegularExpressions.Match m) => new()\r\n {\r\n Commits = int.Parse(m.Groups[\"commits\"]?.Value ?? \"0\"),\r\n Author = m.Groups[\"author\"]?.Value?.Trim() ?? string.Empty,\r\n Email = m.Groups[\"email\"]?.Value?.Trim() ?? string.Empty,\r\n };\r\n var summary = shortlogSummary\r\n .Where(x => re.IsMatch(x))\r\n .Select(x => re.Match(x))\r\n .Select(CreateSummaryItem)\r\n .ToList();\r\n\r\n // Starring aka Release Influencers\r\n var starring = new List();\r\n string CreateStars(int count, string name)\r\n {\r\n var contributor = summary.Find(x => x.Author.Equals(name));\r\n var stars = string.Join(string.Empty, Enumerable.Repeat(\":star:\", count));\r\n var emailInfo = debugUserEmail ? \", \" + contributor.Email : string.Empty;\r\n return $\"{stars} {contributor.Author}{emailInfo}\";\r\n }\r\n\r\n Information(\"------==< Old Starring >==------\");\r\n foreach (var contributor in summary)\r\n {\r\n starring.Add(CreateStars(contributor.Commits, contributor.Author));\r\n }\r\n Information(string.Join(NL, starring));\r\n\r\n var commitsGrouping = summary\r\n .GroupBy(x => x.Commits)\r\n .Select(CreateCommitsGroupingItem)\r\n .OrderByDescending(x => x.Commits)\r\n .ToList();\r\n starring = IterateCommits(commitsGrouping,\r\n breaker: log => false, // don't break, so iterate all groups (summary)\r\n byCommits: (log, group) => CreateStars(group.Commits, group.Authors.First()),\r\n byFiles: (log, group, fGroup) => CreateStars(group.Commits, fGroup.Contributors.First().Contributor),\r\n byInsertions: (log, group, fGroup, insGroup) => CreateStars(group.Commits, insGroup.Contributors.First().Contributor),\r\n byDeletions: (log, group, fGroup, insGroup, contributor) => CreateStars(group.Commits, contributor.Contributor));\r\n Information(\"------==< New Starring >==------\");\r\n Information(string.Join(NL, starring));\r\n\r\n // Honoring aka Top Contributors\r\n var coreTeamNames = new List { \"Raman Maksimchuk\", \"Raynald Messié\", \"Guillaume Gnaegi\" }; // Ocelot Core team members should not be in Top 3 Chart\r\n var coreTeamEmails = new List { \"dotnet044@gmail.com\", \"redbird_project@yahoo.fr\", \"58469901+ggnaegi@users.noreply.github.com\" };\r\n static CommitsGroupingItem CreateCommitsGroupingItem(IGrouping g) => new()\r\n {\r\n Commits = g.Key,\r\n Count = g.Count(),\r\n Authors = g.Select(x => x.Author).ToArray(),\r\n };\r\n commitsGrouping = summary\r\n .Where(x => !coreTeamNames.Contains(x.Author) && !coreTeamEmails.Contains(x.Email)) // filter out Ocelot Core team members\r\n .GroupBy(x => x.Commits)\r\n .Select(CreateCommitsGroupingItem)\r\n .OrderByDescending(x => x.Commits)\r\n .ToList();\r\n var topContributors = IterateCommits(commitsGrouping,\r\n breaker: log => false, // (log.Count >= 3), // going to create Top 3\r\n byCommits: (log, group) =>\r\n {\r\n var place = Place(log.Count);\r\n var author = group.Authors.First();\r\n return Honor(place, author, group.Commits);\r\n },\r\n byFiles: (log, group, fGroup) =>\r\n {\r\n var place = Place(log.Count);\r\n var contributor = fGroup.Contributors.First();\r\n return HonorForFiles(place, contributor.Contributor, group.Commits, contributor.Files);\r\n },\r\n byInsertions: (log, group, fGroup, insGroup) =>\r\n {\r\n var place = Place(log.Count);\r\n var contributor = insGroup.Contributors.First();\r\n return HonorForInsertions(place, contributor.Contributor, group.Commits, contributor.Files, contributor.Insertions);\r\n },\r\n byDeletions: (log, group, fGroup, insGroup, contributor) =>\r\n {\r\n var place = Place(log.Count);\r\n return HonorForDeletions(place, contributor.Contributor, group.Commits, contributor.Files, contributor.Insertions, contributor.Deletions);\r\n });\r\n Information(\"------==< TOP Contributors >==------\");\r\n Information(string.Join(NL, topContributors));\r\n\r\n // local helpers\r\n static string Place(int i) => ++i == 1 ? \"1st\" : i == 2 ? \"2nd\" : i == 3 ? \"3rd\" : $\"{i}th\";\r\n static string Plural(int n) => n == 1 ? \"\" : \"s\";\r\n static string Honor(string place, string author, int commits, string suffix = null)\r\n => $\"{place[0]}{place[1..]} :{place}_place_medal: goes to **{author}** for delivering **{commits}** feature{Plural(commits)} {suffix ?? \"\"}\";\r\n static string HonorForFiles(string place, string author, int commits, int files, string suffix = null)\r\n => Honor(place, author, commits, $\"in **{files}** file{Plural(files)} changed {suffix ?? \"\"}\");\r\n static string HonorForInsertions(string place, string author, int commits, int files, int insertions, string suffix = null)\r\n => HonorForFiles(place, author, commits, files, $\"with **{insertions}** insertion{Plural(insertions)} {suffix ?? \"\"}\");\r\n static string HonorForDeletions(string place, string author, int commits, int files, int insertions, int deletions)\r\n => HonorForInsertions(place, author, commits, files, insertions, $\"and **{deletions}** deletion{Plural(deletions)}\");\r\n List IterateCommits(List commitsGrouping, Predicate> breaker,\r\n Func, CommitsGroupingItem, string> byCommits,\r\n Func, CommitsGroupingItem, FilesGroupingItem, string> byFiles,\r\n Func, CommitsGroupingItem, FilesGroupingItem, InsertionsGroupingItem, string> byInsertions,\r\n Func, CommitsGroupingItem, FilesGroupingItem, InsertionsGroupingItem, FilesChangedItem, string> byDeletions)\r\n {\r\n var log = new List();\r\n foreach (var group in commitsGrouping)\r\n {\r\n if (breaker.Invoke(log)) break; // (log.Count >= top3)\r\n if (group.Count == 1)\r\n {\r\n log.Add(byCommits.Invoke(log, group));\r\n }\r\n else // multiple candidates with the same number of commits, so, group by files changed\r\n {\r\n var statistics = new List();\r\n var shortstatRegex = new Regex(@\"^\\s*(?'files'\\d+)\\s+files?\\s+changed(?'ins',\\s+(?'insertions'\\d+)\\s+insertions?\\(\\+\\))?(?'del',\\s+(?'deletions'\\d+)\\s+deletions?\\(\\-\\))?\\s*$\");\r\n static FilesChangedItem CreateFilesChangedItem(System.Text.RegularExpressions.Match m)\r\n\t\t\t\t\t{\r\n\t\t\t\t\t\tFilesChangedItem item = new();\r\n\t\t\t\t\t\tif (int.TryParse(m.Groups[\"files\"]?.Value ?? \"0\", out int files))\r\n \t\t\t\titem.Files = files;\r\n\t\t\t\t\t\telse\r\n \t\t\t\titem.Files = 0;\r\n\r\n\t\t\t\t\t\tif (int.TryParse(m.Groups[\"insertions\"]?.Value ?? \"0\", out int insertions))\r\n \t\t\t\titem.Insertions = insertions;\r\n\t\t\t\t\t\telse\r\n \t\t\t\titem.Insertions = 0;\r\n\r\n\t\t\t\t\t\tif (int.TryParse(m.Groups[\"deletions\"]?.Value ?? \"0\", out int deletions))\r\n \t\t\t\titem.Deletions = deletions;\r\n\t\t\t\t\t\telse\r\n \t\t\t\titem.Deletions = 0;\r\n\t\t\t\t\t\treturn item;\r\n\t\t\t\t\t}\r\n foreach (var author in group.Authors) // Collect statistics from git log & shortlog\r\n {\r\n if (!statistics.Exists(s => s.Contributor == author))\r\n {\r\n var shortstat = GitHelper($\"log --no-merges --author=\\\"{author}\\\" --shortstat --pretty=oneline {lastRelease}..HEAD\");\r\n var data = shortstat\r\n .Where(x => shortstatRegex.IsMatch(x))\r\n .Select(x => shortstatRegex.Match(x))\r\n .Select(CreateFilesChangedItem)\r\n .ToList();\r\n statistics.Add(new FilesChangedItem(author, data.Sum(x => x.Files), data.Sum(x => x.Insertions), data.Sum(x => x.Deletions)));\r\n }\r\n }\r\n var filesGrouping = statistics\r\n .GroupBy(x => x.Files)\r\n .Select(g => new FilesGroupingItem\r\n {\r\n Files = g.Key,\r\n Count = g.Count(),\r\n Contributors = g.SelectMany(x => statistics.Where(s => s.Contributor == x.Contributor && s.Files == g.Key)).ToArray(),\r\n })\r\n .OrderByDescending(x => x.Files)\r\n .ToList();\r\n foreach (var fGroup in filesGrouping)\r\n {\r\n if (breaker.Invoke(log)) break;\r\n if (fGroup.Count == 1)\r\n {\r\n log.Add(byFiles.Invoke(log, group, fGroup));\r\n }\r\n else // multiple candidates with the same number of commits, with the same number of changed files, so, group by additions (insertions)\r\n {\r\n var insertionsGrouping = fGroup.Contributors\r\n .GroupBy(x => x.Insertions)\r\n .Select(g => new InsertionsGroupingItem\r\n {\r\n Insertions = g.Key,\r\n Count = g.Count(),\r\n Contributors = g.SelectMany(x => fGroup.Contributors.Where(s => s.Contributor == x.Contributor && s.Insertions == g.Key)).ToArray(),\r\n })\r\n .OrderByDescending(x => x.Insertions)\r\n .ToList();\r\n foreach (var insGroup in insertionsGrouping)\r\n {\r\n if (breaker.Invoke(log)) break;\r\n if (insGroup.Count == 1)\r\n {\r\n log.Add(byInsertions.Invoke(log, group, fGroup, insGroup));\r\n }\r\n else // multiple candidates with the same number of commits, with the same number of changed files, with the same number of insertions, so, order desc by deletions\r\n {\r\n foreach (var contributor in insGroup.Contributors.OrderByDescending(x => x.Deletions))\r\n {\r\n if (breaker.Invoke(log)) break;\r\n log.Add(byDeletions.Invoke(log, group, fGroup, insGroup, contributor));\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n }\r\n return log;\r\n } // END of IterateCommits\r\n // releaseNotes.Add(\"### Honoring :medal_sports: aka Top Contributors :clap:\");\r\n // releaseNotes.AddRange(topContributors.Take(3)); // Top 3 only, disabled 'breaker' logic\r\n // releaseNotes.Add(\"\");\r\n // releaseNotes.Add(\"### Starring :star: aka Release Influencers :bowtie:\");\r\n // releaseNotes.AddRange(starring);\r\n // releaseNotes.Add(\"\");\r\n // releaseNotes.Add($\"### Features in Release {releaseVersion}\");\r\n // releaseNotes.Add(\"\");\r\n // releaseNotes.Add(\"Logbook
\");\r\n // releaseNotes.Add(\"\");\r\n // var commitsHistory = GitHelper($\"log --no-merges --date=format:\\\"%A, %B %d at %H:%M\\\" --pretty=format:\\\"- %h by **%aN** on %ad →%n %s\\\" {lastRelease}..HEAD\");\r\n // releaseNotes.AddRange(commitsHistory);\r\n // releaseNotes.Add(\"![\\\"octocat\\\"](\\\"https://raw.githubusercontent.com/ThreeMammals/Ocelot/refs/heads/assets/images/octocat.png\\\")
\";\r\n\tconst string IMG_NuGet_Valid_MD = \"\";\r\n\tif (body.Contains(IMG_Octocat_HTML))\r\n\t{\r\n\t\tInformation($\" {READMEmd}: Detected Octocat HTML IMG-tag -> \" + IMG_Octocat_HTML);\r\n\t\tbody = body.Replace(IMG_Octocat_HTML, IMG_NuGet_Valid_MD);\r\n\t\tInformation($\" {READMEmd}: Octocat HTML IMG-tag has been replaced with -> \" + IMG_NuGet_Valid_MD);\r\n\t}\r\n\tInformation($\" {READMEmd}: Writing the body of the {READMEmd}...\");\r\n\t_File_.WriteAllText(READMEmd, body, System.Text.Encoding.UTF8);\r\n\tInformation($\"DONE Processing {READMEmd}{NL}\");\r\n}\r\n\r\nprivate void GenerateReport(Cake.Core.IO.FilePath coverageSummaryFile)\r\n{\r\n\tvar dir = _Directory_.GetCurrentDirectory();\r\n\tInformation(\"GenerateReport: Current directory: \" + dir);\r\n\r\n\tvar reportSettings = new ProcessArgumentBuilder();\r\n\treportSettings.Append($\"-targetdir:\" + $\"{dir}/{artifactsForUnitTestsDir}\");\r\n\treportSettings.Append($\"-reports:\" + coverageSummaryFile);\r\n\treportSettings.Append($\"-filefilters:-*.g.cs\"); // silence warnings for source-generated files (e.g. RegexGenerator.g.cs) that are deleted after build\r\n\r\n\tInformation($\"GenerateReport: Resolving net10.0/ReportGenerator.dll ...\");\r\n\tvar toolpath = Context.Tools.Resolve(\"net10.0/ReportGenerator.dll\");\r\n\tInformation($\"GenerateReport: Tool Path: {toolpath.ToString()}\" + NL);\r\n\r\n\tDotNetExecute(toolpath, reportSettings);\r\n}\r\n\r\n/// Gets unique nuget version for this commit\r\nprivate GitVersion GetNuGetVersionForCommit()\r\n{\r\n GitVersion(new GitVersionSettings{\r\n UpdateAssemblyInfo = false,\r\n OutputType = GitVersionOutput.BuildServer,\r\n\t\tVerbosity = IsRunningInCICD() ? GitVersionVerbosity.Minimal : GitVersionVerbosity.Normal,\r\n });\r\n return GitVersion(new GitVersionSettings{ OutputType = GitVersionOutput.Json });\r\n}\r\n\r\n/// Updates project version in all of our projects\r\nprivate void PersistVersion(string committedVersion, string newVersion)\r\n{\r\n\tInformation(string.Format(\"We'll search all csproj files for {0} and replace with {1}...\", committedVersion, newVersion));\r\n\tvar projectFiles = GetFiles(\"./**/*.csproj\")\r\n\t\t.Where(f => !f.FullPath.Contains(\"Ocelot.Samples.\"))\r\n\t\t.ToList();\r\n\tforeach(var projectFile in projectFiles)\r\n\t{\r\n\t\tvar file = projectFile.ToString();\r\n\t\tInformation(string.Format(\"Updating {0}...\", file));\r\n\r\n\t\tvar updatedProjectFile = _File_.ReadAllText(file, System.Text.Encoding.UTF8)\r\n\t\t\t.Replace(committedVersion, newVersion);\r\n\r\n\t\t_File_.WriteAllText(file, updatedProjectFile, System.Text.Encoding.UTF8);\r\n\t}\r\n}\r\n\r\n// Publishes code and symbols packages to nuget feed, based on contents of artifacts file\r\nprivate void PublishPackages(ConvertableDirectoryPath packagesDir, ConvertableFilePath artifactsFile, string feedApiKey, string codeFeedUrl, string symbolFeedUrl)\r\n{\r\n\tInformation($\"{nameof(PublishPackages)}: Publishing to NuGet...\");\r\n\tvar artifacts = _File_.ReadAllLines(artifactsFile)\r\n\t\t.Distinct()\r\n\t\t.Where(a => a.EndsWith(\".nupkg\", StringComparison.OrdinalIgnoreCase))\r\n\t\t.ToList();\r\n\tvar skippable = new List\r\n\t{\r\n\t\t\"ReleaseNotes.md\", // skip always\r\n\t\t// \"Ocelot.24.0.0\",\r\n\t\t// \"Ocelot.Cache.CacheManager\",\r\n\t\t// \"Ocelot.Provider.Consul\",\r\n\t\t// \"Ocelot.Provider.Eureka\",\r\n\t\t// \"Ocelot.Provider.Kubernetes\",\r\n\t\t// \"Ocelot.Provider.Polly\",\r\n\t\t// \"Ocelot.Tracing.Butterfly\",\r\n\t\t// \"Ocelot.Tracing.OpenTracing\",\r\n\t};\r\n\tvar includedInTheRelease = new List\r\n\t{\r\n\t\t\"Ocelot.Provider.Kubernetes\",\r\n\t};\r\n\tforeach (var artifact in artifacts)\r\n\t{\r\n\t\tif (skippable.Exists(x => artifact.StartsWith(x, StringComparison.OrdinalIgnoreCase)))\r\n\t\t\tcontinue;\r\n\t\t// if (!includedInTheRelease.Exists(x => artifact.StartsWith(x))) continue;\r\n\r\n\t\tvar package = packagesDir + File(artifact);\r\n\t\tInformation($\"{nameof(PublishPackages)}: Pushing package \" + package + \"...\");\r\n\t\ttry\r\n\t\t{\r\n\t\t\tDotNetNuGetPush(package,\r\n\t\t\t\tnew DotNetNuGetPushSettings { ApiKey = feedApiKey, Source = codeFeedUrl, SkipDuplicate = true });\r\n\r\n\t\t\tvar symbolArtifact = artifact.Replace(\".nupkg\", \".snupkg\");\r\n\t\t\tvar symbolPackage = packagesDir + File(symbolArtifact);\r\n\t\t\tif (FileExists(symbolPackage))\r\n\t\t\t{\r\n\t\t\t\tInformation($\" Pushing symbol package {symbolPackage}...\");\r\n\t\t\t\tSystem.Threading.Thread.Sleep(1000);\r\n\t\t\t\ttry\r\n\t\t\t\t{\r\n\t\t\t\t\tDotNetNuGetPush(symbolPackage,\r\n\t\t\t\t\t\tnew DotNetNuGetPushSettings { ApiKey = feedApiKey, Source = codeFeedUrl, SkipDuplicate = true });\t\t\t\t\t\t\r\n\t\t\t\t}\r\n\t\t\t\tcatch (Exception symEx)\r\n\t\t\t\t{\r\n\t\t\t\t\tWarning($\" Symbol push failed: {symEx.Message}\");\r\n\t\t\t\t}\r\n\t\t\t}\r\n\t\t\telse\r\n\t\t\t{\r\n\t\t\t\tInformation($\" No symbol package found for {artifact}\");\r\n\t\t\t}\r\n\t\t}\r\n\t\tcatch (Exception ex)\r\n\t\t{\r\n\t\t\tInformation(\"--------------------------------------------------------------\");\r\n\t\t\tWarning(ex.ToString());\r\n\t\t\tthrow; // exit task with non-zero result -> failed step -> failed job in Actions\r\n\t\t}\r\n\t\t\t// catch (Exception ex)\r\n\t\t\t// {\r\n\t\t\t// \tWarning(ex.ToString());\r\n\t\t\t// \t// bool isConflict = ex.ToString().Contains(\"409\") || ex.ToString().Contains(\"Conflict\");\r\n\t\t\t// \tif (!isBeta /*|| !isConflict*/) throw;\r\n\r\n\t\t\t// \tvar match = Regex.Match(theArtifact, @\"-beta\\.(\\d+)(?=\\.nupkg$)\");\r\n\t\t\t// \tif (!match.Success)\r\n\t\t\t// \t{\r\n\t\t\t// \t\tWarning(\" No beta version found in the artifact name, but it should be there. Artifact: \" + theArtifact);\r\n\t\t\t// \t\tbreak;\r\n\t\t\t// \t}\r\n \t\t// \tvar betaNumber = match.Groups[1].Value;\r\n \t\t// \tInformation($\" Detected Beta number: {betaNumber}\");\r\n\t\t\t// \tint newBetaVer = int.Parse(betaNumber) + 1; // increase beta version by 1 trying to find the next free beta number\r\n\t\t\t// \tvar newArtifact = Regex.Replace(theArtifact, @\"-beta\\.\\d+(?=\\.nupkg$)\", \"-beta.\" + newBetaVer);\r\n\t\t\t// \tvar newPackage = packagesDir + File(newArtifact);\r\n\t\t\t// \tif (FileExists(newPackage)) DeleteFile(newPackage);\r\n\t\t\t// \tMoveFile(package, newPackage);\r\n\t\t\t// \tWarning($\" Package renamed: {package} -> {newPackage} (Attempt #{attempts})\");\r\n\t\t\t// \tvar oldSymbol = packagesDir + File(theArtifact.Replace(\".nupkg\", \".snupkg\"));\r\n\t\t\t// \tvar newSymbol = packagesDir + File(newArtifact.Replace(\".nupkg\", \".snupkg\"));\r\n\t\t\t// \tif (FileExists(oldSymbol))\r\n\t\t\t// \t{\r\n\t\t\t// \t\tif (FileExists(newSymbol)) DeleteFile(newSymbol);\r\n\t\t\t// \t\tMoveFile(oldSymbol, newSymbol);\r\n\t\t\t// \t}\r\n\t\t\t// \tpackage = newPackage;\r\n\t\t\t// \ttheArtifact = newArtifact;\t\t\t\t\r\n\t\t\t// \tSystem.Threading.Thread.Sleep(1000);\r\n\t\t\t// }\r\n\t}\r\n}\r\n\r\nprivate bool PackageExists(string packageId, string version)\r\n{\r\n\tvar url = $\"https://api.nuget.org/v3-flatcontainer/{packageId.ToLowerInvariant()}/{version}/{packageId.ToLowerInvariant()}.{version}.nupkg\";\r\n\ttry\r\n\t{\r\n\t\tvar response = HttpGet(url);\r\n\t\tInformation($\"{nameof(PackageExists)}: Package ver.{packageId}.{version} exists\");\r\n\t\treturn true;\r\n\t}\r\n\tcatch (Exception ex)\r\n\t{\r\n\t\tWarning(ex.ToString());\r\n\t\tInformation($\"{nameof(PackageExists)}: Package ver.{packageId}.{version} does NOT exist\");\r\n\t}\r\n\treturn false;\r\n}\r\n\r\nprivate void SetupGitHubClient(System.Net.Http.HttpClient client)\r\n{\r\n\tstring token = Environment.GetEnvironmentVariable(\"OCELOT_GITHUB_API_KEY\");\r\n\tclient.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue(\"Bearer\", token);\r\n\tclient.DefaultRequestHeaders.Add(\"User-Agent\", \"Ocelot Release\");\r\n\tclient.DefaultRequestHeaders.Add(\"Accept\", \"application/vnd.github+json\");\r\n\tclient.DefaultRequestHeaders.Add(\"X-GitHub-Api-Version\", \"2022-11-28\");\r\n}\r\n\r\nprivate dynamic CreateGitHubRelease()\r\n{\r\n\tvar body = ReleaseNotesAsJson();\r\n\tvar json = $\"{{ \\\"tag_name\\\": \\\"{versioning.NuGetVersion}\\\", \\\"target_commitish\\\": \\\"{versioning.BranchName}\\\", \\\"name\\\": \\\"{versioning.NuGetVersion}\\\", \\\"body\\\": \\\"{body}\\\", \\\"draft\\\": true, \\\"prerelease\\\": true, \\\"generate_release_notes\\\": false }}\";\r\n\tvar content = new System.Net.Http.StringContent(json, System.Text.Encoding.UTF8, \"application/json\");\r\n\r\n\tusing (var client = new System.Net.Http.HttpClient())\r\n\t{\t\r\n\t\tSetupGitHubClient(client);\r\n\t\tvar result = client.PostAsync(\"https://api.github.com/repos/ThreeMammals/Ocelot/releases\", content).Result;\r\n\t\tif (result.StatusCode != System.Net.HttpStatusCode.Created) \r\n\t\t{\r\n\t\t\tvar msg = \"CreateGitHubRelease: StatusCode = \" + result.StatusCode;\r\n\t\t\tInformation(msg);\r\n\t\t\tthrow new Exception(msg);\r\n\t\t}\r\n\t\tvar releaseData = result.Content.ReadAsStringAsync().Result;\r\n\t\tdynamic releaseJSON = Newtonsoft.Json.JsonConvert.DeserializeObject(releaseData);\r\n\t\tInformation(\"CreateGitHubRelease: Release ID is \" + releaseJSON.id);\r\n\t\treturn releaseJSON;\r\n\t}\r\n}\r\n\r\nprivate string ReleaseNotesAsJson()\r\n{\r\n\tvar body = _File_.ReadAllText(releaseNotesFile, System.Text.Encoding.UTF8);\r\n\treturn System.Text.Encodings.Web.JavaScriptEncoder.Default.Encode(body);\r\n}\r\n\r\nprivate void UploadFileToGitHubRelease(dynamic release, FilePath file)\r\n{\r\n\tvar data = _File_.ReadAllBytes(file.FullPath);\r\n\tvar content = new System.Net.Http.ByteArrayContent(data);\r\n\tcontent.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue(\"application/octet-stream\");\r\n\r\n\tusing (var client = new System.Net.Http.HttpClient())\r\n\t{\t\r\n\t\tSetupGitHubClient(client);\r\n\t\tint releaseId = release.id;\r\n\t\tvar fileName = file.GetFilename();\r\n\t\tstring uploadUrl = release.upload_url.ToString();\r\n\t\t// Information($\"UploadFileToGitHubRelease: uploadUrl is {uploadUrl}\");\r\n\t\tstring[] parts = uploadUrl.Replace(\"{\", \"\").Split(',');\r\n\t\tuploadUrl = parts[0] + \"=\" + fileName; // $\"https://uploads.github.com/repos/ThreeMammals/Ocelot/releases/{releaseId}/assets?name={fileName}\"\r\n\t\tInformation($\"UploadFileToGitHubRelease: uploadUrl is {uploadUrl}\");\r\n\t\tvar result = client.PostAsync(uploadUrl, content).Result;\r\n\t\tif (result.StatusCode != System.Net.HttpStatusCode.Created) \r\n\t\t{\r\n\t\t\tInformation($\"UploadFileToGitHubRelease: StatusCode is {result.StatusCode}. Release ID is {releaseId}. Failed to upload file '{fileName}' to URL: {uploadUrl}\");\r\n\t\t\tthrow new Exception(\"UploadFileToGitHubRelease: StatusCode is \" + result.StatusCode);\r\n\t\t}\r\n\t}\r\n}\r\n\r\nprivate void CompleteGitHubRelease(dynamic release)\r\n{\r\n\tint releaseId = release.id;\r\n\tstring url = release.url.ToString();\r\n\tstring body = ReleaseNotesAsJson();\r\n\tbool isPreRelease = !IsMainBranch();\r\n\tvar json = $\"{{ \\\"tag_name\\\": \\\"{versioning.NuGetVersion}\\\", \\\"target_commitish\\\": \\\"{versioning.BranchName}\\\", \\\"name\\\": \\\"{versioning.NuGetVersion}\\\", \\\"body\\\": \\\"{body}\\\", \\\"draft\\\": false, \\\"prerelease\\\": {isPreRelease.ToString().ToLower()} }}\";\r\n\tvar request = new System.Net.Http.HttpRequestMessage(new System.Net.Http.HttpMethod(\"Patch\"), url); // $\"https://api.github.com/repos/ThreeMammals/Ocelot/releases/{releaseId}\");\r\n\trequest.Content = new System.Net.Http.StringContent(json, System.Text.Encoding.UTF8, \"application/json\");\r\n\r\n\tusing (var client = new System.Net.Http.HttpClient())\r\n\t{\t\r\n\t\tSetupGitHubClient(client);\r\n\t\tvar result = client.SendAsync(request).Result;\r\n\t\tif (result.StatusCode != System.Net.HttpStatusCode.OK) \r\n\t\t{\r\n\t\t\tInformation($\"CompleteGitHubRelease: StatusCode is {result.StatusCode}. Release ID is {releaseId}. Failed to patch release with URL: {url}\");\r\n\t\t\tthrow new Exception(\"CompleteGitHubRelease: StatusCode = \" + result.StatusCode);\r\n\t\t}\r\n\t}\r\n}\r\n\r\n/// gets the resource from the specified url\r\nprivate async Task GetResourceAsync(string url)\r\n{\r\n\ttry\r\n\t{\r\n\t\tInformation(\"Getting resource from \" + url);\r\n\r\n\t\tusing var client = new System.Net.Http.HttpClient();\r\n\t\tclient.DefaultRequestHeaders.Accept.ParseAdd(\"application/vnd.github.v3+json\");\r\n\t\tclient.DefaultRequestHeaders.UserAgent.ParseAdd(\"BuildScript\");\r\n\r\n\t\tusing var response = await client.GetAsync(url);\r\n\t\tresponse.EnsureSuccessStatusCode();\r\n\t\tvar content = await response.Content.ReadAsStringAsync();\r\n\t\tInformation(\"Response is >>>\" + NL + content + NL + \"<<<\");\r\n\t\treturn content;\r\n\t}\r\n\tcatch(Exception exception)\r\n\t{\r\n\t\tInformation(\"There was an exception \" + exception);\r\n\t\tthrow;\r\n\t}\r\n}\r\n\r\nprivate bool IsRunningInCICD()\r\n\t=> IsRunningOnCircleCI() || IsRunningInGitHubActions();\r\nprivate bool IsRunningOnCircleCI()\r\n\t=> !string.IsNullOrWhiteSpace(Environment.GetEnvironmentVariable(\"CIRCLECI\"));\r\nprivate bool IsRunningInGitHubActions()\r\n\t=> Environment.GetEnvironmentVariable(\"GITHUB_ACTIONS\") == \"true\";\r\n\r\nprivate bool IsMainBranch()\r\n{\r\n\tvar br = GetBranchName().ToLower();\r\n return br == \"main\";\r\n}\r\nprivate string GetBranchName()\r\n{\r\n return versioning?.BranchName ?? GetGitBranch();\r\n}\r\nprivate string GetGitBranch()\r\n{\r\n\tvar lines = GitHelper(\"branch --show-current\");\r\n\tvar branch = string.Join(string.Empty, lines);\r\n\treturn branch ?? \"Unknown Branch\";\r\n}\r\n"
},
{
"path": "codeanalysis.ruleset",
"content": "\n\n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n \n"
},
{
"path": "codecov.yml",
"content": "coverage:\n status:\n project: #add everything under here, more options at https://docs.codecov.com/docs/commit-status\n default:\n target: auto\n threshold: 0%\n base: auto\n\ncomment:\n layout: \"reach, diff, flags, tree\"\n behavior: default\n\ngithub_checks:\n annotations: true\n"
},
{
"path": "coverlet.runsettings",
"content": "\n\n \n \n \n \n cobertura\n \n [Ocelot.Testing*]*\n \n false\n \n MissingAll\n \n \n \n \n\n"
},
{
"path": "docker/Dockerfile.base",
"content": "FROM mcr.microsoft.com/dotnet/sdk:9.0-alpine\n\nRUN apk add bash icu-libs krb5-libs libgcc libintl libssl3 libstdc++ zlib git openssh-client\n\n# Install .NET 8 SDK\nRUN curl -L --output ./dotnet-install.sh https://dot.net/v1/dotnet-install.sh\nRUN chmod u+x ./dotnet-install.sh \nRUN ./dotnet-install.sh -c 8.0 -i /usr/share/dotnet\n\n# Generate and export the development SSL certificate\nRUN mkdir -p /certs\nRUN dotnet dev-certs https -ep /certs/cert.pem -p ''\nRUN chmod 644 /certs/cert.pem\n\nENV ASPNETCORE_URLS=\"https://+;http://+\" \nENV ASPNETCORE_HTTPS_PORT=443 \nENV ASPNETCORE_Kestrel__Certificates__Default__Password=\"\" \nENV ASPNETCORE_Kestrel__Certificates__Default__Path=/certs/cert.pem\n"
},
{
"path": "docker/Dockerfile.build",
"content": "# call from ocelot repo root with\n# docker build --platform linux/arm64 --build-arg OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN -f ./docker/Dockerfile.build .\n# docker build --platform linux/amd64 --build-arg OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN -f ./docker/Dockerfile.build .\n\nFROM ocelot2/circleci-build:latest\n\nARG OCELOT_COVERALLS_TOKEN\n\nENV OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN\n\nWORKDIR /build\n\nCOPY ./. .\n\nRUN dotnet tool restore\n\nRUN\tdotnet cake\n"
},
{
"path": "docker/Dockerfile.release",
"content": "# call from ocelot repo root with\n# docker build --platform linux/arm64 --build-arg OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN --build-arg OCELOT_GITHUB_API_KEY=$OCELOT_GITHUB_API_KEY --build-arg OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN -f ./docker/Dockerfile.build .\n# docker build --platform linux/amd64 --build-arg OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN --build-arg OCELOT_GITHUB_API_KEY=$OCELOT_GITHUB_API_KEY --build-arg OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN -f ./docker/Dockerfile.build .\n\nFROM ocelot2/circleci-build:latest\n\nARG OCELOT_COVERALLS_TOKEN\nARG OCELOT_NUTGET_API_KEY\nARG OCELOT_GITHUB_API_KEY\n\nENV OCELOT_COVERALLS_TOKEN=$OCELOT_COVERALLS_TOKEN\nENV OCELOT_NUTGET_API_KEY=$OCELOT_NUTGET_API_KEY\nENV OCELOT_GITHUB_API_KEY=$OCELOT_GITHUB_API_KEY\n\nWORKDIR /build\n\nCOPY ./. .\n\nRUN dotnet tool restore\n\nRUN\tdotnet cake\n"
},
{
"path": "docker/Dockerfile.windows",
"content": "FROM mcr.microsoft.com/dotnet/sdk:9.0-nanoserver-ltsc2022\n\n# Install PowerShell globally AND RUN powershell -Command \"gci\"\n#RUN dotnet tool install -g powershell && pwsh -Command \"gci\"\nRUN pwsh -Command \"gci\"\n\n# # Install .NET 8 SDK\nUSER ContainerAdministrator\nRUN pwsh -Command \"Invoke-WebRequest -OutFile dotnet-install.ps1 https://dot.net/v1/dotnet-install.ps1; gci\"\nENV DOTNET_GENERATE_ASPNET_CERTIFICATE=true\nRUN pwsh -Command \"./dotnet-install.ps1 -Channel 8.0 -InstallDir 'C:\\Program Files\\dotnet\\'; gci -Path C:\\\\ -Recurse -Include *8.0* -Directory\"\n\n#RUN git status\nRUN dotnet --info\n\n# Generate and export the development SSL certificate\n#RUN mkdir -p certs\n#RUN dotnet dev-certs https -ep certs/cert.pem -p ''\n#RUN pwsh -Command \"dotnet dev-certs https --clean; dotnet dev-certs https; exit 0;\"\n#RUN pwsh -Command \"dotnet dev-certs https --trust; exit 0;\"\nRUN pwsh -Command \"dotnet dev-certs https --check --trust; exit 0;\"\n\n#ENV ASPNETCORE_URLS=\"https://+;http://+\" ASPNETCORE_HTTPS_PORT=443\n#ENV ASPNETCORE_Kestrel__Certificates__Default__Password=\"\" ASPNETCORE_Kestrel__Certificates__Default__Path=certs/cert.pem\n"
},
{
"path": "docker/README.md",
"content": "# docker build\r\n\r\nThis folder contains the `Dockerfile.*` and `build-*.sh` scripts to create the Ocelot build image & container.\r\n\r\n## Account\r\n- Docker Hub | [Ocelot Gateway](https://hub.docker.com/u/ocelot2)\r\n\r\n## Repositories\r\n- [circleci-build](https://hub.docker.com/r/ocelot2/circleci-build)\r\n\r\n## Outdated Tags\r\n- [8.21.0](https://hub.docker.com/layers/ocelot2/circleci-build/8.21.0/images/sha256-edb46d37ab52d39a5b27dc63895e5944d4d491d1788744ed144ecb4303b94532?context=explore), uploaded on Nov 20, 2023. It contains .NET 8, 7 and 6 SDKs. It supports builds for `net6.0`, `net7.0` and `net8.0` frameworks.\r\n- [8.23.2](https://hub.docker.com/layers/ocelot2/circleci-build/8.23.2/images/sha256-981d6f9e6e5ba54f6e044bca6fcf8b5197a8f3e6ce2b3cdfa9e6704ecd2ca969?context=explore), uploaded on Apr 3, 2024. It supports development SSL certificates by the command `dotnet dev-certs https`.\r\n- [latest](https://hub.docker.com/layers/ocelot2/circleci-build/latest/images/sha256-981d6f9e6e5ba54f6e044bca6fcf8b5197a8f3e6ce2b3cdfa9e6704ecd2ca969?context=explore) is version 8.23.2, uploaded on Apr 3, 2024.\r\n\r\n## .NET 8-9 Tags\r\n\r\n### Single SDK Tags\r\n- [sdk-8-alpine-lin.net8](https://hub.docker.com/layers/ocelot2/circleci-build/sdk-8-alpine-lin.net8/images/sha256-17c21438771641ba2a3320a6c13fe756a851d707a925188d9616485bfc757b22?context=explore), uploaded on Dec 3, 2024. This Linux OS image contains .NET 8 SDK only. It supports builds for `net8.0` framework.\r\n- [sdk-9-alpine-lin.net9](https://hub.docker.com/layers/ocelot2/circleci-build/sdk-9-alpine-lin.net9/images/sha256-c20d82a52c1a7eebf86bcd32751960ae189e6c50575959ee0499b1d88541c9ea?context=explore), uploaded on Dec 3, 2024. This Linux OS image contains .NET 9 SDK only. It supports builds for `net9.0` framework.\r\n- [sdk8-nanoserver2022-win.net8](https://hub.docker.com/layers/ocelot2/circleci-build/sdk8-nanoserver2022-win.net8/images/sha256-20f21f4361d18301bc885e1f01ebefcd6b024802130db1296173cdfaac5d75e6?context=explore), uploaded on Dec 3, 2024. This Windows OS image contains .NET 8 SDK only. It supports builds for `net8.0` framework.\r\n- [sdk9-nano2022-win.net9](https://hub.docker.com/layers/ocelot2/circleci-build/sdk9-nano2022-win.net9/images/sha256-37b718885f8cfb3480299f48044836f01aec2370e331667dd1811a4c94a4ce45?context=explore), uploaded on Dec 3, 2024. This Windows OS image contains .NET 9 SDK only. It supports builds for `net9.0` framework.\r\n\r\n### Double SDKs Tags\r\n- [sdk9-alpine-lin.net8-9](https://hub.docker.com/layers/ocelot2/circleci-build/sdk9-alpine-lin.net8-9/images/sha256-707924d144248178caff80578649f7d0e9b7c70ed51b6fb5171170c9a30a4eae?context=explore) aka [9.24.0](https://hub.docker.com/layers/ocelot2/circleci-build/9.24.0/images/sha256-707924d144248178caff80578649f7d0e9b7c70ed51b6fb5171170c9a30a4eae?context=explore), uploaded on Dec 3, 2023. This Linux OS image contains .NET 8 and 9 SDKs. It supports builds for `net8.0` and `net9.0` frameworks.\r\n- [sdk9-nano2022-win.net8-9](https://hub.docker.com/layers/ocelot2/circleci-build/sdk9-nano2022-win.net8-9/images/sha256-6e44a8fc52ab091ea43090b6ab182f7a05d7ac31402ce742a7e035323e584cf7?context=explore) aka [9.24.win](https://hub.docker.com/layers/ocelot2/circleci-build/9.24.win/images/sha256-6e44a8fc52ab091ea43090b6ab182f7a05d7ac31402ce742a7e035323e584cf7?context=explore), uploaded on Dec 4, 2023. This Windows OS image contains .NET 8 and 9 SDKs. It supports builds for `net8.0` and `net9.0` frameworks.\r\n\r\n### Links\r\n- Docker Hub | [Microsoft dotnet Images](https://hub.docker.com/r/microsoft/dotnet)\r\n- GitHub | dotnet-docker | [.NET SDK](https://github.com/dotnet/dotnet-docker/blob/main/README.sdk.md)\r\n- StackOverflow | [PowerShell and process exit codes](https://stackoverflow.com/questions/57468522/powershell-and-process-exit-codes)\r\n"
},
{
"path": "docker/build-windows.sh",
"content": "version=9.24.win\ntag=sdk9-nano2022-win.net8-9\n\ndocker build --no-cache --platform windows/amd64 -t ocelot2/circleci-build -f Dockerfile.windows .\n\ndocker tag ocelot2/circleci-build ocelot2/circleci-build:$tag\ndocker push ocelot2/circleci-build:$tag\n\ndocker tag ocelot2/circleci-build ocelot2/circleci-build:$version\ndocker push ocelot2/circleci-build:$version\n"
},
{
"path": "docker/build.sh",
"content": "# This script builds the Ocelot Docker file\n# echo $DOCKER_PASS | docker login -u $DOCKER_USER --password-stdin\n\n# {DotNetSdkVer}.{OcelotVer} -> {.NET9}.{24.0} -> 9.24.0\n#version=9.24.0\ntag=sdk9-alpine-lin.net8-9\n\ndocker build --platform linux/amd64 -t ocelot2/circleci-build -f Dockerfile.base .\ndocker tag ocelot2/circleci-build ocelot2/circleci-build:$tag\ndocker push ocelot2/circleci-build:$tag\n# docker tag ocelot2/circleci-build ocelot2/circleci-build:$version\n# docker push ocelot2/circleci-build:$version\n"
},
{
"path": "docker/outdated/Dockerfile.8.21.0.base",
"content": "FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine\n\nRUN apk add bash icu-libs krb5-libs libgcc libintl libssl1.1 libstdc++ zlib git openssh-client\n\nRUN curl -L --output ./dotnet-install.sh https://dot.net/v1/dotnet-install.sh\n\nRUN chmod u+x ./dotnet-install.sh \n\n# Install .NET 8 SDK (already included in the base image, but listed for consistency)\nRUN ./dotnet-install.sh -c 8.0 -i /usr/share/dotnet\n\n# Install .NET 7 SDK\nRUN ./dotnet-install.sh -c 7.0 -i /usr/share/dotnet\n\n# Install .NET 6 SDK\nRUN ./dotnet-install.sh -c 6.0 -i /usr/share/dotnet\n"
},
{
"path": "docker/outdated/Dockerfile.8.23.2.base",
"content": "FROM mcr.microsoft.com/dotnet/sdk:8.0-alpine\n\nRUN apk add bash icu-libs krb5-libs libgcc libintl libssl3 libstdc++ zlib git openssh-client\n\nRUN curl -L --output ./dotnet-install.sh https://dot.net/v1/dotnet-install.sh\n\nRUN chmod u+x ./dotnet-install.sh \n\n# Install .NET 8 SDK (already included in the base image, but listed for consistency)\nRUN ./dotnet-install.sh -c 8.0 -i /usr/share/dotnet\n\n# Install .NET 7 SDK\nRUN ./dotnet-install.sh -c 7.0 -i /usr/share/dotnet\n\n# Install .NET 6 SDK\nRUN ./dotnet-install.sh -c 6.0 -i /usr/share/dotnet\n\n# Generate and export the development certificate\nRUN dotnet dev-certs https -ep /certs/cert.pem -p '' && \\\n chmod 644 /certs/cert.pem\n\nENV ASPNETCORE_URLS=\"https://+;http://+\" \nENV ASPNETCORE_HTTPS_PORT=443 \nENV ASPNETCORE_Kestrel__Certificates__Default__Password=\"\" \nENV ASPNETCORE_Kestrel__Certificates__Default__Path=/certs/cert.pem\n"
},
{
"path": "docs/Makefile",
"content": "# Minimal makefile for Sphinx documentation\n#\n\n# You can set these variables from the command line, and also\n# from the environment for the first two.\nSPHINXOPTS ?=\nSPHINXBUILD ?= sphinx-build\nSOURCEDIR = .\nBUILDDIR = _build\n\n# Put it first so that \"make\" without argument is like \"make help\".\nhelp:\n\t@$(SPHINXBUILD) -M help \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n\n.PHONY: help Makefile\n\n# Catch-all target: route all unknown targets to Sphinx using the new\n# \"make mode\" option. $(O) is meant as a shortcut for $(SPHINXOPTS).\n%: Makefile\n\t@$(SPHINXBUILD) -M $@ \"$(SOURCEDIR)\" \"$(BUILDDIR)\" $(SPHINXOPTS) $(O)\n"
},
{
"path": "docs/_static/overrides.css",
"content": "blockquote {\n font-size: 0.9em;\n}\naside.footnote-list {\n font-size: 0.9em;\n}\n.img-valign-middle\n{\n vertical-align: middle;\n}\n.img-valign-bottom\n{\n vertical-align: bottom;\n}\n.img-valign-textbottom\n{\n vertical-align: text-bottom;\n}\n"
},
{
"path": "docs/building/building.rst",
"content": ".. role:: htm(raw)\n :format: html\n.. role:: pdf(raw)\n :format: latex pdflatex\n.. _Ocelot: https://github.com/ThreeMammals/Ocelot\n.. _Cake: https://cakebuild.net\n.. _Bash: https://www.gnu.org/software/bash\n.. _build.cake: https://github.com/ThreeMammals/Ocelot/blob/main/build.cake\n.. _GitHub Actions: https://docs.github.com/en/actions\n.. _NuGet: https://www.nuget.org/profiles/ThreeMammals\n\nBuilding\n========\n\nThis document summarises the build and release process for the `Ocelot`_ project.\nThe build scripts are written using `Cake`_ (C# Make), with relevant build tasks defined in the '`build.cake`_' file located in the root of the `Ocelot`_ project.\nThe scripts are designed to be run by developers locally in a `Bash`_ terminal (on any OS), in Command Prompt (CMD) or PowerShell consoles (on Windows OS),\nor by a CI/CD server (currently `GitHub Actions`_), with minimal logic defined in the build server itself.\n\nThe final goal of the build process is to create ``Ocelot.*`` `NuGet`_ packages (.nupkg files) for redistribution via the `NuGet`_ repository or manually.\nThe build process consists of several steps: (1) compilation, (2) testing, (3) creating and publishing `NuGet`_ packages, and (4) making an official GitHub release.\nThe build process requires pre-installed .NET SDKs on the build machine (host) for all target framework monikers: TFMs are ``net8.0`` and ``net9.0`` currently.\nIn general, the build process is the same across all environments and tools, with a few differences described below.\n\n.. _b-in-ide:\n\nIn IDE\n------\n.. _Release configuration: https://learn.microsoft.com/en-us/visualstudio/debugger/how-to-set-debug-and-release-configurations?view=vs-2022\n\nIn an IDE, a DevOps engineer can build the project in Visual Studio IDE or another IDE in `Release configuration`_ mode, but the latest .NET 8/9 SDKs must be pre-installed on the local machine.\nHowever, this approach is not practical because the generated '.nupkg' files must be uploaded to `NuGet`_ manually, and the GitHub release must also be created manually.\nA better approach is to utilize the '`build.cake`_' script :ref:`b-in-terminal`, which covers all building scenarios.\n\n.. _b-in-terminal:\n\nIn terminal\n-----------\n.. _./: https://github.com/ThreeMammals/Ocelot/tree/main/\n\n Folder: `./`_\n\nThese are local machine or remote server building scenarios using build scripts, aka '`build.cake`_'.\nIn these scenarios, the following two commands should be run in a terminal from the project's root folder:\n\n.. code-block:: shell\n\n dotnet tool restore && dotnet cake # In Bash terminal\n dotnet tool restore; dotnet cake # In PowerShell terminal\n\n.. _break: http://break.do\n\n **Note**: The default target task (\"Default\") is \"Build\", and output files will be stored in the ``./artifacts`` directory.\n\nTo run a desired target task, you need to specify its *name*:\n\n.. code-block:: shell\n\n dotnet tool restore && dotnet cake --target=name # In Bash terminal\n dotnet tool restore; dotnet cake --target=name # In PowerShell terminal\n\nFor example,\n\n- .. code-block:: shell\n\n dotnet cake --target=Build\n\n It runs a local build, performing compilation and testing only.\n\n- .. code-block:: shell\n\n dotnet cake --target=Version\n \n It checks the next version to be tagged in the Git repository during the next release, without performing compilation or testing tasks.\n\n- .. code-block:: shell\n\n dotnet cake --target=CreateReleaseNotes\n \n It generates Release Notes artifacts in the ``/artifacts/Packages`` folder using the ``ReleaseNotes.md`` template file.\n\n- .. code-block:: shell\n\n dotnet cake --target=Release\n\n It creates a release, consisting of the following steps: compilation, testing, generating release notes, creating .nupkg files, publishing `NuGet`_ packages, and finally, making a GitHub release.\n\n.. _dotnet-tools.json: https://github.com/ThreeMammals/Ocelot/blob/main/.config/dotnet-tools.json\n\n **Note 1**: The building tools for the ``dotnet tool restore`` command are configured in the `dotnet-tools.json`_ file.\n\n **Note 2**: Some targets (build tasks) require appropriate environment variables to be defined directly in the terminal session (aka secret tokens).\n\n.. _b-with-docker:\n\nWith Docker\n-----------\n.. _docker: https://github.com/ThreeMammals/Ocelot/tree/main/docker\n.. _Dockerfile.build: https://github.com/ThreeMammals/Ocelot/blob/main/docker/Dockerfile.build\n.. _24.0: https://github.com/ThreeMammals/Ocelot/releases/tag/24.0.0\n\n Folder: ./`docker`_\n\nThe best way to replicate the CI/CD process and build `Ocelot`_ locally is by using the `Dockerfile.build`_ file, which can be found in the '`docker`_' folder in the `Ocelot`_ root directory.\nFor example, use the following command:\n\n.. code-block:: shell\n\n docker build --platform linux/amd64 -f ./docker/Dockerfile.build .\n\nYou may need to adjust the platform flag depending on your system.\n\n **Note**: This approach is somewhat excessive, but it will work if you are a masterful Docker user. 🙂\n The Ocelot team has not followed this approach since version `24.0`_, favoring :ref:`b-with-ci-cd`-based builds and occasionally building :ref:`b-in-terminal` instead.\n\n.. _b-with-ci-cd:\n\nWith CI/CD\n----------\n.. _workflows: https://github.com/ThreeMammals/Ocelot/tree/main/.github/workflows \n.. _PR: https://github.com/ThreeMammals/Ocelot/actions/workflows/pr.yml\n.. _Develop: https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml\n.. _Release: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml\n.. _Coveralls: https://coveralls.io\n.. |ReleaseButton| image:: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml/badge.svg\n :target: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml\n :alt: Release Status\n :class: img-valign-textbottom\n.. |DevelopButton| image:: https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml/badge.svg\n :target: https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml\n :alt: Development Status\n :class: img-valign-textbottom\n.. |DevelopCoveralls| image:: https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg?branch=develop\n :target: https://coveralls.io/github/ThreeMammals/Ocelot?branch=develop\n :alt: Coveralls Status\n :class: img-valign-textbottom\n.. |ReleaseCoveralls| image:: https://coveralls.io/repos/github/ThreeMammals/Ocelot/badge.svg?branch=main\n :target: https://coveralls.io/github/ThreeMammals/Ocelot?branch=main\n :alt: Coveralls Status\n :class: img-valign-textbottom\n.. _break2: http://break.do\n\n | Folder: ./.github/`workflows`_\n | Provider: `GitHub Actions`_\n | Workflows: `PR`_, `Develop`_, `Release`_\n | Dashboard: `Workflow runs `_ (Actions tab)\n\nThe `Ocelot`_ project utilizes `GitHub Actions`_ as a CI/CD provider, offering seamless integrations with the GitHub ecosystem and APIs.\nStarting from version `24.0`_, all pull requests, development commits, and releases are built using `GitHub Actions`_ workflows.\nThere are three `workflows`_: one for pull requests (`PR`_), one for the ``develop`` branch (`Develop`_), and one for the ``main`` branch (`Release`_).\n\n **Note**: Each workflow has a dedicated status badge in the `Ocelot README`_:\n the |ReleaseButton|:pdf:`\\href{https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml}{Release}` button and\n the |DevelopButton|:pdf:`\\href{https://github.com/ThreeMammals/Ocelot/actions/workflows/develop.yml}{Develop}` button,\n with the `PR`_ status being published directly in a pull request under the \"Checks\" tab.\n\nThe `PR`_ workflow will track code coverage using `Coveralls`_.\nAfter opening a pull request or submitting a new commit to a pull request, `Coveralls`_ will publish a short message with the current code coverage once the top commit is built.\nConsidering that `Coveralls`_ retains the entire history but does not fail the build if coverage falls below the threshold, all workflows have a built-in 80% threshold,\napplied internally within the ``build-cake`` job, particularly during the \"`Cake Build`_\" step-action.\nIf the code coverage of a newly opened pull request drops below the 80% threshold, the `'build-cake' job`_ will fail, logging an appropriate message in the \"`Cake Build`_\" step.\n\n **Note 1**: There are special code coverage badges in `Ocelot README`_: the `Develop`_ |DevelopCoveralls| button and the `Release`_ |ReleaseCoveralls| button.\n\n **Note 2**: The current code coverage of the `Ocelot`_ project is around 85-86%. The coverage threshold is subject to change in upcoming releases.\n All `Coveralls`_ builds can be viewed by navigating to the `ThreeMammals/Ocelot `_ project on Coveralls.io.\n\nDocumentation\n-------------\n.. _docs: https://github.com/ThreeMammals/Ocelot/tree/main/docs\n.. _.readthedocs.yaml: https://github.com/ThreeMammals/Ocelot/blob/main/.readthedocs.yaml\n.. _Read the Docs: https://about.readthedocs.com\n.. _Ocelot app: https://app.readthedocs.org/projects/ocelot/\n.. _README: https://github.com/ThreeMammals/Ocelot/blob/main/docs/readme.md\n.. _Ocelot README: https://github.com/ThreeMammals/Ocelot/blob/main/README.md\n.. |ReleaseDocs| image:: https://readthedocs.org/projects/ocelot/badge/?version=latest&style=flat-square\n :target: https://app.readthedocs.org/projects/ocelot/builds/?version__slug=latest\n :alt: ReadTheDocs Status\n :class: img-valign-middle\n.. |DevelopDocs| image:: https://readthedocs.org/projects/ocelot/badge/?version=develop&style=flat-square\n :target: https://app.readthedocs.org/projects/ocelot/builds/?version__slug=develop\n :alt: ReadTheDocs Status\n :class: img-valign-middle\n.. _break3: http://break.do\n\n | Folder: ./`docs`_\n | Dashboard: `Ocelot app`_ project\n\nDocumentation building is configured using the '`.readthedocs.yaml`_' integration file, which allows builds to run separately via the `Read the Docs`_ publisher.\nAll build artifacts and document sources are located in the '`docs`_' folder.\nMore details on the documentation build process can be found in the `README`_.\n\n **Note 1**: Documentation builds have a dedicated status badges in `Ocelot README`_: the `Develop`_ |DevelopDocs| button and the `Release`_ |ReleaseDocs| button.\n\n **Note**: Documentation can be easily built locally in a terminal from the '`docs`_' folder by running the ``make.sh`` or ``make.bat`` scripts.\n The resulting documentation build files will be located in the ``./docs/_build`` folder, with the HTML documentation specifically written to the ``./docs/_build/html`` folder.\n\n.. _b-testing:\n\nTesting\n-------\n\nThe tests should run and function correctly as part of the *building* process using the ``dotnet test`` command.\nYou can also run them in Visual Studio IDE within the Test Explorer window.\nDepending on your build scenario, `Ocelot`_ *testing* can be performed as follows.\n\n:ref:`b-in-ide`: Simply run tests via the Test Explorer window of Visual Studio IDE.\n\n:ref:`b-in-terminal`: There are two main approaches:\n\n1. Run the ``dotnet test`` command to perform all tests (unit, integration, and acceptance):\n\n .. code-block:: shell\n\n dotnet test -f net8.0 ./Ocelot.sln\n\n Or run tests separately per project:\n\n .. code-block:: shell\n\n dotnet test -f net8.0 ./test/Ocelot.UnitTests/Ocelot.UnitTests.csproj # Unit tests only\n dotnet test -f net8.0 ./test/Ocelot.IntegrationTests/Ocelot.IntegrationTests.csproj # Integration tests only\n dotnet test -f net8.0 ./test/Ocelot.AcceptanceTests/Ocelot.AcceptanceTests.csproj # Acceptance tests only\n\n2. Run ``dotnet cake`` command: ``dotnet cake --target=Tests`` to perform all tests (unit, integration and acceptance).\n Or run tests separately per *testing* project:\n\n .. code-block:: shell\n\n dotnet cake --target=UnitTests # unit tests only\n dotnet cake --target=IntegrationTests # integration tests only\n dotnet cake --target=AcceptanceTests # acceptance tests only\n\n:ref:`b-with-docker`: This approach is not recommended.\nInstead, perform automated testing :ref:`b-with-ci-cd` or opt for :ref:`b-in-terminal`-based testing, which is a more advanced method.\n\n:ref:`b-with-ci-cd`: In `GitHub Actions`_ `workflows`_, the *testing* process consists of separate testing steps, organized per job:\n\n* In the `'build' job`_: There are '`Unit Tests`_', '`Integration Tests`_', and '`Acceptance Tests`_' steps.\n* In the `'build-cake' job`_: There is a '`Cake Build`_' step responsible for performing tests internally.\n\n.. _'build' job: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+build%3A+path%3A%2F%5E%5C.github%5C%2Fworkflows%5C%2F%2F&type=code\n.. _Unit Tests: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22Unit+Tests%22+path%3A%2F%5E%5C.github%5C%2Fworkflows%5C%2F%2F&type=code\n.. _Integration Tests: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22Integration+Tests%22+path%3A%2F%5E%5C.github%5C%2Fworkflows%5C%2F%2F&type=code\n.. _Acceptance Tests: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22Acceptance+Tests%22+path%3A%2F%5E%5C.github%5C%2Fworkflows%5C%2F%2F&type=code\n.. _'build-cake' job: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22-cake%3A%22+path%3A%2F%5E%5C.github%5C%2Fworkflows%5C%2F%2F&type=code\n.. _Cake Build: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22cake-build%2F%22+path%3A%2F%5E%5C.github%5C%2Fworkflows%5C%2F%2F&type=code\n\nSSL certificate\n---------------\n\nTo create a certificate for :ref:`b-testing`, you can use `OpenSSL `_:\n\n* Install the `openssl `__ package (if you are using Windows, download the binaries `here `_).\n* Generate a private key:\n\n .. code-block:: bash\n\n openssl genrsa 2048 > private.pem\n\n* Generate a self-signed certificate:\n\n .. code-block:: bash\n\n openssl req -x509 -days 1000 -new -key private.pem -out public.pem\n\n* If needed, create a PFX file:\n\n .. code-block:: bash\n\n openssl pkcs12 -export -in public.pem -inkey private.pem -out mycert.pfx\n\n"
},
{
"path": "docs/building/devprocess.rst",
"content": ".. _Gitflow Workflow: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow\n.. _GitHub Flow: https://docs.github.com/en/get-started/using-github/github-flow\n.. _develop: https://github.com/ThreeMammals/Ocelot/tree/develop\n.. _main: https://github.com/ThreeMammals/Ocelot/tree/main\n.. _issue(s): https://github.com/ThreeMammals/Ocelot/issues\n.. _discussion: https://github.com/ThreeMammals/Ocelot/discussions\n.. _fork: https://docs.github.com/en/get-started/quickstart/fork-a-repo\n.. _unit: https://github.com/ThreeMammals/Ocelot/tree/develop/test/Ocelot.UnitTests\n.. _acceptance: https://github.com/ThreeMammals/Ocelot/tree/develop/test/Ocelot.AcceptanceTests\n.. _documentation: https://github.com/ThreeMammals/Ocelot/tree/develop/docs\n.. _feature: https://github.com/ThreeMammals/Ocelot/tree/develop/docs/features\n.. _Actions: https://github.com/ThreeMammals/Ocelot/actions\n.. _Coveralls check: https://coveralls.io/github/ThreeMammals/Ocelot\n\nDevelopment Process\n===================\n\n* The *development process* is optimized when using Gitflow branching, as detailed here: `Gitflow Workflow`_.\n It's important to note that the Ocelot team does not utilize `GitHub Flow`_, which, despite being quicker, does not align with the efficiency required for Ocelot's delivery.\n* Contributors are free to manage their pull requests and feature branches as they see fit to contribute to the '`develop`_' branch.\n* Maintainers have the autonomy to handle pull requests and merges. Any merges to the '`main`_' branch will trigger the release of packages to GitHub and NuGet.\n* In conclusion, while users should adhere to the guidelines in :doc:`../building/devprocess`, maintainers should follow the procedures outlined in :doc:`../building/releaseprocess`.\n\nStages\n------\n\nOcelot project follows this *development process* to integrate work into a merged commit in the '`develop`_' branch:\n\n1. Users either create a new issue or select an existing `issue(s)`_ on GitHub.\n Issues can also be generated from `discussion`_ topics when necessary and agreed upon.\n\n2. Users should create a `fork`_ and branch off of it (unless they are a core team member, in which case they can branch directly from the main/head/upstream repository), e.g., ``feature/xxx``, ``bug/xxx``, etc.\n The \"xxx\" can be the issue number or a brief description.\n\n3. Once contributors are satisfied with their work, they can submit a pull request against the `develop`_ branch on GitHub with their changes.\n\n4. The Ocelot team will review the pull request and, if satisfactory, merge it; otherwise, they will provide feedback for the contributor to address.\n To expedite pull request approval, contributors should consider:\n\n - Ensuring all changes are covered by `unit`_ and `acceptance`_ tests.\n - Ensuring that the code coverage percentage from `unit`_ tests does not decrease; thus, the `Coveralls check`_ reports a green status.\n - Updating any `documentation`_ affected by the changes, with a required review of the appropriate `feature`_ document.\n - Verifying that the feature is necessary and does not duplicate existing Ocelot features.\n\n5. A pull request must meet the following criteria before merging:\n\n - All new code must be covered by `unit`_ tests.\n - There must be at least one `acceptance`_ test for the happy path of the new code.\n - Tests must pass locally, in Visual Studio Test Explorer or in terminal after performing ``dotnet test`` command.\n - The build must have a green status on repository `Actions`_ as passed *checks* of the pull request (aka `Checks`_ tab).\n - The build's performance must not be significantly degraded on repository `Actions`_ page for `PR`_ workflow.\n - The main `Ocelot package`_ must not introduce any non-Microsoft `dependencies`_.\n\n.. _PR: https://github.com/ThreeMammals/Ocelot/actions/workflows/pr.yml\n.. _Checks: https://github.com/ThreeMammals/Ocelot/pull/2283/checks\n.. _Ocelot package: https://www.nuget.org/packages/Ocelot\n.. _dependencies: https://www.nuget.org/packages/Ocelot#dependencies-body-tab\n.. _NuGet packages: https://www.nuget.org/profiles/ThreeMammals\n\n6. Once the pull request is merged with *\"Squash and Merge\"* option into the `develop`_ branch, the ``Ocelot.*`` `NuGet packages`_ will not be updated until a release is crafted.\n The concluding step involves returning to GitHub to close any resolved `issue(s)`_.\n\nNotes\n-----\n\n**Note 1**: The `issue(s)`_ linked to the pull request within the *Development* settings (on the right sidebar of the pull request settings) will automatically close upon merging.\nIt is crucial for developers to utilize the *\"Link an issue from this repository\"* feature in the *Development* settings.\nAn alternative way to link `issue(s)`_ is by specifying them in the pull request description, where the developer lists the linked `issue(s)`_ that need to be closed.\nFor example:\n\n.. code-block:: markdown\n\n ## Fixes #1222\n - #1222\n\n ## Closes #1333\n - #1333\n\n ## Proposed Changes\n - change 1\n - change 2 \n\nThis Markdown should automatically link the desired bug/issue in the open status.\nFor bugs, the developer needs to write \"Fixes #xxxx\", and for features, \"Closes #xxxx\".\n\n.. _GitHub Actions: https://docs.github.com/en/actions\n.. _workflows: https://github.com/ThreeMammals/Ocelot/tree/main/.github/workflows \n\n**Note 2**: All pull request builds are conducted using `GitHub Actions`_, but developers have the freedom to build Ocelot as needed.\nDetails can be found in the :doc:`../building/building` chapter.\nAdditionally, for a deeper understanding of the current Ocelot CI/CD environment and a clearer view of the CI/CD build process, refer to the \"Building :ref:`b-with-ci-cd`\" section.\n\n**Note 3**: Should you encounter any confusion or obstacles, do not hesitate to reach out to the members of the 'Ocelot Team' or the repository maintainers.\n\n.. _dev-best-practices:\n\nBest Practices\n--------------\n* Refer to the Ocelot `Actions`_ dashboard on GitHub to verify the latest build statuses for the three current `workflows`_.\n It is recommended to monitor the build status of each workflow on the `Actions`_ dashboard or directly in the `Checks`_ tab of a pull request.\n If a build fails, initiate a new build by pushing a new commit, or consult with online maintainers or code reviewers to ensure the current pull request build is successful.\n* Request a code review after reaching the \"Development Complete\" stage, and address all feedback issues.\n Code is deemed complete when robust code, relevant `unit`_ and `acceptance`_ tests, and `documentation`_ updates are in place.\n* Set up your development environment on Windows OS using Visual Studio IDE.\n While development in Linux OS with alternative IDEs is possible, it is not recommended. For more details, refer to the :ref:`dev-fun` section.\n* Remain online after submitting a pull request/issue to ensure maintainers can reach you promptly.\n Note that if you are offline for extended periods, such as days, weeks, or months, maintainers may deprioritize your work.\n A strong contribution ethic implies constant online presence and proactivity.\n\n.. _dev-fun:\n\nDev Fun\n-------\n\nThis section is part of the :ref:`dev-best-practices` and is written to be more amusing D)\n\nEOL Gotchas\n^^^^^^^^^^^\n\n *Also known as, \"Line-Endings problem\"*\n\n Since the project's inception in 2016, this issue has been persistent.\n Indeed, some lines end with the ``LF`` character, typical of the Linux OS.\n Many of our contributors work on Linux and use IDEs like Visual Studio Code, JetBrains .NET Rider, which defaults to the ``LF`` as the newline character.\n As a result, we have numerous files with inconsistent or mixed EOL characters.\n\nThis problem stems from the well-known dilemma of End-of-Line (EOL) characters in cross-OS development.\nFor the Windows OS, the EOL character is ``CRLF``, while for Linux, it is ``LF``.\nModern IDEs and Git repositories have their own strategies for detecting inconsistencies of mixed EOLs in source files.\nHowever, the GitHub \"Files Changed\" tool unfortunately registers a line change in two scenarios: ``CRLF`` to ``LF`` and ``LF`` to ``CRLF``, even when there's no actual code change!\nReviewing such pull requests with fictitious (\"fake\") changes is always challenging because the reviewer's focus should be on actual code changes.\n\n Please note, if a pull request is filled with \"fake\" changes in *\"Files Changed\"*, the code reviewer has the right to not provide a code review, mark the PR as a draft, or even close it.\n\nOur standard practice is to maintain end-of-line characters as they are.\nMoreover, we utilize Visual Studio's unique ``.editorconfig`` IDE analyzer settings for EOL to avoid issues with line endings.\nThese settings are specific to Visual Studio, hence we recommend rebasing a feature branch onto develop using Visual Studio exclusively.\n\n Special EOL settings can be specified in the ``.gitattributes`` file of the git repository, although we do not currently manage this.\n\nOur current recommendations for addressing the end-of-line (EOL) issue are as follows:\n\n* Ideally, resolve merge conflicts by prioritizing the changes in the `develop`_ branch, then manually incorporate your changes in the merge tool dialog.\n It appears that changes from the feature branch are being included, even if they are minor.\n Conflicts should be addressed by manually applying your changes to the `develop`_ branch with a merge tool.\n\n* If changes from the feature branch are given priority (despite being minor), the merge tool will document them and apply ``CRLF`` end-of-line characters according to the rules specified in ``.editorconfig``.\n This is the source of the issue.\n\n* Renaming a method in an IDE, such as Visual Studio, or using another auto-refactoring command, causes Visual Studio to apply the command using the default styling rules in ``.editorconfig``, which includes `CRLF settings `_.\n Thus, applying auto-refactoring commands inadvertently alters the EOL characters, leading to \"fake\" changes in pull requests.\n Note that Visual Studio analyzers (IDE, StyleCop, etc.) may also recommend auto-refactoring, which could be applied implicitly.\n To preserve the original EOL characters, manual code editing is necessary.\n Therefore, \"fake\" changes result from auto-refactoring commands in IDEs like Visual Studio, Visual Code, Rider, etc.\n\n* **Our final recommendation** is to boot into Windows, use Visual Studio Community (which is free), refrain from using auto-refactoring commands, and ensure that EOLs remain unchanged.\n If your OS differs, you **must** ensure that the appropriate settings are provided in the ``.gitattributes`` file to always commit files with ``CRLF`` EOL characters.\n"
},
{
"path": "docs/building/releaseprocess.rst",
"content": ".. _Gitflow Workflow: https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow\r\n.. _GitHub Flow: https://docs.github.com/en/get-started/using-github/github-flow\r\n.. _develop: https://github.com/ThreeMammals/Ocelot/tree/develop\r\n.. _main: https://github.com/ThreeMammals/Ocelot/tree/main\r\n\r\nRelease Process\r\n===============\r\n\r\n* The *release process* is optimized when using Gitflow branching, as detailed here: `Gitflow Workflow`_.\r\n It's important to note that the Ocelot team does not utilize `GitHub Flow`_, which, despite being quicker, does not align with the efficiency required for Ocelot's delivery.\r\n* Contributors are free to manage their pull requests and feature branches as they see fit to contribute to the '`develop`_' branch.\r\n* Maintainers have the autonomy to handle pull requests and merges. Any merges to the '`main`_' branch will trigger the release of packages to GitHub and NuGet.\r\n* In conclusion, while users should adhere to the guidelines in :doc:`../building/devprocess`, maintainers should follow the procedures outlined in :doc:`../building/releaseprocess`.\r\n\r\nStages\r\n------\r\n.. _Pair Programming: https://www.bing.com/search?q=Pair+Programming\r\n.. _SemVer: https://semver.org\r\n.. _GitVersion: https://gitversion.net/docs/\r\n.. _Ocelot NuGet packages: https://www.nuget.org/profiles/ThreeMammals\r\n.. _Release: https://github.com/ThreeMammals/Ocelot/actions/workflows/release.yml\r\n.. _Environments: https://github.com/ThreeMammals/Ocelot/settings/environments\r\n.. _build.cake: https://github.com/ThreeMammals/Ocelot/blob/main/build.cake\r\n.. _ThreeMammals: https://github.com/ThreeMammals\r\n.. _milestone: https://github.com/ThreeMammals/Ocelot/milestones\r\n.. _releases: https://github.com/ThreeMammals/Ocelot/releases\r\n\r\nOcelot project follows this *release process* to incorporate work into NuGet packages:\r\n\r\n1. As a code reviewers, maintainers review pull requests and, if satisfactory, merge them; otherwise, they provide feedback for the contributor to address.\r\n Contributors are supported through continuous `Pair Programming`_ sessions, which include multiple code reviews, resolving code review issues, and problem-solving.\r\n\r\n2. As a release engineers, maintainers must adhere to Semantic Versioning (`SemVer`_) supported by `GitVersion`_.\r\n For breaking changes, maintainers should use the correct commit message (containing *\"+semver: breaking|major|minor|patch\"*) to ensure `GitVersion`_ applies the appropriate `SemVer`_ tags.\r\n Manual tagging of the Ocelot repository should be avoided to prevent disruptions.\r\n\r\n3. Once a pull request is merged into the '`develop`_' branch, the `Ocelot NuGet packages`_ remain unchanged until a release is initiated.\r\n When sufficient work warrants a new release, the '`develop`_' branch is merged into '`main`_' as a ``release/X.Y`` branch, triggering the `Release`_ workflow that builds the code, assigns versions, and pushes artifacts to GitHub and packages to NuGet.\r\n\r\n4. The release engineer, who holds the integration tokens in GitHub `Environments`_, automates each release build using the primary build script, '`build.cake`_'.\r\n Automated or manual :doc:`../building/building` can be performed :ref:`b-in-terminal` or :ref:`b-with-ci-cd`.\r\n The release engineer is also responsible for DevOps within the `ThreeMammals`_ organization, across all (sub)repositories, supporting the primary build script, and scripting for other repositories.\r\n\r\n5. The release engineer drafts the ``ReleaseNotes.md`` template file, informing the community about key aspects of the release, including new or updated features, bug fixes, documentation updates, breaking changes, contributor acknowledgments, version upgrade guidelines, and more.\r\n\r\n6. The final stage of the *release process* involves returning to GitHub to close the current `milestone`_, ensuring that:\r\n\r\n * All issues within the `milestone`_ are closed; any remaining work from open issues should be transferred to the next `milestone`_.\r\n * All pull requests associated with the `milestone`_ are either closed or reassigned to the upcoming release `milestone`_.\r\n * Release Notes are published on GitHub `releases`_, with an additional review of the text.\r\n * The published release is designated as the latest, provided the corresponding `Ocelot NuGet packages`_ have been successfully uploaded to the `ThreeMammals `__ account.\r\n\r\n7. Optional support for the major version ``X.Y.0`` should be available in cases such as Microsoft official patches and critical Ocelot defects of that major version.\r\n Maintainers should release patched versions ``X.Y.1-z`` as hot-fix patch versions.\r\n\r\nNotes\r\n-----\r\n.. _GitHub Actions: https://docs.github.com/en/actions\r\n.. _Actions: https://github.com/ThreeMammals/Ocelot/actions\r\n.. _Tom Pallister: https://github.com/TomPallister\r\n.. _Raman Maksimchuk: https://github.com/raman-m\r\n.. _Ocelot Team: https://github.com/orgs/ThreeMammals/teams\r\n\r\n**Note 1**: All NuGet package builds and releases are conducted through the `GitHub Actions`_ CI/CD provider.\r\nFor details, refer to the dedicated `Actions`_ dashboard, which should be used to monitor the current status of three workflows.\r\n\r\n**Note 2**: Currently, only `Tom Pallister`_, `Raman Maksimchuk`_, the owners—along with the `Ocelot Team`_ maintainers—have the authority to merge releases into the '`main`_' branch of the Ocelot repository.\r\nThis policy ensures that final :ref:`quality-gates` are in place.\r\nThe maintainers' primary focus during the final merge is to identify any security issues, as outlined in Stage 7 of the process.\r\n\r\n.. _quality-gates:\r\n\r\nQuality Gates\r\n-------------\r\n.. _code analysis rule set: https://github.com/search?q=repo%3AThreeMammals%2FOcelot%20%3CCodeAnalysisRuleSet%3E&type=code\r\n.. _codeanalysis.ruleset: https://github.com/ThreeMammals/Ocelot/blob/main/codeanalysis.ruleset\r\n.. _Overview of .NET source code analysis: https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/overview?tabs=net-9\r\n.. _StyleCop.Analyzers: https://www.nuget.org/packages/StyleCop.Analyzers\r\n.. _reference: https://github.com/search?q=repo%3AThreeMammals%2FOcelot%20StyleCop.Analyzers&type=code\r\n.. _here: https://learn.microsoft.com/en-us/dotnet/fundamentals/code-analysis/configuration-options\r\n\r\n**Gate 1**: Static code analysis.\r\nThe Ocelot repository includes the following integrated style analyzers:\r\n\r\n* In-built IDE (.NET SDK):\r\n The `code analysis rule set`_ is defined in the '`codeanalysis.ruleset`_' file, with configuration instructions available `here`_.\r\n For comprehensive documentation, refer to the following article:\r\n\r\n - Microsoft Learn: `Overview of .NET source code analysis`_\r\n\r\n* `StyleCop.Analyzers`_: The package is somewhat outdated with slow support, but Ocelot projects still `reference`_ it because it has remained functional since 2015/16 as an older style analyzer.\r\n The Ocelot team plans to replace this library with a more advanced tool in upcoming releases.\r\n"
},
{
"path": "docs/conf.py",
"content": "# Configuration file for the Sphinx documentation builder.\r\n#\r\n# For the full list of built-in configuration values, see the documentation:\r\n# https://www.sphinx-doc.org/en/master/usage/configuration.html\r\n\r\n# -- Project information -----------------------------------------------------\r\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information\r\n\r\nproject = 'Ocelot Gateway'\r\ncopyright = ' 2016-2026 Three Mammals'\r\nauthor = 'Tom Gardham-Pallister, Raman Maksimchuk'\r\nrelease = '25.0 \".NET 10\"' # OK displayed\r\nversion = '25.0' # version is not displayed in either HTML pages or PDF docs\r\n\r\n# -- General configuration ---------------------------------------------------\r\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration\r\n\r\nextensions = [\r\n 'sphinx_copybutton'\r\n]\r\n\r\ntemplates_path = ['_templates']\r\nexclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']\r\n\r\n# -- Options for HTML output -------------------------------------------------\r\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output\r\n\r\n# HTML theming: https://www.sphinx-doc.org/en/master/usage/theming.html\r\n# HTML theme development: https://www.sphinx-doc.org/en/master/development/html_themes/index.html\r\n# https://alabaster.readthedocs.io/en/latest/\r\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_theme\r\nhtml_theme = 'alabaster'\r\n\r\n# https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path\r\nhtml_static_path = ['_static']\r\nhtml_css_files = ['overrides.css']\r\n"
},
{
"path": "docs/features/administration.rst",
"content": ".. _IdentityServer: https://github.com/DuendeArchive/IdentityServer4\r\n.. _IdentityServer4: https://www.nuget.org/packages/IdentityServer4\r\n.. _Program: https://github.com/ThreeMammals/Ocelot.Administration.IdentityServer4/blob/main/sample/Program.cs\r\n.. _Ocelot.Administration.IdentityServer4: https://www.nuget.org/packages/Ocelot.Administration.IdentityServer4\r\n.. _24.0: https://github.com/ThreeMammals/Ocelot/releases/tag/24.0.0\r\n.. _Ocelot.postman_collection.json: https://github.com/ThreeMammals/Ocelot.Administration.IdentityServer4/blob/main/sample/Ocelot.postman_collection.json\r\n\r\nAdministration\r\n==============\r\n\r\n **Ocelot extension package**: `Ocelot.Administration.IdentityServer4`_ with integrated `IdentityServer4`_ package by `IdentityServer org `_ (archived on March 6, 2025)\r\n\r\nOcelot supports changing configuration during runtime via an authenticated HTTP API.\r\nThis can be authenticated in two ways either using Ocelot's internal `IdentityServer`_ (for authenticating requests to the :ref:`administration-api` only) or hooking the :ref:`administration-api` authentication into your own `IdentityServer`_.\r\n\r\nThe first thing you need to do if you want to use the :ref:`administration-api` is bring in the relevant `Ocelot.Administration.IdentityServer4`_ package:\r\n\r\n.. code-block:: powershell\r\n\r\n NuGet\\Install-Package Ocelot.Administration.IdentityServer4\r\n dotnet add package Ocelot.Administration.IdentityServer4\r\n\r\nThis will bring down everything needed by the :ref:`administration-api`.\r\n\r\n **Warning!** Currently, the *Administration* feature relies solely on the `IdentityServer4`_ package, whose `repository `_ was archived by its owner on July 31, 2024 (for the first time) and again on March 6, 2025.\r\n In release `24.0`_, the Ocelot team deprecated the `Ocelot.Administration.IdentityServer4`_ extension package.\r\n However, `the repository `_ remains available, allowing for potential patches.\r\n\r\n.. _ad-your-own-identityserver:\r\n\r\nYour Own IdentityServer [#f1]_\r\n------------------------------\r\n\r\nAll you need to do to hook into your own `IdentityServer`_ is add the following configuration options with authentication to your `Program`_.\r\nAfter that, we must pass these options to the ``AddAdministration()`` extension of the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f2]_, as shown below:\r\n\r\n.. code-block:: csharp\r\n\r\n Action options = o =>\r\n {\r\n o.Authority = \"https://identity-server-host:3333\";\r\n o.RequireHttpsMetadata = true; // false in development environment\r\n o.TokenValidationParameters = new()\r\n {\r\n ValidateAudience = false,\r\n };\r\n //...\r\n };\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddAdministration(\"/administration\", options);\r\n\r\nYou now need to get a token from your `IdentityServer`_ and use in subsequent requests to Ocelot's :ref:`administration-api`.\r\n\r\n **Note**: This feature is useful because the `IdentityServer`_ authentication middleware needs the URL of the server.\r\n If you are using the :ref:`ad-internal-identityserver`, it might not always be possible to have the Ocelot URL.\r\n\r\n.. _ad-internal-identityserver:\r\n\r\nInternal IdentityServer\r\n-----------------------\r\n\r\nThe API is authenticated using Bearer tokens that you request from Ocelot itself.\r\nThis is provided by the amazing `IdentityServer`_ project that the .NET community has been using for several years.\r\nCheck it out.\r\n\r\nIn order to enable the administration section, you need to do a few things. First of all, add this to your initial `Program`_.\r\n\r\nThe path can be anything you want and it is obviously recommended don't use a URL you would like to route through with Ocelot as this will not work.\r\nThe administration uses the ``MapWhen`` functionality of ASP.NET Core and all requests to ``{root}/administration`` will be sent there not to the Ocelot middleware.\r\n\r\nThe secret is the client secret that Ocelot's internal `IdentityServer`_ will use to authenticate requests to the :ref:`administration-api`.\r\nThis can be whatever you want it to be!\r\nIn order to pass this secret string as parameter, we must call the ``AddAdministration()`` extension of the ``OcelotBuilder`` being returned by ``AddOcelot()`` [#f2]_, as shown below:\r\n\r\n.. code-block:: csharp\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddAdministration(\"/administration\", \"secret\");\r\n\r\nIn order for the :ref:`administration-api` to work, Ocelot and `IdentityServer`_ must be able to call themselves for validation.\r\nThis means that you need to add the base URL of Ocelot to the global configuration if it is not the default ``http://localhost:5000``.\r\n\r\n **Note**: If you are using something like Docker to host Ocelot, it might not be able to call back to ``localhost``, etc., and you need to know what you are doing with Docker networking in this scenario.\r\n\r\nConfiguration can be done as follows:\r\n\r\n* If you want to run on a different host and port locally:\r\n\r\n .. code-block:: json\r\n\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"http://localhost:5580\"\r\n }\r\n\r\n* or if Ocelot is exposed via DNS:\r\n\r\n .. code-block:: json\r\n\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"http://mydns.net\"\r\n }\r\n\r\nNow, if you went with the configuration options above and want to access the API, you can use the Postman scripts called `Ocelot.postman_collection.json`_ in the solution to change the Ocelot configuration. \r\nObviously these will need to be changed if you are running Ocelot on a different URL to ``http://localhost:5000``.\r\n\r\nThe scripts show you how to request a Bearer token from Ocelot and then use it to GET the existing configuration and POST a configuration.\r\n\r\nIf you are running multiple Ocelot instances in a cluster then you need to use a certificate to sign the Bearer tokens used to access the :ref:`administration-api`.\r\n\r\nIn order to do this, you need to add two more environmental variables for each Ocelot in the cluster:\r\n\r\n1. ``OCELOT_CERTIFICATE``: The path to a certificate that can be used to sign the tokens. The certificate needs to be of the type X509 and obviously Ocelot needs to be able to access it.\r\n2. ``OCELOT_CERTIFICATE_PASSWORD``: The password for the certificate.\r\n\r\nNormally Ocelot just uses temporary signing credentials but if you set these environmental variables then it will use the certificate. \r\nIf all the other Ocelot instances in the cluster have the same certificate then you are good!\r\n\r\n.. _administration-api:\r\n\r\nAdministration API\r\n------------------\r\n\r\n* **POST** ``{adminPath}/connect/token``\r\n\r\n This gets a token for use with the admin area using the client credentials we talk about setting above.\r\n Under the hood this calls into an `IdentityServer`_ hosted within Ocelot.\r\n\r\n The body of the request is form-data as follows:\r\n\r\n * ``client_id`` set as admin\r\n * ``client_secret`` set as whatever you used when setting up the administration services.\r\n * ``scope`` set as admin\r\n * ``grant_type`` set as client_credentials\r\n\r\n* **GET** ``{adminPath}/configuration``\r\n\r\n This gets the current Ocelot configuration. It is exactly the same JSON we use to set Ocelot up with in the first place.\r\n\r\n* **POST** ``{adminPath}/configuration``\r\n\r\n This overwrites the existing configuration (should probably be a PUT!).\r\n We recommend getting your config from the GET endpoint, making any changes and posting it back... simples.\r\n\r\n The body of the request is JSON and it is the same format as the `FileConfiguration `_\r\n that we use to set up Ocelot on a file system. \r\n\r\n Please note, if you want to use this API then the process running Ocelot must have permission to write to the disk where your ``ocelot.json`` or ``ocelot.{environment}.json`` is located.\r\n This is because Ocelot will overwrite them on save. \r\n\r\n* **DELETE** ``{adminPath}/outputcache/{region}``\r\n\r\n This clears a region of the cache. If you are using a backplane, it will clear all instances of the cache!\r\n Giving your the ability to run a cluster of Ocelots and cache over all of them in memory and clear them all at the same time, so just use a distributed cache.\r\n\r\n The region is whatever you set against the ``Region`` field in the `FileCacheOptions `_ section of the Ocelot configuration.\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] The \":ref:`Your Own IdentityServer `\" feature was implemented for issue `228 `_.\r\n.. [#f2] The :ref:`di-services-addocelot-method` adds default ASP.NET services to the DI container. You can call another extended :ref:`di-addocelotusingbuilder-method` while configuring services to develop your own :ref:`di-custom-builder`. See more instructions in the \":ref:`di-addocelotusingbuilder-method`\" section of the :doc:`../features/dependencyinjection` feature.\r\n"
},
{
"path": "docs/features/aggregation.rst",
"content": "Aggregation\n===========\n\n*Aggregation*, also known as HTTP response data aggregation, is a well-known Backend for Frontend pattern of Microservices architecture.\n\n * `Backend for Frontend (BFF) Pattern: Microservices for UX | Teleport Academy `_\n * `Gateway Aggregation pattern | Azure Architecture Center | Microsoft Learn `_\n * `Backends for Frontends pattern | Azure Architecture Center | Microsoft Learn `_\n * `Implement API Gateways with Ocelot | .NET microservices - Architecture e-book | Microsoft Learn `_\n\nOcelot allows you to specify *Aggregate Routes* [#f1]_ that combine multiple normal routes and map their responses into a single object.\nThis is particularly useful when a client is making multiple requests to a server that could be consolidated into one.\nThis feature supports the implementation of a Backend for Frontend (BFF) architecture using Ocelot.\n\nConfiguration\n-------------\n\n.. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json\n\nIn order to set this up, you need to configure the `ocelot.json`_ file as follows.\nIn this example, two normal routes are specified, each having a ``Key`` property.\nAn *aggregation* is then defined, which combines the two routes using their keys listed in ``RouteKeys``, and the ``UpstreamPathTemplate`` is set up to function like a normal route.\n\n Note that duplicate ``UpstreamPathTemplates`` are not allowed between ``Routes`` and ``Aggregates``.\n You can use all of Ocelot's normal route options, except for ``RequestIdKey``, as explained in the :ref:`agg-gotchas` section.\n\n.. code-block:: json\n :emphasize-lines: 11, 21, 24\n\n {\n \"Routes\": [\n {\n \"UpstreamHttpMethod\": [ \"Get\" ],\n \"UpstreamPathTemplate\": \"/laura\",\n \"DownstreamPathTemplate\": \"/\",\n \"DownstreamScheme\": \"http\",\n \"DownstreamHostAndPorts\": [\n { \"Host\": \"localhost\", \"Port\": 51881 }\n ],\n \"Key\": \"Laura\"\n },\n {\n \"UpstreamHttpMethod\": [ \"Get\" ],\n \"UpstreamPathTemplate\": \"/tom\",\n \"DownstreamPathTemplate\": \"/\",\n \"DownstreamScheme\": \"http\",\n \"DownstreamHostAndPorts\": [\n { \"Host\": \"localhost\", \"Port\": 51882 }\n ],\n \"Key\": \"Tom\"\n }\n ],\n \"Aggregates\": [\n {\n \"UpstreamPathTemplate\": \"/\",\n \"RouteKeys\": [ \"Tom\", \"Laura\" ]\n }\n ]\n }\n\nYou can also set ``UpstreamHost`` and ``RouteIsCaseSensitive`` in the *aggregation* configuration. These settings behave the same as in other routes.\n\nIf the route ``/tom`` returned a body of ``{\"Age\": 19}`` and ``/laura`` returned ``{\"Age\": 25}``, the response after *aggregation* would be as follows:\n\n.. code-block:: json\n\n {\"Tom\":{\"Age\": 19},\"Laura\":{\"Age\": 25}}\n\nAt the moment, the *aggregation* is quite simple.\nOcelot retrieves the response from your downstream service and inserts it into a JSON dictionary, as shown above.\nThe route ``Key`` becomes the key of the dictionary, and the response body from your downstream service serves as the value.\nThe resulting object is plain JSON without any formatting or additional spaces.\n\n **Note 1**: All headers will be lost from the downstream service's response.\n\n **Note 2**: Ocelot will always return the content type ``application/json`` for an aggregate request.\n\n **Note 3**: If your downstream services return a ``404`` `Not Found `_, the aggregate will simply return nothing for that downstream service.\n It will not change the aggregate response to a ``404``, even if all the downstream services return a ``404``.\n\n.. _agg-complex-aggregation:\n\nComplex Aggregation [#f2]_\n--------------------------\n\nImagine you would like to use aggregated queries but don't have all the parameters for your queries.\nFirst, you need to call an endpoint to obtain the necessary data, such as a user's ID, and then return the user's details.\n\nLet's say we have an endpoint that returns a series of comments referencing various users or threads.\nThe author of the comments is identified by their ID, but you want to return all the details about the author.\n\nHere, you could use aggregation to: 1) retrieve all the comments, and 2) attach the author details.\nIn fact, two endpoints are called, but for the second, you dynamically replace the user's ID in the route to obtain the details.\n\nIn concrete terms:\n\n1) ``/Comments`` contains the ``authorId`` property.\n2) ``/users/{userId}``, with ``{userId}`` replaced by ``authorId``, is used to obtain the user's details.\n\nTo perform the mapping, you need to use the ``RouteKeysConfig`` list of configuration options for aggreagte route, typed as ``AggregateRouteConfig`` class:\n\n.. code-block:: json\n\n \"RouteKeysConfig\": [\n {\n \"RouteKey\": \"UserDetails\",\n \"JsonPath\": \"$[*].authorId\",\n \"Parameter\": \"userId\"\n }\n ]\n\n``RouteKey`` is used as a reference for the route, ``JsonPath`` indicates where the parameter of interest is located in the first request's response body, and ``Parameter`` specifies that the value for ``authorId`` should be used as the request parameter ``userId``.\n\nThe final configuration is as follows:\n\n.. code-block:: json\n :emphasize-lines: 27-30\n\n {\n \"Routes\": [\n {\n \"UpstreamPathTemplate\": \"/Comments\",\n \"DownstreamPathTemplate\": \"/\",\n // ...\n \"Key\": \"Comments\"\n },\n {\n \"UpstreamPathTemplate\": \"/UserDetails/{userId}\",\n \"DownstreamPathTemplate\": \"/users/{userId}\",\n // ...\n \"Key\": \"UserDetails\"\n },\n {\n \"UpstreamPathTemplate\": \"/PostDetails/{postId}\",\n \"DownstreamPathTemplate\": \"/posts/{postId}\",\n // ...\n \"Key\": \"PostDetails\"\n }\n ],\n \"Aggregates\": [\n {\n \"UpstreamPathTemplate\": \"/\",\n \"UpstreamHost\": \"localhost\",\n \"RouteKeys\": [ \"Comments\", \"UserDetails\", \"PostDetails\" ],\n \"RouteKeysConfig\": [\n { \"RouteKey\": \"UserDetails\", \"JsonPath\": \"$[*].writerId\", \"Parameter\": \"userId\" },\n { \"RouteKey\": \"PostDetails\", \"JsonPath\": \"$[*].postId\", \"Parameter\": \"postId\" }\n ]\n }\n ]\n }\n\nCustom Aggregators\n------------------\n\nOcelot started with basic request *aggregation*, and since then, a more advanced method has been added.\nThis method allows the user to take the responses from downstream services and aggregate them into a response object.\nThe `ocelot.json`_ setup is almost identical to the basic *aggregation* approach, except that you need to add an ``Aggregator`` property, as shown below:\n\n.. code-block:: json\n :emphasize-lines: 20\n\n {\n \"Routes\": [\n {\n \"UpstreamPathTemplate\": \"/laura\",\n \"DownstreamPathTemplate\": \"/\",\n // ...\n \"Key\": \"Laura\"\n },\n {\n \"UpstreamPathTemplate\": \"/tom\",\n \"DownstreamPathTemplate\": \"/\",\n // ...\n \"Key\": \"Tom\"\n }\n ],\n \"Aggregates\": [ \n {\n \"UpstreamPathTemplate\": \"/\",\n \"RouteKeys\": [ \"Tom\", \"Laura\" ],\n \"Aggregator\": \"MyAggregator\"\n }\n ]\n }\n\nHere, we have added an aggregator called ``MyAggregator``. Ocelot will look for this aggregator when it tries to aggregate this route.\n\nIn order to make the aggregator available in Ocelot Core, we must add the ``MyAggregator`` to the ``OcelotBuilder`` returned by ``AddOcelot()`` [#f3]_, as shown below:\n\n.. code-block:: csharp\n :emphasize-lines: 5\n\n using Ocelot.Multiplexer;\n\n builder.Services\n .AddOcelot(builder.Configuration)\n .AddSingletonDefinedAggregator();\n\nNow, when Ocelot tries to aggregate the route above, it will find the ``MyAggregator`` in the DI-container and use it to aggregate the route.\nSince the ``MyAggregator`` is registered in the DI-container, you can add any dependencies it needs to the container, as shown below:\n \n.. code-block:: csharp\n :emphasize-lines: 2, 6\n\n builder.Services\n .AddSingleton();\n // ...\n builder.Services\n .AddOcelot(builder.Configuration)\n .AddSingletonDefinedAggregator();\n\nIn this example, ``MyAggregator`` depends on ``MyDependency``, and it will be resolved by the DI container.\nIn addition to this, Ocelot lets you add transient aggregators, as shown below:\n\n.. code-block:: csharp\n :emphasize-lines: 3\n\n builder.Services\n .AddOcelot(builder.Configuration)\n .AddTransientDefinedAggregator();\n\nIn order to create an *aggregator*, you must implement the following interface:\n\n.. code-block:: csharp\n\n public interface IDefinedAggregator\n {\n Task Aggregate(List responses);\n }\n\nWith this feature, you can essentially do whatever you want, as the ``HttpContext`` objects contain the results of all the aggregate requests.\n\n Please note that if the ``HttpClient`` throws an exception when making a request to a route in the aggregate, you will not receive a ``HttpContext`` for it.\n However, you will receive one for any that succeed. If an exception is thrown, it will be logged.\n\nBelow is an example of an *aggregator* that can be implemented for your solution:\n\n.. code-block:: csharp\n\n public class MyAggregator : IDefinedAggregator\n {\n public async Task Aggregate(List responseHttpContexts)\n {\n // The aggregator gets a list of downstream responses as parameter.\n // You can now implement your own logic to aggregate the responses (including bodies and headers) from the downstream services\n var responses = responseHttpContexts.Select(x => x.Items.DownstreamResponse()).ToArray();\n\n // In this example we are concatenating the results,\n // but you could create a more complex construct, up to you.\n var contentList = new List();\n foreach (var response in responses)\n {\n var content = await response.Content.ReadAsStringAsync();\n contentList.Add(content);\n }\n\n // The only constraint here: You must return a DownstreamResponse object.\n return new DownstreamResponse(\n new StringContent(JsonConvert.SerializeObject(contentList)),\n HttpStatusCode.OK,\n responses.SelectMany(x => x.Headers).ToList(),\n \"reason\");\n }\n }\n\n.. _agg-gotchas:\n\nGotchas\n-------\n\n* You cannot use routes with specific ``RequestIdKeys``, as this would be overly complicated to track.\n* *Aggregation* supports only the ``GET`` HTTP verb.\n* *Aggregation* allows the forwarding of ``HttpRequest.Body`` to downstream services by duplicating the body data.\n Form data and attached files should also be forwarded.\n It is essential to specify the ``Content-Length`` header in requests to the upstream; otherwise, Ocelot will log warnings such as: *\"Aggregation does not support body copy without a Content-Length header!\"*\n\n\"\"\"\"\n\n.. [#f1] This feature was requested as part of issue `79`_, and further improvements were made as part of issue `298`_. A significant refactoring and revision of the `Multiplexer `_ design was carried out on March 4, 2024, in version `23.1`_. See pull requests `1462`_ and `1826`_ for more details.\n.. [#f2] The \":ref:`Complex Aggregation `\" feature is still in its early stages, but it enables searching for data based on an initial request. This feature was requested as part of issue `661`_, introduced in pull request `704`_, and released in version `13.4`_.\n.. [#f3] The :ref:`di-services-addocelot-method` adds default ASP.NET services to the DI container. You can call another extended :ref:`di-addocelotusingbuilder-method` while configuring services to develop your own :ref:`di-custom-builder`. See more instructions in the \":ref:`di-addocelotusingbuilder-method`\" section of the :doc:`../features/dependencyinjection` feature.\n\n.. _79: https://github.com/ThreeMammals/Ocelot/issues/79\n.. _298: https://github.com/ThreeMammals/Ocelot/issues/298\n.. _661: https://github.com/ThreeMammals/Ocelot/issues/661\n\n.. _704: https://github.com/ThreeMammals/Ocelot/pull/704\n.. _1462: https://github.com/ThreeMammals/Ocelot/pull/1462\n.. _1826: https://github.com/ThreeMammals/Ocelot/pull/1826\n\n.. _13.4: https://github.com/ThreeMammals/Ocelot/releases/tag/13.4.1\n.. _23.1: https://github.com/ThreeMammals/Ocelot/releases/tag/23.1.0\n"
},
{
"path": "docs/features/authentication.rst",
"content": ".. _scheme: https://learn.microsoft.com/en-us/aspnet/core/security/authentication/#authentication-scheme\r\n.. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/Program.cs\r\n\r\nAuthentication\r\n==============\r\n\r\nIn order to authenticate routes and subsequently use any of Ocelot's claims based features such as authorization or modifying the request with values from the token,\r\nusers must register authentication services in their `Program`_ as usual but they provide a `scheme`_ \r\n(authentication provider key) with each registration e.g.\r\n\r\n.. code-block:: csharp\r\n\r\n const string AuthenticationProviderKey = \"MyKey\"; // aka scheme\r\n builder.Services\r\n .AddAuthentication()\r\n .AddJwtBearer(AuthenticationProviderKey, options =>\r\n {\r\n // authentication setup via options initialization\r\n });\r\n\r\nIn this example, ``MyKey`` is the `scheme`_ with which this provider has been registered, but for JWT bearer authentication, the scheme is usually ``Bearer``.\r\nWe then map this to a route in the configuration using the following :ref:`authentication-options-schema` options:\r\n\r\n* ``AuthenticationProviderKey`` is a string, the legacy definition of :ref:`Single Authentication Scheme `.\r\n* ``AuthenticationProviderKeys`` is an array of strings, the recommended definition of :ref:`Multiple Authentication Schemes ` feature.\r\n\r\n.. _authentication-options-schema:\r\n\r\n``AuthenticationOptions`` Schema\r\n--------------------------------\r\n\r\n.. _FileAuthenticationOptions: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileAuthenticationOptions.cs\r\n\r\n Class: `FileAuthenticationOptions`_\r\n\r\nThe following is the full *authentication* configuration, used in both the :ref:`config-route-schema` and the :ref:`config-dynamic-route-schema`.\r\nNot all of these options need to be configured; however, the ``AuthenticationProviderKeys`` option is mandatory when ``AuthenticationProviderKey`` is absent.\r\n\r\n.. code-block:: json\r\n\r\n \"AuthenticationOptions\": {\r\n \"AllowAnonymous\": false, // nullable boolean\r\n \"AllowedScopes\": [], // array of strings\r\n \"AuthenticationProviderKey\": \"\", // deprecated! -> use AuthenticationProviderKeys\r\n \"AuthenticationProviderKeys\": [] // array of strings\r\n }\r\n\r\n.. list-table::\r\n :widths: 25 75\r\n :header-rows: 1\r\n\r\n * - *Option*\r\n - *Description*\r\n * - ``AllowAnonymous``\r\n - Excludes a route from global *authentication options* by setting it to ``true``.\r\n If the global option disables authentication by forcibly having a ``true`` value, then at the route level the option can include a route to be authenticated by setting it to ``false``.\r\n For more details, refer to the \":ref:`Configuration and AllowAnonymous `\" section.\r\n * - ``AllowedScopes``\r\n - If specified, enables authorization based on the ``scope`` claim after successful authentication by a configured authentication provider.\r\n For more details, refer to the \":ref:`authentication-allowed-scopes`\" section.\r\n * - ``AuthenticationProviderKey``\r\n - Maps a configured authentication provider, identified by a key (scheme), to a route that requires authentication.\r\n *Note: This option is deprecated—see the warning below.*\r\n For more details, refer to the \":ref:`Single Authentication Scheme `\" section.\r\n * - ``AuthenticationProviderKeys``\r\n - Maps all configured authentication providers, identified by their schemes, to a route that requires authentication.\r\n For more details, refer to the \":ref:`Multiple Authentication Schemes `\" section.\r\n\r\n.. warning::\r\n The ``AuthenticationProviderKey`` option is deprecated in version `24.1`_! Use the ``AuthenticationProviderKeys`` array option instead.\r\n Note that ``AuthenticationProviderKey`` will be removed in version `25.0`_.\r\n For backward compatibility in version `24.1`_, the ``AuthenticationProviderKey`` option takes precedence over the schemes in the ``AuthenticationProviderKeys`` array.\r\n If the ``AuthenticationProviderKey`` scheme provider fails, the remaining schemes in the ``AuthenticationProviderKeys`` array will enforce the appropriate authentication providers in the specified order.\r\n\r\n.. _authentication-scheme:\r\n\r\nSingle Authentication Scheme [#f1]_\r\n-----------------------------------\r\n\r\n Option: ``AuthenticationProviderKey``\r\n\r\nWe map authentication provider to a Route in the configuration e.g.\r\n\r\n.. code-block:: json\r\n\r\n \"AuthenticationOptions\": {\r\n \"AuthenticationProviderKey\": \"MyKey\",\r\n \"AllowedScopes\": []\r\n }\r\n\r\nWhen Ocelot runs it will look at this routes ``AuthenticationProviderKey`` and check that there is an authentication provider registered with the given key.\r\nIf there isn't then Ocelot will not start up. If there is then the route will use that provider when it executes.\r\n\r\nIf a route is authenticated, Ocelot will invoke whatever scheme is associated with it while executing the authentication middleware.\r\nIf the request fails authentication, Ocelot returns a HTTP status code `401 Unauthorized `_.\r\n\r\n.. _authentication-multiple:\r\n\r\nMultiple Authentication Schemes [#f2]_\r\n--------------------------------------\r\n.. _multiple authentication schemes: https://learn.microsoft.com/en-us/aspnet/core/security/authorization/limitingidentitybyscheme#use-multiple-authentication-schemes\r\n\r\n Option: ``AuthenticationProviderKeys``\r\n\r\nIn the real world of ASP.NET Core, apps may need to support multiple types of authentication by a single Ocelot app instance.\r\nTo register `multiple authentication schemes`_ (`authentication provider keys `_) for each appropriate authentication provider,\r\nuse and develop this abstract configuration of two or more schemes:\r\n\r\n.. code-block:: csharp\r\n\r\n var DefaultScheme = JwtBearerDefaults.AuthenticationScheme; // Bearer\r\n builder.Services\r\n .AddAuthentication()\r\n .AddJwtBearer(DefaultScheme, options => { /* JWT setup */ })\r\n // AddJwtBearer, AddCookie, AddIdentityServerAuthentication etc. \r\n .AddMyProvider(\"MyKey\", options => { /* Custom auth setup */ });\r\n\r\nIn this example, the ``MyKey`` and ``Bearer`` schemes represent the keys with which these providers were registered.\r\nWe then map these schemes to a route in the configuration as shown below.\r\n\r\n.. code-block:: json\r\n\r\n \"AuthenticationOptions\": {\r\n \"AuthenticationProviderKeys\": [ \"Bearer\", \"MyKey\" ] // The order matters!\r\n \"AllowedScopes\": []\r\n }\r\n\r\nAfterward, Ocelot applies all steps that are specified for ``AuthenticationProviderKey`` as :ref:`Single Authentication Scheme `.\r\nThe order of the keys in an array definition does matter! We use a \"First One Wins\" authentication strategy.\r\n\r\n.. _authentication-configuration:\r\n\r\nConfiguration and ``AllowAnonymous`` [#f3]_\r\n-------------------------------------------\r\n\r\nTo configure *authentication options* uniformly across all static routes, define them in ``GlobalConfiguration`` section using the :ref:`authentication-options-schema`.\r\nIf *authentication options* are specified in both ``GlobalConfiguration`` and a route (i.e., ``AuthenticationProviderKey`` or ``AuthenticationProviderKeys`` are set), the route-level configuration takes precedence.\r\n\r\nExcluding a route from global *authentication options* is possible by setting ``AllowAnonymous`` option to ``true``.\r\nThis prevents the route from requiring authentication, keeping it open and anonymous.\r\n\r\nIn the following example:\r\n\r\n* The first route is authenticated using the ``MyGlobalKey`` provider's scheme.\r\n* The second route uses the ``MyKey`` provider's scheme.\r\n* The third route is not authenticated.\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 4, 8-11, 15-17, 22-26\r\n\r\n \"Routes\": [\r\n {\r\n // route #1 props...\r\n \"AuthenticationOptions\": {}\r\n },\r\n {\r\n // route #2 props...\r\n \"AuthenticationOptions\": {\r\n \"AuthenticationProviderKeys\": [ \"MyKey\" ],\r\n \"AllowedScopes\": [ \"Bob\" ]\r\n }\r\n },\r\n {\r\n // route #3 props...\r\n \"AuthenticationOptions\": {\r\n \"AllowAnonymous\": true\r\n }\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"http://ocelot.net\",\r\n \"AuthenticationOptions\": {\r\n \"RouteKeys\": [], // empty -> no grouping, thus opts will apply to all routes\r\n \"AuthenticationProviderKeys\": [ \"MyGlobalKey\" ],\r\n \"AllowedScopes\": [ \"Admin\" ]\r\n }\r\n }\r\n\r\n.. _break: http://break.do\r\n\r\n **Note**: Ocelot performs a per-option merging algorithm to combine route and global ``AuthenticationOptions``.\r\n If global ``AuthenticationProviderKeys`` are defined together with global ``AllowedScopes``, then route options should be specified as a pair of scheme and scopes; otherwise, a scope should not belong to the global authentication provider.\r\n Moreover, the route scopes array entirely overrides the global scopes array, so the two collections are not merged but rather interchangeable.\r\n\r\n.. _authentication-global-configuration:\r\n\r\nGlobal Configuration [#f4]_\r\n---------------------------\r\n\r\nSince the global configuration for static routes has already been described above, here are additional details regarding dynamic routes, whose configuration was not supported in versions prior to `24.1`_.\r\nStarting with version `24.1`_, global and route *authentication options* for :ref:`Dynamic Routing ` were introduced.\r\nThese global options may also be overridden in the ``DynamicRoutes`` configuration section, as defined by the :ref:`config-dynamic-route-schema`.\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 6-9, 18-22\r\n\r\n {\r\n \"DynamicRoutes\": [\r\n {\r\n \"Key\": \"R1\", // optional\r\n \"ServiceName\": \"my-service\",\r\n \"AuthenticationOptions\": {\r\n \"AuthenticationProviderKeys\": [\"MyKey\"], // custom authentication provider\r\n \"AllowedScopes\": [\"my-service\"] // require authorization with a 'scope' claim set to the value 'my-service'\r\n }\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"https://ocelot.net\",\r\n \"DownstreamScheme\": \"http\",\r\n \"ServiceDiscoveryProvider\": {\r\n // required section for dynamic routing\r\n },\r\n \"AuthenticationOptions\": {\r\n \"RouteKeys\": [], // or null, no grouping, thus opts apply to all dynamic routes\r\n \"AuthenticationProviderKeys\": [\"Bearer\"], // use a global JWT bearer auth provider for all discovered services\r\n \"AllowedScopes\": [\"oc-admin\"] // require the global 'scope' claim to gain access to all discovered services\r\n }\r\n }\r\n }\r\n\r\nIn this configuration, an ``oc-admin`` scope authorization is applied to all implicit dynamic routes by the global ``Bearer`` JWT signing service.\r\nHowever, for the “my-service” service, authorization with the ``my-service`` scope is applied, and authentication is provided by another source of tokens named ``MyKey``.\r\n\r\n.. note::\r\n\r\n 1. If the ``RouteKeys`` option is not defined or the array is empty in the global ``AuthenticationOptions``, the global options will apply to all routes.\r\n If the array contains route keys, it defines a single group of routes to which the global options apply.\r\n Routes excluded from this group must specify their own route-level ``AuthenticationOptions``.\r\n\r\n 2. Prior to version `24.1`_, global and dynamic route ``AuthenticationOptions`` were not available.\r\n Starting with version `24.1`_, global configuration is supported for both static and dynamic routes.\r\n\r\n.. _authentication-allowed-scopes:\r\n\r\nAllowed Scopes\r\n--------------\r\n\r\n | Option: ``AllowedScopes``\r\n | Middleware: :ref:`authorization-middleware`\r\n\r\nTo set up authorization by scopes from the ``AllowedScopes`` collection, after successful authentication by the middleware and after claims have been transformed,\r\nthe authorization middleware in Ocelot retrieves all user claims (from the token) of the '``scope``' type and ensures that the user has at least one of the scopes in the list.\r\nThis provides a way to restrict access to a route on a per-scope basis.\r\n\r\n.. note::\r\n [#f5]_ Depending on the authentication provider, incoming tokens embed the '``scope``' claim value in the body either as an array or as a single space-separated string of multiple values.\r\n For instance, :ref:`authentication-identity-server` use an array, whereas most :ref:`authentication-jwt-tokens` providers generate a space-separated list of scopes, in accordance with `RFC 8693`_, as stated in section \"`4.2. \"scope\" (Scopes) Claim`_\".\r\n Since version `24.1`_, Ocelot supports `RFC 8693`_ (OAuth 2.0 Token Exchange) for the ``scope`` claim in the ``ScopesAuthorizer`` service, also known as the ``IScopesAuthorizer`` service in the DI container.\r\n\r\n.. note::\r\n Starting with version `24.1`_, specifying global *allowed scopes* is exclusively supported.\r\n Be cautious when overriding the global ``AllowedScopes`` array with a route-level ``AllowedScopes`` array;\r\n a combination of the route scheme (``AuthenticationProviderKeys`` array) and its *allowed scopes* might be required, since new *allowed scopes* could belong to another authentication provider's security model.\r\n For more details, refer to the \":ref:`Configuration and AllowAnonymous `\" and \":ref:`Global Configuration `\" sections.\r\n\r\n.. _authentication-jwt-tokens:\r\n\r\nJWT Tokens\r\n----------\r\n\r\nIf you want to authenticate using JWT tokens maybe from a provider like `Auth0 `_, you can register your authentication middleware as normal e.g.\r\n\r\n.. code-block:: csharp\r\n\r\n builder.Services\r\n .AddAuthentication()\r\n .AddJwtBearer(\"Auth0\", options =>\r\n {\r\n options.Authority = \"test\";\r\n options.Audience = \"test\";\r\n });\r\n builder.Services\r\n .AddOcelot(builder.Configuration);\r\n\r\nThen map the authentication provider key to a route in your configuration e.g.\r\n\r\n.. code-block:: json\r\n\r\n \"AuthenticationOptions\": {\r\n \"AuthenticationProviderKeys\": [\"Auth0\"],\r\n }\r\n\r\n**JWT Tokens Docs**\r\n\r\n * Microsoft Learn: `Authentication and authorization in minimal APIs `_\r\n * Andrew Lock | .NET Escapades: `A look behind the JWT bearer authentication middleware in ASP.NET Core `_\r\n\r\n.. _authentication-identity-server:\r\n\r\nIdentity Server Bearer Tokens\r\n-----------------------------\r\n\r\nIn order to use `IdentityServer `_ bearer tokens, register your IdentityServer services as usual in `Program`_ with a `scheme`_ (key).\r\nIf you don't understand how to do this, please consult the IdentityServer `documentation `_.\r\n\r\n.. code-block:: csharp\r\n\r\n Action options = o =>\r\n {\r\n o.Authority = \"https://whereyouridentityserverlives.com\";\r\n // ...\r\n };\r\n builder.Services\r\n .AddAuthentication()\r\n .AddJwtBearer(\"IS4\", options);\r\n builder.Services\r\n .AddOcelot(builder.Configuration);\r\n\r\nThen map the authentication provider key to a route in your configuration e.g.\r\n\r\n.. code-block:: json\r\n\r\n \"AuthenticationOptions\": {\r\n \"AuthenticationProviderKeys\": [\"IS4\"],\r\n }\r\n\r\nAuth0 by Okta\r\n-------------\r\n\r\nYet another identity provider by `Okta `_, see `Auth0 Developer Resources `_.\r\n\r\nAdd the following, at minimum, to your startup `Program`_:\r\n\r\n.. code-block:: csharp\r\n\r\n builder.Services\r\n .AddAuthentication()\r\n .AddJwtBearer(\"Okta\", o =>\r\n {\r\n var conf = builder.Configuration;\r\n o.Audience = conf[\"Authentication:Okta:Audience\"]; // Okta Authorization server Audience\r\n o.Authority = conf[\"Authentication:Okta:Server\"]; // Okta Authorization Issuer URI URL e.g. https://{subdomain}.okta.com/oauth2/{authidentifier}\r\n });\r\n builder.Services\r\n .AddOcelot(builder.Configuration);\r\n\r\n var app = builder.Build();\r\n await app\r\n .UseAuthentication()\r\n .UseOcelot();\r\n await app.RunAsync();\r\n\r\nIn order to get Ocelot to view the scope claim from Okta properly, you have to add the following to map the default Okta ``scp`` claim to ``scope``:\r\n\r\n.. code-block:: csharp\r\n\r\n // Map Okta \"scp\" to \"scope\" claims instead of http://schemas.microsoft.com/identity/claims/scope to allow Ocelot to read/verify them\r\n JsonWebTokenHandler.DefaultInboundClaimTypeMap.Remove(\"scp\");\r\n JsonWebTokenHandler.DefaultInboundClaimTypeMap.Add(\"scp\", \"scope\");\r\n\r\n**Okta Notes**\r\n\r\n 1. Issue `446`_ contains some code and examples that might help with Okta integration.\r\n 2. Here is documentation for better clarity on claims mapping: `Mapping, customizing, and transforming claims in ASP.NET Core`_.\r\n 3. It is highly advisable to read and understand the :ref:`authentication-warnings` related to the critical changes in authentication when utilizing .NET 8.\r\n\r\n.. _authentication-warnings:\r\n\r\nWarnings\r\n--------\r\n\r\n.. warning::\r\n .NET 8 introduced a breaking change where ``JwtSecurityToken`` was replaced with ``JsonWebToken`` to enhance performance and reliability.\r\n Consequently, their handlers were changed ``JwtSecurityTokenHandler`` to ``JsonWebTokenHandler``.\r\n For a complete understanding of .NET 8 breaking change related to JWT tokens, please refer to the Microsoft Learn documentation: \"`Security token events return a JsonWebToken `__\".\r\n\r\nLinks\r\n-----\r\n.. _Mapping, customizing, and transforming claims in ASP.NET Core: https://learn.microsoft.com/en-us/aspnet/core/security/authentication/claims?view=aspnetcore-9.0\r\n\r\n* Microsoft Learn: `Overview of ASP.NET Core authentication `_\r\n* Microsoft Learn: `Authorize with a specific scheme in ASP.NET Core `_\r\n* Microsoft Learn: `Policy schemes in ASP.NET Core `_\r\n* Microsoft Learn: `Mapping, customizing, and transforming claims in ASP.NET Core`_\r\n* Microsoft .NET Blog: `ASP.NET Core Authentication with IdentityServer4 `_\r\n\r\nRoadmap\r\n-------\r\n\r\nNothing is currently in the stack, but the Ocelot team is rethinking a new version of the \":doc:`../features/administration`\" feature, which is closely dependent on authentication.\r\n\r\nWe invite you to add more examples if you have integrated with other identity providers and the integration solution is working.\r\nPlease open a \"`Show and tell `_\" discussion in the repository.\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] The \":ref:`Single Authentication Scheme `\" feature has been an Ocelot artifact for ages. Use the ``AuthenticationProviderKeys`` property instead of ``AuthenticationProviderKey`` one. We support this ``[Obsolete]`` property for backward compatibility and migration reasons. In future releases, the property may be removed as a breaking change.\r\n.. [#f2] The \":ref:`Multiple Authentication Schemes `\" feature was requested in issues `740`_, `1580`_ and delivered as a part of `23.0`_ release.\r\n.. [#f3] The global \":ref:`Configuration and AllowAnonymous `\" feature for static routes was requested in issues `842`_ and `1414`_, implemented in pull request `2114`_, and officially released in version `24.1`_.\r\n.. [#f4] The \":ref:`Global Configuration `\" feature for dynamic routes was requested in issues `585`_ and `2316`_, implemented in pull request `2336`_, and released in version `24.1`_.\r\n.. [#f5] The \":ref:`authentication-allowed-scopes`\" feature fully supports `RFC 8693`_ (OAuth 2.0 Token Exchange) for the ``scope`` claim in the ``ScopesAuthorizer`` service, which is part of the :ref:`authorization-middleware`.\r\n Refer to section `4.2. \"scope\" (Scopes) Claim`_.\r\n This enhancement was requested in bug `913`_, fixed in pull request `1478`_, and the patch was rolled out as part of the `24.1`_ release.\r\n\r\n.. _RFC 8693: https://datatracker.ietf.org/doc/html/rfc8693\r\n.. _4.2. \"scope\" (Scopes) Claim: https://datatracker.ietf.org/doc/html/rfc8693#name-scope-scopes-claim\r\n\r\n.. _446: https://github.com/ThreeMammals/Ocelot/issues/446\r\n.. _585: https://github.com/ThreeMammals/Ocelot/issues/585\r\n.. _740: https://github.com/ThreeMammals/Ocelot/issues/740\r\n.. _842: https://github.com/ThreeMammals/Ocelot/issues/842\r\n.. _913: https://github.com/ThreeMammals/Ocelot/issues/913\r\n.. _1414: https://github.com/ThreeMammals/Ocelot/issues/1414\r\n.. _1478: https://github.com/ThreeMammals/Ocelot/pull/1478\r\n.. _1580: https://github.com/ThreeMammals/Ocelot/issues/1580\r\n.. _2114: https://github.com/ThreeMammals/Ocelot/pull/2114\r\n.. _2316: https://github.com/ThreeMammals/Ocelot/issues/2316\r\n.. _2336: https://github.com/ThreeMammals/Ocelot/pull/2336\r\n.. _23.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0\r\n.. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0\r\n.. _25.0: https://github.com/ThreeMammals/Ocelot/milestone/13\r\n"
},
{
"path": "docs/features/authorization.rst",
"content": "Authorization\r\n=============\r\n\r\nOcelot supports claims based authorization which is run post authentication.\r\nThis means if you have a route you want to authorize, you can add the following to your route configuration:\r\n\r\n.. code-block:: json\r\n\r\n \"RouteClaimsRequirement\": {\r\n \"UserType\": \"registered\"\r\n }\r\n\r\nIn this example, when the :ref:`authorization-middleware` is called, Ocelot will check to see if the user has the claim type ``UserType`` and if the value of that claim is ``\"registered\"``.\r\nIf it isn't then the user will not be authorized and the response will be `403 Forbidden `_.\r\n\r\n.. _authorization-middleware:\r\n\r\nAuthorization Middleware\r\n------------------------\r\n\r\nThe `AuthorizationMiddleware `_ is built-in into Ocelot pipeline.\r\n\r\n | Previous private: ``ClaimsToClaimsMiddleware``\r\n | Previous public: ``PreAuthorizationMiddleware``\r\n | **This**: ``AuthorizationMiddleware``\r\n | Next private: ``ClaimsToHeadersMiddleware``\r\n | Next public: ``PreQueryStringBuilderMiddleware``\r\n\r\n.. role:: htm(raw)\r\n :format: html\r\n\r\nSo, the closest middlewares are in order of calling:\r\n\r\n``ClaimsToClaimsMiddleware`` :htm:`→` ``PreAuthorizationMiddleware`` :htm:`→` **AuthorizationMiddleware** :htm:`→` ``ClaimsToHeadersMiddleware`` :htm:`→` ``PreQueryStringBuilderMiddleware``\r\n\r\nAs you may know from the :doc:`../features/middlewareinjection` chapter, the Authorization middleware can be overridden like this:\r\n\r\n.. code-block:: csharp\r\n\r\n var app = builder.Build();\r\n await app.UseOcelot(new OcelotPipelineConfiguration\r\n {\r\n AuthorizationMiddleware = async (context, next) =>\r\n {\r\n await next.Invoke();\r\n }\r\n });\r\n await app.RunAsync();\r\n\r\n**Note!** Do this in very rare cases, because overriding the Authorization middleware means you will lose claims and scopes authorizer through the ``RouteClaimsRequirement`` property of the route.\r\nAnother option is preparing before the actual authorization in ``PreAuthorizationMiddleware``, which is public and open to overriding.\r\n\r\n.. code-block:: csharp\r\n\r\n await app.UseOcelot(new OcelotPipelineConfiguration\r\n {\r\n PreAuthorizationMiddleware = async (context, next) =>\r\n {\r\n // Do whatever you want here\r\n await next.Invoke(); // next is AuthorizationMiddleware\r\n }\r\n });\r\n"
},
{
"path": "docs/features/caching.rst",
"content": ".. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/Program.cs\r\n\r\nCaching\r\n=======\r\n\r\n[#f1]_ Ocelot currently supports caching on the URL of the downstream service and setting a TTL in seconds to expire the cache.\r\nUsers can also clear the cache for a specific region by using Ocelot's :ref:`administration-api`.\r\n\r\nOcelot utilizes some very rudimentary caching at the moment provider by the `CacheManager `_ project.\r\nThis is an amazing project that is solving a lot of caching problems. We would recommend using this package to cache with Ocelot. \r\n\r\nThe following example shows how to add *CacheManager* to Ocelot so that you can do output caching. \r\n\r\nInstall\r\n-------\r\n\r\nFirst of all, add the following `Ocelot.Cache.CacheManager `_ package:\r\n\r\n.. code-block:: powershell\r\n\r\n Install-Package Ocelot.Cache.CacheManager\r\n\r\nThis will give you access to the Ocelot cache manager extension methods.\r\nThe second step is to add the following to your `Program`_:\r\n\r\n.. code-block:: csharp\r\n\r\n using Ocelot.Cache.CacheManager;\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddCacheManager(x => x.WithDictionaryHandle());\r\n\r\n``CacheOptions`` Schema\r\n-----------------------\r\n\r\n.. _FileCacheOptions: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileCacheOptions.cs\r\n\r\n Class: `FileCacheOptions`_\r\n\r\nThe following is the full *caching* configuration, used in both the :ref:`config-route-schema` and the :ref:`config-dynamic-route-schema`.\r\nNot all of these options need to be configured; however, the ``TtlSeconds`` option is mandatory.\r\n\r\n.. code-block:: json\r\n\r\n \"CacheOptions\": {\r\n \"TtlSeconds\": 1, // nullable integer\r\n \"Region\": \"\", // string\r\n \"Header\": \"\", // string\r\n \"EnableContentHashing\": false // nullable boolean\r\n }\r\n\r\n.. list-table::\r\n :widths: 25 75\r\n :header-rows: 1\r\n\r\n * - *Option*\r\n - *Description*\r\n * - ``TtlSeconds``\r\n - Time-To-Live (TTL) in seconds for the cached downstream response, i.e., the absolute expiration timeout starting from when the item is added to the cache.\r\n This option is required. If undefined, it defaults to 0 (zero), which disables caching.\r\n * - ``Region``\r\n - Specifies the cache region to be cleared via Ocelot's :ref:`administration-api`.\r\n See: ``DELETE {adminPath}/outputcache/{region}``\r\n * - ``Header``\r\n - Specifies the header name used for native Ocelot caching control, defaulting to the special ``OC-Cache-Control`` header.\r\n If the header is present, its value is included in the cache key constructed by the ``ICacheKeyGenerator`` service.\r\n Varying header values result in different cache keys, effectively invalidating the cache.\r\n\r\n * - ``EnableContentHashing``\r\n - Toggles inclusion of request body hashing in the cache key.\r\n Disabled by default (``false``) due to potential performance impact.\r\n Recommended for POST/PUT routes where request body affects response.\r\n Refer to the :ref:`EnableContentHashing option ` section.\r\n\r\nThe actual ``CacheOptions`` schema with all the properties can be found in the C# `FileCacheOptions`_ class.\r\n\r\n.. _caching-configuration:\r\n\r\nConfiguration\r\n-------------\r\n\r\nFinally, in order to use caching on a route in your route configuration add these sections:\r\n\r\n.. code-block:: json\r\n\r\n \"CacheOptions\": {\r\n \"TtlSeconds\": 15,\r\n \"Region\": \"europe-central\",\r\n \"Header\": \"OC-Cache-Control\",\r\n \"EnableContentHashing\": false // my route has GET verb only, assigning 'true' for requests with body: POST, PUT etc.\r\n },\r\n // Warning! FileCacheOptions section is deprecated! -> use CacheOptions\r\n \"FileCacheOptions\": {\r\n \"TtlSeconds\": 15,\r\n \"Region\": \"europe-central\",\r\n \"Header\": \"OC-Cache-Control\",\r\n \"EnableContentHashing\": false // my route has GET verb only, assigning 'true' for requests with body: POST, PUT etc.\r\n }\r\n\r\n* In this example, ``TtlSeconds`` is set to 15, which means the cache will expire 15 seconds after the response is stored.\r\n* The ``Region`` property specifies a cache region. Cache entries within a region can be cleared by calling Ocelot's :ref:`administration-api`.\r\n* If a header name is defined in the ``Header`` property, its value is retrieved from the ``HttpRequest`` headers.\r\n If the header is present, its value is included in the cache key constructed by the ``ICacheKeyGenerator`` service.\r\n Varying header values result in different cache keys, effectively invalidating the cache.\r\n* Finally, ``EnableContentHashing`` is disabled due to the current route using the ``GET`` verb, which does not include a request body.\r\n\r\n.. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0\r\n.. _25.0: https://github.com/ThreeMammals/Ocelot/milestone/13\r\n.. warning::\r\n According to the static :ref:`config-route-schema`, the ``FileCacheOptions`` section has been deprecated!\r\n\r\n The `old schema `_ ``FileCacheOptions`` section is deprecated in version `24.1`_!\r\n Use ``CacheOptions`` instead of ``FileCacheOptions``! Note that ``FileCacheOptions`` will be removed in version `25.0`_!\r\n For backward compatibility in version `24.1`_, the ``FileCacheOptions`` section takes precedence over the ``CacheOptions`` section.\r\n\r\n.. _caching-enablecontenthashing-option:\r\n\r\n``EnableContentHashing`` option [#f2]_\r\n--------------------------------------\r\n\r\nPreviously, in versions prior to `23.0`_, the request body was used to compute the cache key.\r\nHowever, due to potential performance issues arising from request body hashing, it has been disabled by default.\r\nClearly, this constitutes a breaking change and presents challenges for users who require cache key calculations that consider the request body (e.g., for the POST method).\r\nTo address this issue, it is recommended to enable the option either at the route level or globally in the \":ref:`Global Configuration `\" section:\r\n\r\n.. code-block:: json\r\n\r\n \"CacheOptions\": {\r\n // ...\r\n \"EnableContentHashing\": true\r\n }\r\n\r\n.. rubric:: Ocelot Team Recommendation\r\n\r\nAlthough the community raised concerns about backward compatibility in issue `2234`_, Ocelot team maintains that *caching* performance takes precedence over backward compatibility when migrating from versions prior to `23.0`_.\r\nThe proposed option clarifies that ``POST`` requests should **not** be cached; only ``GET`` requests are eligible for caching.\r\nTherefore, ``POST`` and ``GET`` verbs must be separated into distinct routes:\r\n\r\n* POST routes with *caching* disabled\r\n* GET routes with *caching* enabled\r\n\r\n.. _caching-global-configuration:\r\n\r\nGlobal Configuration [#f3]_\r\n---------------------------\r\n\r\nCopying route-level properties for each static route is no longer necessary, as version `23.3`_ allows these values to be set in the ``GlobalConfiguration`` section.\r\nThis convenience applies to ``Header`` and ``Region`` as well.\r\nHowever, if no global ``TtlSeconds`` value is defined, this option must still be explicitly set per route to enable caching.\r\nAs a result, the final configuration for static routes might look like:\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 5-7, 12, 18-21\r\n\r\n {\r\n \"Routes\": [\r\n {\r\n \"Key\": \"R0\", // optional\r\n \"CacheOptions\": {\r\n \"TtlSeconds\": 60 // 1-minute short-term caching\r\n },\r\n // ...\r\n },\r\n {\r\n \"Key\": \"R1\", // this route is part of a group\r\n \"CacheOptions\": {}, // optional due to grouping\r\n // ...\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"https://ocelot.net\",\r\n \"CacheOptions\": {\r\n \"RouteKeys\": [\"R1\",], // if undefined or empty array, opts will apply to all routes\r\n \"TtlSeconds\": 300 // enable global caching for a duration of 5 minutes\r\n },\r\n // ...\r\n }\r\n }\r\n\r\nDynamic routes were not supported in versions prior to `24.1`_.\r\nStarting with version `24.1`_, global *cache options* for :ref:`Dynamic Routing ` were introduced.\r\nThese global options may also be overridden in the ``DynamicRoutes`` configuration section, as defined by the :ref:`config-dynamic-route-schema`.\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 6-8, 17-20\r\n\r\n {\r\n \"DynamicRoutes\": [\r\n {\r\n \"Key\": \"\", // optional\r\n \"ServiceName\": \"my-service\",\r\n \"CacheOptions\": {\r\n \"TtlSeconds\": 60 // 1-minute short-term caching\r\n }\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"https://ocelot.net\",\r\n \"DownstreamScheme\": \"http\",\r\n \"ServiceDiscoveryProvider\": {\r\n // required section for dynamic routing\r\n },\r\n \"CacheOptions\": {\r\n \"RouteKeys\": [], // or null, no grouping, thus opts apply to all dynamic routes\r\n \"TtlSeconds\": 300 // enable global caching for a duration of 5 minutes\r\n }\r\n }\r\n }\r\n\r\nIn this configuration, a 5-minute *caching* duration is applied to all implicit dynamic routes.\r\nHowever, for the \"my-service\" service, the *caching* TTL has been explicitly reduced from 5 minutes to 1 minute.\r\n\r\n.. note::\r\n\r\n 1. If the ``RouteKeys`` option is not defined or the array is empty in the global ``CacheOptions``, the global options will apply to all routes.\r\n If the array contains route keys, it defines a single group of routes to which the global options apply.\r\n Routes excluded from this group must specify their own route-level ``CacheOptions``.\r\n\r\n 2. Prior to version `23.3`_, global ``CacheOptions`` were not available.\r\n Starting with version `24.1`_, global configuration is supported for both static and dynamic routes.\r\n\r\n.. Sample\r\n.. -----\r\n\r\n.. If you look at the example `here `_ you can see how the cache manager is setup and then passed into the Ocelot ``AddCacheManager`` configuration method.\r\n.. You can use any settings supported by the **CacheManager** package and just pass them in.\r\n\r\nCustom Caching\r\n--------------\r\n\r\nIf you want to add your own caching method, implement the following interfaces and register them in DI e.g.\r\n\r\n.. code-block:: csharp\r\n\r\n builder.Services\r\n .AddSingleton, MyCache>();\r\n\r\n* ``IOcelotCache`` this is for output caching.\r\n* ``IOcelotCache`` this is for caching the file configuration if you are calling something remote to get your config such as Consul.\r\n\r\nRoadmap\r\n-------\r\n\r\nPlease dig into the Ocelot source code to find more.\r\nWe would really appreciate it if anyone wants to implement `Redis `_, `Memcached `_ etc.\r\nPlease, open a new `Show and tell `_ thread in `Discussions `_ space of the repository.\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] Historically, *Caching* is one of Ocelot's earliest features, first introduced in version `1.1`_ on February 2, 2017, the initial release of Ocelot.\r\n The \"Clear cache region via :ref:`administration-api`\" feature was first delivered in pull request `109`_ and released in version `1.4.8`_.\r\n.. [#f2] The \":ref:`EnableContentHashing option `\" feature was requested in issue `2059`_ and released in version `23.3`_.\r\n.. [#f3] :ref:`Global Configuration ` for static routes was first introduced in pull request `2058`_ and released in version `23.3`_.\r\n Support for dynamic routes was added in pull request `2331`_ and delivered in version `24.1`_.\r\n\r\n.. _109: https://github.com/ThreeMammals/Ocelot/pull/109\r\n.. _2058: https://github.com/ThreeMammals/Ocelot/pull/2058\r\n.. _2059: https://github.com/ThreeMammals/Ocelot/issues/2059\r\n.. _2234: https://github.com/ThreeMammals/Ocelot/issues/2234\r\n.. _2331: https://github.com/ThreeMammals/Ocelot/pull/2331\r\n\r\n.. _1.1: https://github.com/ThreeMammals/Ocelot/releases/tag/1.1.0\r\n.. _1.4.8: https://github.com/ThreeMammals/Ocelot/releases/tag/1.4.8\r\n.. _23.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0\r\n.. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0\r\n.. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0\r\n"
},
{
"path": "docs/features/claimstransformation.rst",
"content": "Claims Transformation\r\n=====================\r\n\r\nOcelot allows the user to access claims and transform them into headers, query string parameters, other claims and change downstream paths. This is only available once a user has been authenticated.\r\n\r\nAfter the user is authenticated, we run the claims to claims transformation middleware (see the `ClaimsToClaimsMiddleware `_ class).\r\nThis allows the user to transform claims before the authorization middleware is called.\r\nAfter the user is authorized, we call the claims to headers middleware (see the `ClaimsToHeadersMiddleware `_ class),\r\nthen the claims to query string parameters middleware (see the `ClaimsToQueryStringMiddleware `_ class),\r\nand finally the claims to downstream path middleware (see the `ClaimsToDownstreamPathMiddleware `_ class).\r\n\r\nThe syntax for performing the transforms is the same for each process.\r\nIn the route configuration, a JSON dictionary is added with a specific name either ``AddClaimsToRequest``, ``AddHeadersToRequest``, ``AddQueriesToRequest``, or ``ChangeDownstreamPathTemplate``.\r\n\r\n **Note**: This syntax is not ideal. So any suggestions are welcome...\r\n\r\nWithin this dictionary the entries specify how Ocelot should transform things!\r\nThe key to the dictionary is going to become the key of either a claim, header or query parameter.\r\nIn the case of ``ChangeDownstreamPathTemplate``, the key must be also specified in the ``DownstreamPathTemplate``, in order to do the transformation.\r\n\r\nThe value of the entry is parsed to logic that will perform the transform.\r\nFirst of all, a dictionary accessor is specified e.g. ``Claims[CustomerId]``. This means we want to access the claims and get the ``CustomerId`` claim type.\r\nNext is a \"greater than\" ``>`` symbol which is just used to split the string. The next entry is either value or value with an indexer.\r\nIf value is specified, Ocelot will just take the value and add it to the transform.\r\nIf the value has an indexer, Ocelot will look for a delimiter which is provided after another \"greater than\" ``>`` symbol.\r\nOcelot will then split the value on the delimiter and add whatever was at the index requested to the transform.\r\n\r\nClaims to Claims\r\n----------------\r\n\r\nBelow is an example configuration that will transform claims to claims\r\n\r\n.. code-block:: json\r\n\r\n \"AddClaimsToRequest\": {\r\n \"UserType\": \"Claims[sub] > value[0] > |\",\r\n \"UserId\": \"Claims[sub] > value[1] > |\"\r\n }\r\n\r\nThis shows a transforms where Ocelot looks at the users ``sub`` claim and transforms it into ``UserType`` and ``UserId`` claims.\r\nAssuming the ``sub`` looks like this ``usertypevalue|useridvalue``.\r\n\r\nClaims to Headers\r\n-----------------\r\n\r\nBelow is an example configuration that will transform claims to headers\r\n\r\n.. code-block:: json\r\n\r\n \"AddHeadersToRequest\": {\r\n \"CustomerId\": \"Claims[sub] > value[1] > |\"\r\n }\r\n\r\nThis shows a transform where Ocelot looks at the users ``sub`` claim and transforms it into a ``CustomerId`` header.\r\nAssuming the ``sub`` looks like this ``usertypevalue|useridvalue``.\r\n\r\nClaims to Query String Parameters\r\n---------------------------------\r\n\r\nBelow is an example configuration that will transform claims to query string parameters\r\n\r\n.. code-block:: json\r\n\r\n \"AddQueriesToRequest\": {\r\n \"LocationId\": \"Claims[LocationId] > value\",\r\n }\r\n\r\nThis shows a transform where Ocelot looks at the users ``LocationId`` claim and add it as a query string parameter to be forwarded onto the downstream service.\r\n\r\nClaims to Downstream Path\r\n-------------------------\r\n\r\nBelow is an example configuration that will transform claims to downstream path custom placeholders:\r\n\r\n.. code-block:: json\r\n\r\n \"UpstreamPathTemplate\": \"/api/users/me/{everything}\",\r\n \"DownstreamPathTemplate\": \"/api/users/{userId}/{everything}\",\r\n \"ChangeDownstreamPathTemplate\": {\r\n \"userId\": \"Claims[sub] > value[1] > |\",\r\n }\r\n\r\nThis shows a transform where Ocelot looks at the users ``userId`` claim and substitutes the value to the ``{userId}`` placeholder specified in the ``DownstreamPathTemplate``.\r\nTake into account that the key specified in the ``ChangeDownstreamPathTemplate`` must be the same than the placeholder specified in the ``DownstreamPathTemplate``.\r\n\r\n **Note**: If a key specified in the ``ChangeDownstreamPathTemplate`` does not exist as a placeholder in ``DownstreamPathTemplate``, it will fail at runtime returning an error in the response.\r\n"
},
{
"path": "docs/features/configuration.rst",
"content": ".. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json\r\n.. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Configuration/Program.cs\r\n.. _ConfigurationBuilderExtensions: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/DependencyInjection/ConfigurationBuilderExtensions.cs\r\n.. _Consul: https://www.consul.io/\r\n.. _KV Store: https://developer.hashicorp.com/consul/docs/dynamic-app-config/kv\r\n\r\nConfiguration\r\n=============\r\n\r\nAn example configuration can be found here in `ocelot.json`_.\r\nThere are two major sections to the configuration: an array of ``Routes`` and a ``GlobalConfiguration`` sections:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"Routes\": [],\r\n \"GlobalConfiguration\": {}\r\n }\r\n\r\nFrom the :doc:`../introduction/gettingstarted` chapter and its :ref:`getstarted-configuration` section, you may already know that there are four total configuration sections:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"Routes\": [], // static routes\r\n \"DynamicRoutes\": [],\r\n \"Aggregates\": [], // BFF\r\n \"GlobalConfiguration\": {}\r\n }\r\n\r\n.. list-table::\r\n :widths: 25 75\r\n :header-rows: 1\r\n\r\n * - *Section*\r\n - *Description*\r\n * - ``Routes`` with :ref:`config-route-schema`\r\n - The static objects that tell Ocelot how to treat an upstream request.\r\n Once static routes have been loaded during gateway startup, in general, they cannot be changed during the lifetime of the app instance, with a few exceptional use cases.\r\n * - ``DynamicRoutes`` with :ref:`config-dynamic-route-schema`\r\n - This section enables dynamic routing when using a :doc:`../features/servicediscovery` provider.\r\n Please refer to the :ref:`routing-dynamic` docs for more details.\r\n * - ``Aggregates`` with :ref:`config-aggregate-route-schema`\r\n - This section allows specifying aggregated routes that compose multiple normal routes and map their responses into one JSON object.\r\n It allows you to start implementing a *Back-end For a Front-end* (BFF) type architecture with Ocelot.\r\n Please refer to the :doc:`../features/aggregation` chapter for more details.\r\n * - ``GlobalConfiguration`` with :ref:`config-global-configuration-schema`\r\n - This section is a bit hacky and allows overrides of static route-specific settings.\r\n It is useful if you do not want to manage lots of route-specific settings.\r\n\r\nTo fully understand all configuration capabilities, we recommend reading all sections below.\r\n\r\n.. _config-route-schema:\r\n\r\nRoute Schema\r\n------------\r\n\r\n.. _FileRoute: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileRoute.cs\r\n\r\n Class: `FileRoute`_\r\n\r\nHere is the complete route configuration, also known as the *\"route schema,\"* of top-level properties.\r\nYou do not need to set all of these things, but this is everything that is available at the moment.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"AddClaimsToRequest\": {}, // dictionary\r\n \"AddHeadersToRequest\": {}, // dictionary\r\n \"AddQueriesToRequest\": {}, // dictionary\r\n \"AuthenticationOptions\": {}, // object\r\n \"ChangeDownstreamPathTemplate\": {}, // dictionary\r\n \"DangerousAcceptAnyServerCertificateValidator\": false,\r\n \"DelegatingHandlers\": [], // array of strings\r\n \"DownstreamHeaderTransform\": {}, // dictionary\r\n \"DownstreamHostAndPorts\": [], // array of FileHostAndPort\r\n \"DownstreamHttpMethod\": \"\",\r\n \"DownstreamHttpVersion\": \"\",\r\n \"DownstreamHttpVersionPolicy\": \"\",\r\n \"DownstreamPathTemplate\": \"\",\r\n \"DownstreamScheme\": \"\",\r\n \"CacheOptions\": {}, // object\r\n \"FileCacheOptions\": {}, // deprecated! -> use CacheOptions\r\n \"HttpHandlerOptions\": {}, // object\r\n \"Key\": \"\",\r\n \"LoadBalancerOptions\": {}, // object\r\n \"Metadata\": {}, // dictionary\r\n \"Priority\": 1, // integer\r\n \"QoSOptions\": {}, // object\r\n \"RateLimitOptions\": {}, // object\r\n \"RequestIdKey\": \"\",\r\n \"RouteClaimsRequirement\": {}, // dictionary\r\n \"RouteIsCaseSensitive\": false,\r\n \"SecurityOptions\": {}, // object\r\n \"ServiceName\": \"\",\r\n \"ServiceNamespace\": \"\",\r\n \"Timeout\": 0, // nullable integer\r\n \"UpstreamHeaderTemplates\": {}, // dictionary\r\n \"UpstreamHeaderTransform\": {}, // dictionary\r\n \"UpstreamHost\": \"\",\r\n \"UpstreamHttpMethod\": [], // array of strings\r\n \"UpstreamPathTemplate\": \"\"\r\n },\r\n\r\nThe actual route schema with all the properties can be found in the C# `FileRoute`_ class.\r\n\r\n **Note**: The `old schema `__ ``FileCacheOptions`` section is deprecated in version `24.1`_!\r\n Use ``CacheOptions`` instead of ``FileCacheOptions``! Note that ``FileCacheOptions`` will be removed in version `25.0`_!\r\n For backward compatibility in version `24.1`_, the ``FileCacheOptions`` section takes precedence over the ``CacheOptions`` section.\r\n\r\n.. _config-dynamic-route-schema:\r\n\r\nDynamic Route Schema\r\n--------------------\r\n\r\n.. _FileDynamicRoute: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileDynamicRoute.cs\r\n\r\n Class: `FileDynamicRoute`_\r\n\r\nHere is the complete dynamic route configuration, also known as the *\"dynamic route schema,\"* of top-level properties.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"AuthenticationOptions\": {},\r\n \"CacheOptions\": {},\r\n \"DownstreamHttpVersion\": \"\",\r\n \"DownstreamHttpVersionPolicy\": \"\",\r\n \"HttpHandlerOptions\": {},\r\n \"LoadBalancerOptions\": {},\r\n \"Metadata\": {}, // dictionary\r\n \"QoSOptions\": {},\r\n \"RateLimitRule\": {}, // deprecated! -> use RateLimitOptions\r\n \"RateLimitOptions\": {},\r\n \"ServiceName\": \"\",\r\n \"ServiceNamespace\": \"\",\r\n \"Timeout\": 0 // nullable integer\r\n }\r\n\r\nThe actual dynamic route schema with all the properties can be found in the C# `FileDynamicRoute`_ class.\r\n\r\n **Note 1**: The `old schema `_ ``RateLimitRule`` section is deprecated in version `24.1`_!\r\n Use ``RateLimitOptions`` instead of ``RateLimitRule``! Note that ``RateLimitRule`` will be removed in version `25.0`_!\r\n For backward compatibility in version `24.1`_, the ``RateLimitRule`` section takes precedence over the ``RateLimitOptions`` section.\r\n\r\n **Note 2**: The following options were not supported in versions prior to `24.1`_ for overriding globally configured options: ``AuthenticationOptions``, ``CacheOptions``, ``HttpHandlerOptions``, ``LoadBalancerOptions``, ``QoSOptions``, ``RateLimitOptions``, ``ServiceNamespace``, and ``Timeout``.\r\n Starting with version `24.1`_, both global and route-level options for :ref:`Dynamic Routing ` were introduced.\r\n For a clearer understanding of the changes, refer to the `previous schema (version 24.0) `_.\r\n\r\n.. _config-aggregate-route-schema:\r\n\r\nAggregate Route Schema\r\n----------------------\r\n\r\n.. _FileAggregateRoute: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileAggregateRoute.cs\r\n\r\n Class: `FileAggregateRoute`_\r\n\r\nHere is the complete aggregated route configuration, also known as the *\"aggregate route schema,\"* of top-level properties.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"Aggregator\": \"\",\r\n \"Priority\": 1, // integer\r\n \"RouteIsCaseSensitive\": false,\r\n \"RouteKeys\": [], // array of strings\r\n \"RouteKeysConfig\": [], // array of AggregateRouteConfig\r\n \"UpstreamHeaderTemplates\": {}, // dictionary\r\n \"UpstreamHost\": \"\",\r\n \"UpstreamHttpMethod\": [], // array of strings\r\n \"UpstreamPathTemplate\": \"\"\r\n }\r\n\r\nThe actual aggregated route schema with all the properties can be found in the C# `FileAggregateRoute`_ class.\r\n\r\n.. _config-global-configuration-schema:\r\n\r\nGlobal Configuration Schema\r\n---------------------------\r\n\r\n.. _FileGlobalConfiguration: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileGlobalConfiguration.cs\r\n\r\n Class: `FileGlobalConfiguration`_\r\n\r\nHere is the complete global configuration, also known as the *\"global configuration schema,\"* of top-level properties.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"AuthenticationOptions\": {},\r\n \"BaseUrl\": \"\",\r\n \"CacheOptions\": {},\r\n \"DownstreamHeaderTransform\": {}, // dictionary\r\n \"DownstreamHttpVersion\": \"\",\r\n \"DownstreamHttpVersionPolicy\": \"\",\r\n \"DownstreamScheme\": \"\",\r\n \"HttpHandlerOptions\": {},\r\n \"LoadBalancerOptions\": {},\r\n \"Metadata\": {}, // dictionary\r\n \"MetadataOptions\": {},\r\n \"QoSOptions\": {},\r\n \"RateLimitOptions\": {},\r\n \"RequestIdKey\": \"\",\r\n \"SecurityOptions\": {},\r\n \"ServiceDiscoveryProvider\": {},\r\n \"Timeout\": 0, // nullable integer\r\n \"UpstreamHeaderTransform\": {} // dictionary\r\n }\r\n\r\nThe actual global configuration schema with all the properties can be found in the C# `FileGlobalConfiguration`_ class.\r\n\r\n **Note 1**: The following global options were not supported in versions prior to `24.1`_ for overriding in the :ref:`config-dynamic-route-schema`: ``AuthenticationOptions``, ``CacheOptions``, ``HttpHandlerOptions``, ``LoadBalancerOptions``, ``QoSOptions``, ``RateLimitOptions``, and ``Timeout``.\r\n Moreover, these global options were not available in versions prior to `24.1`_ for static routes, as stated in issue `585`_.\r\n Starting with version `24.1`_, both static and dynamic route *global* options are fully supported.\r\n For a clearer understanding of the changes, refer to the :ref:`config-dynamic-route-schema` and related notes.\r\n\r\n **Note 2**: The ``DownstreamHeaderTransform`` and ``UpstreamHeaderTransform`` global options were introduced in version `24.1`_, but they are available only for static routes.\r\n\r\n.. _config-overview:\r\n\r\nConfiguration Overview\r\n----------------------\r\n\r\n:doc:`../features/dependencyinjection` of the *Configuration* feature in Ocelot allows you to extend, manage, and build Ocelot Core *configuration* **before** the stage of building ASP.NET Core services.\r\n\r\nTo configure the Ocelot Core and services, use the following abstract program-structure, which must be presented in your `Program`_:\r\n\r\n1. **Create application builder**: The ``Microsoft.AspNetCore.Builder.WebApplication`` has three overloaded versions of the ``CreateBuilder()`` methods.\r\n Our recommendation is to utilize arguments possibly coming from terminal sessions into an app host; thus, use the ``CreateBuilder(args)`` method.\r\n\r\n .. code-block:: csharp\r\n\r\n var builder = WebApplication.CreateBuilder(args);\r\n\r\n2. **Set up the configuration builder**: Utilize the ``WebApplicationBuilder.Configuration`` property, which returns a ``ConfigurationManager`` object implementing the target ``IConfigurationBuilder`` interface.\r\n\r\n .. code-block:: csharp\r\n\r\n builder.Configuration.AddOcelot(...);\r\n\r\n3. **Forward configuration to the Ocelot builder**: The ``Ocelot.DependencyInjection.ServiceCollectionExtensions`` class has three overloaded versions of the ``AddOcelot(IServiceCollection)`` methods, which return an ``IOcelotBuilder`` object.\r\n\r\n .. code-block:: csharp\r\n\r\n builder.Services.AddOcelot(builder.Configuration);\r\n\r\n4. **Finish the app setup**, add middlewares, and finally run the application: Let's write the final algorithm.\r\n\r\n .. code-block:: csharp\r\n\r\n var builder = WebApplication.CreateBuilder(args); // step 1\r\n builder.Configuration.AddOcelot(...); // step 2\r\n builder.Services.AddOcelot(builder.Configuration); // step 3\r\n\r\n // Step 4\r\n var app = builder.Build();\r\n await app.UseOcelot();\r\n await app.RunAsync();\r\n\r\nFor comprehensive documentation of configuration DI-extensions, please refer to the :ref:`di-configuration-overview` section in the :doc:`../features/dependencyinjection` chapter.\r\n\r\nMultiple Environments\r\n---------------------\r\n\r\nLike any other ASP.NET Core project Ocelot supports configuration file names such as ``appsettings.dev.json``, ``appsettings.test.json`` etc.\r\nIn order to implement this add the following to you:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 4,5,7\r\n\r\n var builder = WebApplication.CreateBuilder(args);\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddJsonFile(\"ocelot.json\") // primary config file\r\n .AddJsonFile($\"ocelot.{builder.Environment.EnvironmentName}.json\");\r\n builder.Services\r\n .AddOcelot(builder.Configuration);\r\n\r\nOcelot will now use the environment specific configuration and fall back to `ocelot.json`_ if there isn't one.\r\nAnother version of the configuration above, which is based on configuration providers, is the following:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 4,6,7,9\r\n\r\n var builder = WebApplication.CreateBuilder(args);\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddOcelot() // single ocelot.json file without environment one\r\n // or\r\n .AddOcelot(builder.Environment)\r\n .AddJsonFile($\"ocelot.{builder.Environment.EnvironmentName}.json\");\r\n builder.Services\r\n .AddOcelot(builder.Configuration);\r\n\r\nYou also need to set the corresponding ``ASPNETCORE_ENVIRONMENT`` variable.\r\n\r\n **Note 1**: More info on configuration can be found in the ASP.NET Core documentation:\r\n\r\n * `Use multiple environments in ASP.NET Core `_\r\n * `Configuration in ASP.NET Core `_\r\n\r\n **Note 2**: Calling the following configuration methods is rudimentary in ASP.NET Core because of internal encapsulation in the default builder, aka ``CreateBuilder(args)`` method.\r\n\r\n .. code-block:: csharp\r\n :emphasize-lines: 3,4,5\r\n\r\n var builder = WebApplication.CreateBuilder(args);\r\n builder.Configuration\r\n .AddJsonFile(\"appsettings.json\", true, true) // not required\r\n .AddJsonFile($\"appsettings.{builder.Environment.EnvironmentName}.json\", true, true) // not required\r\n .AddEnvironmentVariables() // not required\r\n // ...\r\n\r\n This is explained in the `Default application configuration sources `_ docs; thus, remove these optional methods.\r\n\r\n.. _config-merging-files:\r\n\r\nMerging Files [#f1]_\r\n--------------------\r\n\r\n **Sample**: `Ocelot.Samples.Configuration `_\r\n\r\nThis feature allows users to have multiple configuration files to make managing large configurations easier.\r\n\r\nRather than directly adding the configuration e.g., using ``AddJsonFile(\"ocelot.json\")``, you can achieve the same result by invoking ``AddOcelot()`` as shown below:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 3\r\n\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddOcelot(builder.Environment); // will skip environment file\r\n\r\nIn this scenario, Ocelot will look for any files that match the pattern ``^ocelot\\.(.*?)\\.json$`` as the regular expression and then merge these together.\r\nThe environment file will be skipped aka ``ocelot.{builder.Environment.EnvironmentName}.json``.\r\nIf you want to set the ``GlobalConfiguration`` property, you must have a file called ``ocelot.global.json``.\r\n\r\nThe way Ocelot merges the files is basically load them, loop over them, skip environment file, add any ``Routes``, add any ``AggregateRoutes`` and if the file is called ``ocelot.global.json`` add the ``GlobalConfiguration`` aswell as any ``Routes`` or ``AggregateRoutes``.\r\nOcelot will then save the merged configuration to a file called `ocelot.json`_ and this will be used as the source of truth while Ocelot is running.\r\n\r\n **Note 1**: Currently, validation occurs only during the final merging of configurations in Ocelot.\r\n It's essential to be aware of this when troubleshooting issues.\r\n We recommend thoroughly inspecting the contents of the ``ocelot.json`` file if you encounter any problems.\r\n\r\n **Note 2**: The Merging feature is operational only during the application's startup.\r\n Consequently, the merged configuration in ``ocelot.json`` remains static post-merging and startup.\r\n Once the Ocelot application has started, you cannot call the ``AddOcelot`` method, nor can you employ the merging feature within ``AddOcelot``.\r\n If you still require on-the-fly updating of the primary configuration file, ``ocelot.json``, please refer to the :ref:`config-react-to-changes` section.\r\n Additionally, note that merging partial configuration files (such as ``ocelot.*.json``) on the fly using :doc:`../features/administration` API is not currently implemented.\r\n\r\n **Note 3**: An alternative to static merged configurations could be the construction of the ``FileConfiguration`` object before passing it as an argument to the :ref:`di-configuration-addocelot-methods` method.\r\n Refer to the :ref:`config-build-from-scratch` subsection for details.\r\n\r\nKeep files in a folder\r\n^^^^^^^^^^^^^^^^^^^^^^\r\n\r\nYou can also give Ocelot a specific path to look in for the configuration files as shown below:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 3\r\n\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddOcelot(\"/my/folder\", builder.Environment); // happy path\r\n\r\nOcelot needs the ``builder.Environment`` so it knows to exclude any environment-specific files from the merging algorithm, such as ``ocelot.{builder.Environment.EnvironmentName}.json``.\r\n\r\n.. _config-merging-tomemory:\r\n\r\nMerging files to memory [#f2]_\r\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n\r\nBy default, Ocelot writes the merged configuration to disk as `ocelot.json`_ (the primary configuration file) by adding the file to the ASP.NET configuration provider.\r\n\r\nIf your web server lacks write permissions for the configuration folder, you can instruct Ocelot to use the merged configuration directly from memory.\r\nHere's how:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 5\r\n\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n // It implicitly calls ASP.NET AddJsonStream extension method for IConfigurationBuilder\r\n // .AddJsonStream(new MemoryStream(Encoding.UTF8.GetBytes(json)));\r\n .AddOcelot(builder.Environment, MergeOcelotJson.ToMemory);\r\n\r\nThis feature proves exceptionally valuable in cloud environments like Azure, AWS, and GCP, especially when the app lacks sufficient write permissions to save files.\r\nFurthermore, within Docker container environments, permissions can be scarce, necessitating substantial DevOps efforts to enable file write operations.\r\nTherefore, save time by leveraging this feature!\r\n\r\nReload On Change\r\n----------------\r\n\r\nOcelot supports reloading the JSON configuration file on change.\r\nFor instance, the following will recreate Ocelot internal configuration when the `ocelot.json`_ file is updated manually:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 3\r\n\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddJsonFile(\"ocelot.json\", optional: false, reloadOnChange: true) // ASP.NET framework version\r\n\r\n.. _break: http://break.do\r\n\r\n **Note**: Starting from version `23.2`_, most :ref:`di-configuration-addocelot-methods` include optional ``bool?`` arguments, specifically ``optional`` and ``reloadOnChange``.\r\n Therefore, you have the flexibility to provide these arguments when invoking the native `AddJsonFile method `_ during the final configuration step (see `AddOcelotJsonFile `_ implementation).\r\n\r\nWe recommend using the :ref:`di-configuration-addocelot-methods` to control reloading, rather than relying on the framework's ``AddJsonFile`` method.\r\nFor example:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 4,13-16\r\n\r\n // Old solution based on native framework functionality\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddJsonFile(ConfigurationBuilderExtensions.PrimaryConfigFile, optional: false, reloadOnChange: true);\r\n\r\n var config = builder.Configuration;\r\n var env = builder.Environment;\r\n var mergeTo = MergeOcelotJson.ToFile; // ToMemory\r\n var folder = \"/My/folder\";\r\n var configuration = new FileConfiguration(); // read from anywhere and initialize\r\n\r\n // Advanced solutions based on Ocelot functionality\r\n config.AddOcelot(env, mergeTo, optional: false, reloadOnChange: true); // with environment and merging type\r\n config.AddOcelot(folder, env, mergeTo, optional: false, reloadOnChange: true); // with folder, environment and merging type\r\n config.AddOcelot(configuration, optional: false, reloadOnChange: true); // with configuration object created by your own\r\n config.AddOcelot(configuration, env, mergeTo, optional: false, reloadOnChange: true); // with configuration object, environment and merging type\r\n\r\nExamining the code within the ``ConfigurationBuilderExtensions`` class would be helpful for gaining a better understanding of the signatures of the overloaded :ref:`di-configuration-addocelot-methods`.\r\n\r\n.. _config-react-to-changes:\r\n\r\nReact to Changes\r\n----------------\r\n\r\nResolve ``IOcelotConfigurationChangeTokenSource`` interface from the DI container if you wish to react to changes to the Ocelot configuration via the :ref:`administration-api` or `ocelot.json`_ being reloaded from the disk.\r\n\r\nYou may either poll the change token's ``IChangeToken.HasChanged`` property, or register a callback with the ``RegisterChangeCallback`` method.\r\n\r\n **How to poll** is explained here:\r\n\r\n .. code-block:: csharp\r\n\r\n public class ConfigurationNotifyingService : BackgroundService\r\n {\r\n private readonly IOcelotConfigurationChangeTokenSource _tokenSource;\r\n private readonly ILogger _logger;\r\n\r\n public ConfigurationNotifyingService(IOcelotConfigurationChangeTokenSource tokenSource, ILogger logger)\r\n {\r\n _tokenSource = tokenSource;\r\n _logger = logger;\r\n }\r\n\r\n protected override async Task ExecuteAsync(CancellationToken stoppingToken)\r\n {\r\n while (!stoppingToken.IsCancellationRequested)\r\n {\r\n if (_tokenSource.ChangeToken.HasChanged)\r\n {\r\n _logger.LogInformation(\"Configuration has changed\");\r\n }\r\n await Task.Delay(1000, stoppingToken);\r\n }\r\n }\r\n }\r\n\r\n **How to register a callback** is explained here:\r\n\r\n .. code-block:: csharp\r\n\r\n public sealed class MyConfigurationNotifying : IDisposable\r\n {\r\n private readonly IOcelotConfigurationChangeTokenSource _tokenSource;\r\n private readonly IDisposable _callbackHolder;\r\n\r\n public MyConfigurationNotifying(IOcelotConfigurationChangeTokenSource tokenSource)\r\n {\r\n _tokenSource = tokenSource;\r\n _callbackHolder = tokenSource.ChangeToken\r\n .RegisterChangeCallback(_ => Console.WriteLine(\"Configuration has changed\"), null);\r\n }\r\n\r\n public void Dispose() => _callbackHolder.Dispose();\r\n }\r\n\r\nStore in `Consul`_\r\n------------------\r\n\r\nAs a developer, if you have enabled :doc:`../features/servicediscovery` with `Consul`_ support in Ocelot, you may choose to manage your configuration saving to the *Consul* `KV store`_.\r\n\r\nBeyond the traditional methods of storing configuration in a file vs folder (:ref:`config-merging-files`), or in-memory (:ref:`config-merging-tomemory`), you also have the alternative to utilize the `Consul`_ server's storage capabilities.\r\n\r\nFor further details on managing Ocelot configurations via a Consul instance, please consult the \":ref:`sd-consul-configuration-in-kv`\" section.\r\n\r\n.. _config-build-from-scratch:\r\n\r\nBuild From Scratch\r\n------------------\r\n\r\n Class: `FileConfiguration `_\r\n\r\nStoring, reading, and writing static configurations may have limitations.\r\nTherefore, for more flexible and advanced scenarios the ``FileConfiguration`` object can be built from scratch in C# code of Ocelot application startup.\r\nAdditionally after reading static configuration from various sources such as, remote file systems, remote storages or cloudages, you can rewrite options to the configuration.\r\n\r\nOcelot does not provide a fluent syntax to build configuration on fly as other products do.\r\nHowever, it is possible to inject a ``FileConfiguration`` object during Ocelot startup using the :ref:`di-configuration-addocelot-methods` with a special parameter:\r\n\r\n.. code-block:: csharp\r\n\r\n public static IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, FileConfiguration fileConfiguration, /* optional */);\r\n\r\nThe method above will deserialize the object to disk.\r\nIf you prefer to keep the configuration in memory, the following method includes the ``MergeOcelotJson`` parameter:\r\n\r\n.. code-block:: csharp\r\n\r\n public static IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, FileConfiguration fileConfiguration, IWebHostEnvironment env, MergeOcelotJson mergeTo, /* optional */);\r\n\r\nIn summary, the final .NET 8+ solution should be written in `Program`_ using `top-level statements `_:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 8,13,14\r\n\r\n using Ocelot.Configuration.File;\r\n using Ocelot.DependencyInjection;\r\n using Ocelot.Middleware;\r\n\r\n var builder = WebApplication.CreateBuilder(args);\r\n\r\n // Build Ocelot's configuration object on the fly:\r\n var config = new FileConfiguration(); // create new or read static state from anywhere\r\n // ... initialize or rewrite props: add routes, global config, etc.\r\n\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddOcelot(config) // MergeOcelotJson.ToFile : writing config JSON back to disk\r\n .AddOcelot(config, builder.Environment, MergeOcelotJson.ToMemory); // merging to memory\r\n builder.Services\r\n .AddOcelot(builder.Configuration);\r\n\r\n var app = builder.Build();\r\n await app.UseOcelot();\r\n await app.RunAsync();\r\n\r\nAs a final step, you could add shutdown logic to save the complete configuration back to the storage, deserializing it to JSON format.\r\n\r\n.. _config-http-handler-options:\r\n\r\n``HttpHandlerOptions``\r\n----------------------\r\n\r\n | Class: `FileHttpHandlerOptions `_\r\n | MS Learn: `SocketsHttpHandler Class `_\r\n\r\nThis route configuration section allows for following HTTP redirects, for instance, via the boolean ``AllowAutoRedirect`` option.\r\nThese options can be set at the route or global level for both static and :ref:`dynamic routing `.\r\n\r\nUse ``HttpHandlerOptions`` in a route configuration to set up `HttpMessageHandler `_ behavior\r\nbased on a `SocketsHttpHandler `_ instance:\r\n\r\n.. code-block:: json\r\n\r\n \"HttpHandlerOptions\": {\r\n \"AllowAutoRedirect\": false,\r\n \"MaxConnectionsPerServer\": 2147483647, // max integer\r\n \"PooledConnectionLifetimeSeconds\": 120,\r\n \"UseCookieContainer\": false,\r\n \"UseProxy\": false,\r\n \"UseTracing\": false\r\n }\r\n\r\n.. list-table::\r\n :widths: 25 75\r\n :header-rows: 1\r\n\r\n * - *Option*\r\n - *Description*\r\n * - | ``AllowAutoRedirect``\r\n | default: ``false``\r\n - This value indicates whether the request should follow `Redirection messages `_ (HTTP 3xx status codes).\r\n Set it ``true`` if the request should automatically follow redirection responses from the downstream resource; otherwise ``false``.\r\n * - | ``MaxConnectionsPerServer``\r\n | default: ``2147483647``, maximum integer\r\n - This controls how many connections the internal ``HttpMessageInvoker`` will open to a single :ref:`hosting-gotchas-iis`/:ref:`hosting-gotchas-kestrel` server.\r\n * - | ``PooledConnectionLifetimeSeconds``\r\n | default: ``120`` seconds\r\n - This controls how long a connection can be in the pool to be considered reusable.\r\n Also refer to the **1st note** below!\r\n * - | ``UseCookieContainer``\r\n | default: ``false``\r\n - This indicates whether the handler uses the ``CookieContainer`` property to store server cookies and uses these cookies when sending requests.\r\n Also refer to the **2nd note** below!\r\n * - | ``UseProxy``\r\n | default: ``false``\r\n - Refer to MS Learn: `UseProxy Property `_\r\n * - | ``UseTracing``\r\n | default: ``false``\r\n - This enables :doc:`../features/tracing` feature in Ocelot.\r\n Also refer to the **3rd note** below!\r\n\r\n.. note::\r\n\r\n 1. If the ``PooledConnectionLifetimeSeconds`` option is not defined, the default value is ``120`` seconds,\r\n which is hardcoded in the `HttpHandlerOptions `_ class as the ``DefaultPooledConnectionLifetimeSeconds`` constant.\r\n\r\n 2. If you use the ``CookieContainer``, Ocelot caches the ``HttpMessageInvoker`` for each downstream service.\r\n This means that all requests to that downstream service will share the same cookies.\r\n Issue `274 `_ was created because a user noticed that the cookies were being shared.\r\n The Ocelot team tried to think of a nice way to handle this but we think it is impossible.\r\n If you don't cache the clients, that means each request gets a new client and therefore a new cookie container.\r\n If you clear the cookies from the cached client container, you get race conditions due to inflight requests. \r\n This would also mean that subsequent requests don't use the cookies from the previous response!\r\n All in all not a great situation.\r\n We would avoid setting ``UseCookieContainer`` to ``true`` unless you have a really really good reason.\r\n Just look at your response headers and forward the cookies back with your next request!\r\n\r\n 3. ``UseTracing`` option adds a tracing ``DelegatingHandler`` (aka ``Ocelot.Requester.ITracingHandler``) after obtaining it from ``ITracingHandlerFactory``,\r\n encapsulating the ``Ocelot.Logging.IOcelotTracer`` service of DI-container.\r\n\r\n 4. Prior to version `24.1`_, global ``HttpHandlerOptions`` were not accessible, as they were only available at the route level for static routes.\r\n Since version `24.1`_, global configuration is supported for both static and dynamic routes.\r\n\r\n.. _ssl-errors:\r\n\r\nSSL Errors\r\n----------\r\n\r\nIf you want to ignore SSL warnings (errors), set the following in your route configuration:\r\n\r\n.. code-block:: json\r\n\r\n \"DangerousAcceptAnyServerCertificateValidator\": true\r\n\r\n**We don't recommend doing this!**\r\nThe team suggests creating your own certificate and then getting it trusted by your local (or remote) machine, if you can.\r\nFor ``https`` scheme, this fake validator was requested by issue `309 `_.\r\nFor ``wss`` scheme, this fake validator was added by PR `1377 `_. \r\n\r\n **Note**: As a team, we do not consider it an ideal solution.\r\n On one hand, the community wants to have an option to work with self-signed certificates.\r\n But on the other hand, currently, source code scanners detect two serious security vulnerabilities because of this fake validator in version `20.0`_ and higher.\r\n The Ocelot team will rethink this unfortunate situation, and it is highly likely that this feature will at least be redesigned or removed completely.\r\n\r\nFor now, the SSL fake validator makes sense in local development environments when a route has ``https`` or ``wss`` schemes with self-signed certificates for those routes.\r\nThere are no other reasons to use the ``DangerousAcceptAnyServerCertificateValidator`` property at all!\r\n\r\nAs a team, we highly recommend following these instructions when developing your gateway app with Ocelot:\r\n\r\n* **Local development environments**: Use this feature to avoid SSL errors for self-signed certificates in the case of ``https`` or ``wss`` schemes.\r\n We understand that some routes should have the downstream scheme exactly with SSL, because they are also in development and/or deployed using SSL protocols.\r\n However, we believe that, especially for local development, you can switch from ``https`` to ``http`` without any objection since the services are in development and there is no risk of data leakage.\r\n\r\n* **Remote development environments**: Everything is the same as for local development.\r\n However, this case is less strict; you have more options to use real certificates to switch off the feature.\r\n For instance, you can deploy downstream services to cloud and hosting providers that have their own signed certificates for SSL.\r\n At least your team can deploy one remote web server to host downstream services. Install your own certificate or use the cloud provider's one.\r\n\r\n* **Staging or testing environments**: We do not recommend using self-signed certificates because web servers should have valid certificates installed.\r\n Ask your system administrator or DevOps engineers to create valid certificates.\r\n\r\n* **Production environments**: **Do not use self-signed certificates at all!**\r\n System administrators or DevOps engineers must create real valid certificates signed by hosting or cloud providers.\r\n **Switch off the feature for all routes!**\r\n Remove the ``DangerousAcceptAnyServerCertificateValidator`` property for all routes in the production version of the `ocelot.json`_ file!\r\n\r\n.. _config-http-version:\r\n\r\n``DownstreamHttpVersion``\r\n-------------------------\r\n\r\n MS Learn: `HttpVersion Class `_\r\n\r\nOcelot allows you to choose the HTTP version it will use to make the proxy request. It can be set as ``1.0``, ``1.1``, or ``2.0``.\r\n\r\n.. _config-version-policy:\r\n\r\n``DownstreamHttpVersionPolicy`` [#f3]_\r\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n\r\n Enum: `HttpVersionPolicy `_\r\n\r\nThis routing property enables the configuration of the ``VersionPolicy`` property within ``HttpRequestMessage`` objects for downstream HTTP requests.\r\nFor additional details, refer to the following documentation:\r\n\r\n* `HttpRequestMessage.VersionPolicy Property `_\r\n* `HttpVersionPolicy Enum `_\r\n* `HttpVersion Class `_\r\n\r\nThe ``DownstreamHttpVersionPolicy`` option is intricately linked with the :ref:`config-http-version` setting.\r\nTherefore, merely specifying ``DownstreamHttpVersion`` may sometimes be inadequate, particularly if your downstream services or Ocelot logs report HTTP connection errors such as ``PROTOCOL_ERROR``.\r\nIn these routes, selecting the precise ``DownstreamHttpVersionPolicy`` value is crucial for the ``HttpVersion`` policy to prevent such protocol errors.\r\n\r\nHTTP2 version policy\r\n^^^^^^^^^^^^^^^^^^^^\r\n\r\n**Given** you aim to ensure a smooth HTTP/2 connection setup for the Ocelot app and downstream services with SSL enabled:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"DownstreamScheme\": \"https\",\r\n \"DownstreamHttpVersion\": \"2.0\",\r\n \"DownstreamHttpVersionPolicy\": \"\", // empty or not defined\r\n \"DangerousAcceptAnyServerCertificateValidator\": true\r\n }\r\n\r\n**And** you configure global settings to use :ref:`hosting-gotchas-kestrel` with this snippet:\r\n\r\n.. code-block:: csharp\r\n\r\n var builder = WebApplication.CreateBuilder(args);\r\n builder.WebHost.ConfigureKestrel(serverOptions =>\r\n {\r\n serverOptions.ConfigureEndpointDefaults(listenOptions =>\r\n {\r\n listenOptions.Protocols = HttpProtocols.Http2;\r\n });\r\n });\r\n\r\n**When** all components are set to communicate exclusively via HTTP/2 without TLS (plain HTTP).\r\n\r\n**Then** the downstream services may display error messages such as:\r\n\r\n.. code-block::\r\n\r\n HTTP/2 connection error (PROTOCOL_ERROR): Invalid HTTP/2 connection preface\r\n\r\nTo resolve the issue, ensure that ``HttpRequestMessage`` has its ``VersionPolicy`` set to ``RequestVersionOrHigher``.\r\nTherefore, the ``DownstreamHttpVersionPolicy`` should be defined as follows:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"DownstreamHttpVersion\": \"2.0\",\r\n \"DownstreamHttpVersionPolicy\": \"RequestVersionOrHigher\" // !\r\n }\r\n\r\nDependency Injection\r\n--------------------\r\n\r\n Class: `ConfigurationBuilderExtensions`_\r\n\r\n*Dependency Injection* for this *Configuration* feature in Ocelot is designed to extend and/or control the configuration of the Ocelot Core before the stage of building ASP.NET Core pipeline services.\r\nThe primary methods are :ref:`di-configuration-addocelot-methods` within the ``ConfigurationBuilderExtensions`` class, which offers several overloaded versions with corresponding signatures.\r\nYou can utilize these methods in the `Program`_.cs file of your gateway app to configure the Ocelot pipeline and services.\r\n\r\nFind additional details in the dedicated :ref:`di-configuration-overview` section and in subsequent sections related to the :doc:`../features/dependencyinjection` chapter.\r\n\r\n.. _config-route-metadata:\r\n\r\nExtend with ``Metadata``\r\n------------------------\r\n\r\n Feature: :doc:`../features/metadata` [#f4]_\r\n\r\nThe ``Metadata`` options can store any arbitrary data that users can access in middlewares, delegating handlers, etc.\r\nBy using the *metadata*, users can implement their own logic and extend the functionality of Ocelot.\r\n\r\nThe :doc:`../features/metadata` feature is designed to extend both the static :ref:`config-route-schema` and :ref:`config-dynamic-route-schema`.\r\nGlobal *metadata* must be defined in the ``Metadata`` section, while parsing options should be placed in the ``MetadataOptions`` section.\r\n\r\nThe following example demonstrates practical usage of this feature:\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 10,21-22\r\n\r\n {\r\n \"Routes\": [\r\n {\r\n // other opts...\r\n \"Metadata\": {\r\n \"api-id\": \"FindPost\",\r\n \"my-extension/param1\": \"overwritten-value\",\r\n \"other-extension/param1\": \"value1\",\r\n \"other-extension/param2\": \"value2\",\r\n \"tags\": \"tag1, tag2, area1, area2, func1\",\r\n \"json\": \"[1, 2, 3, 4, 5]\"\r\n }\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n // other opts...\r\n \"Metadata\": {\r\n \"instance_name\": \"dc-1-54abcz\",\r\n \"my-extension/param1\": \"default-value\"\r\n },\r\n \"MetadataOptions\": {\r\n // parsing metadata opts...\r\n }\r\n }\r\n }\r\n\r\n.. _break3: http://break.do\r\n\r\n **Note**: Route *metadata* prevails over global *metadata* from the ``GlobalConfiguration`` section.\r\n Therefore, if the same key data are defined both at the route and global levels, the route *metadata* overrides the global ones.\r\n\r\nNow, the route *metadata* can be accessed through the `DownstreamRoute `_ object:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 8,9\r\n\r\n using Ocelot.Metadata;\r\n\r\n public static class OcelotMiddlewares\r\n {\r\n public static Task PreAuthenticationMiddleware(HttpContext context, Func next)\r\n {\r\n var route = context.Items.DownstreamRoute();\r\n var param1 = route.GetMetadata(\"my-extension/param1\") ?? throw new ArgumentNullException(\"my-extension/param1\");\r\n var param2 = route.GetMetadata(\"other-extension/param2\", \"default-value\");\r\n // Working with metadata...\r\n return next();\r\n }\r\n }\r\n\r\nFor comprehensive documentation, please refer to the :doc:`../features/metadata` chapter.\r\n\r\n.. _config-timeout:\r\n\r\n``Timeout``\r\n-----------\r\n\r\nThis feature [#f5]_ is designed as part of the ``MessageInvokerPool``, which contains cached ``HttpMessageInvoker`` objects per route.\r\nEach created ``HttpMessageInvoker`` encapsulates an ``HttpMessageHandler``, specifically a ``SocketsHttpHandler`` instance, which serves as the base handler for the request pipeline.\r\nThis pipeline also includes all user-defined :doc:`../features/delegatinghandlers`.\r\nFinally, both the :doc:`../features/delegatinghandlers` and the base ``SocketsHttpHandler`` are wrapped by Ocelot's custom ``TimeoutDelegatingHandler``, which provides the internal timeout functionality.\r\n\r\n **Note**: This design is subject to future review because ``TimeoutDelegatingHandler`` overrides/mimics the default timeout properties of ``SocketsHttpHandler``, as well as the behavior of ``HttpMessageInvoker`` as a controller for ``HttpMessageHandler`` objects.\r\n\r\nTo configure timeouts (in seconds) at different levels, choose the appropriate level and provide the corresponding JSON configuration.\r\n\r\nRoute timeout\r\n^^^^^^^^^^^^^\r\n\r\nA *route timeout* (also known as Requester middleware timeout based on ``TimeoutDelegatingHandler``) can be easily defined using the following JSON, according to the :ref:`config-route-schema`:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n // upstream props\r\n // downstream props\r\n \"Timeout\": 3 // seconds\r\n }\r\n\r\nPlease note that the route-level timeout takes precedence over the global timeout.\r\nThe same configuration applies to *dynamic routes*, according to the :ref:`config-dynamic-route-schema`.\r\n\r\nGlobal timeout\r\n^^^^^^^^^^^^^^\r\n\r\nA *global configuration timeout* can be defined using the following JSON, according to the :ref:`config-global-configuration-schema`:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n // routes...\r\n \"GlobalConfiguration\": {\r\n // other props\r\n \"Timeout\": 60 // seconds, 1 minute\r\n }\r\n }\r\n\r\nPlease note that the global timeout is substituted into a route if the route-level timeout is not defined, and it takes precedence over the absolute :ref:`config-default-timeout`.\r\nAdditionally, the global timeout may be omitted in the JSON configuration in favor of the absolute :ref:`config-default-timeout`, which is also configurable via a property of the C# static class.\r\n\r\nQoS timeout\r\n^^^^^^^^^^^\r\n\r\nA :doc:`../features/qualityofservice` (QoS) *timeout* can be defined using the :ref:`qos-schema` and the QoS :ref:`qos-timeout-strategy`:\r\n\r\n.. code-block:: json\r\n\r\n \"QoSOptions\": {\r\n \"Timeout\": 5000 // milliseconds\r\n }\r\n\r\nPlease note, the *Quality of Service* timeout takes precedence over both route-level and global timeouts, which are ignored when QoS is enabled.\r\nAdditionally, avoid defining both *timeouts* in the same route, as the QoS timeout has higher priority than the route-level timeout.\r\nTherefore, the following route configuration **is not** recommended:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n // route props...\r\n \"Timeout\": 3, // seconds\r\n \"QoSOptions\": {\r\n \"Timeout\": 5000 // milliseconds\r\n }\r\n }\r\n\r\nSo, route ``Timeout`` will be ignored in favor of QoS ``Timeout``.\r\nMoreover, because the 3-second duration is shorter than 5000 milliseconds, you may observe warning messages in the logs that begin with the following sentence:\r\n\r\n.. code-block:: text\r\n\r\n Route '/xxx' has Quality of Service settings (QoSOptions) enabled, but either the route Timeout or the QoS Timeout is misconfigured: ...\r\n\r\nFor more details about this warning, refer to the :ref:`qos-notes-qos-and-route-global-timeouts` note in the :doc:`../features/qualityofservice` chapter.\r\nYour next recommended action is to completely remove the 3-second ``Timeout`` property or comment it out:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n // \"Timeout\": 3, // seconds\r\n \"QoSOptions\": {\r\n \"Timeout\": 5000 // milliseconds\r\n }\r\n }\r\n\r\n.. note::\r\n\r\n 1. Both route ``Timeout`` and QoS ``Timeout`` are nullable positive integers, with a minimum valid value of ``1``.\r\n Values in the range ``(−∞, 0]`` are treated as \"no value\" and will be automatically converted to the absolute :ref:`config-default-timeout`, effectively ignoring the property.\r\n\r\n 2. The unit of measurement for route ``Timeout`` is seconds,\r\n whereas QoS ``Timeout`` is measured in milliseconds.\r\n\r\n.. _config-default-timeout:\r\n\r\nDefault timeout\r\n^^^^^^^^^^^^^^^\r\n.. _DefTimeout: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22const+int+DefTimeout%22&type=code\r\n.. _DefaultTimeoutSeconds: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22static+int+DefaultTimeoutSeconds%22&type=code\r\n\r\nTimeout values defined at different levels in the JSON configuration can serve as fallback defaults for other levels.\r\n\r\n- The absolute timeout (also known as ``DownstreamRoute`` `DefaultTimeoutSeconds`_) defaults to 90 seconds (as defined by the ``DownstreamRoute`` `DefTimeout`_ constant).\r\n It acts as the default timeout when neither route-level nor global timeouts are defined.\r\n- The global configuration timeout, if not defined, also defaults to ``DownstreamRoute.DefaultTimeoutSeconds``.\r\n If defined, it serves as the default timeout for all routes.\r\n- The Quality of Service (QoS) global timeout acts as the default timeout for all routes where QoS is enabled.\r\n\r\nTo configure the absolute timeout (currently 90 seconds, as defined by the ``DownstreamRoute`` `DefTimeout`_ constant),\r\nassign the desired number of seconds to the ``DownstreamRoute`` `DefaultTimeoutSeconds`_ static property in your `Program`_ class:\r\n\r\n.. code-block:: csharp\r\n\r\n using Ocelot.Configuration;\r\n\r\n DownstreamRoute.DefaultTimeoutSeconds = 3; // seconds, value must be >= 3\r\n\r\nHowever, keep in mind that the absolute timeout has the lowest priority—therefore, route-level and global timeouts will override this C# property if they are defined.\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] The \":ref:`Merging Files `\" feature was requested in issue `296`_, since then we extended it in issue `1216`_ (PR `1227`_) as \":ref:`Merging files to memory `\" subfeature which was released as a part of version `23.2`_.\r\n.. [#f2] The \":ref:`Merging files to memory `\" feature is based on the `MergeOcelotJson `_ enumeration type with values: ``ToFile`` and ``ToMemory``. The 1st one is implicit by default, and the second one is exactly what you need when merging to memory. See more details on implementations in the `ConfigurationBuilderExtensions`_ class.\r\n.. [#f3] The \":ref:`DownstreamHttpVersionPolicy `\" feature was requested in issue `1672`_ as a part of version `23.3`_.\r\n.. [#f4] The \":ref:`config-route-metadata`\" feature was requested in issues `738`_ and `1990`_, and it was released as part of version `23.3`_.\r\n.. [#f5] The initial draft design of the :ref:`config-timeout` feature was implemented in pull request `1824`_ as ``TimeoutDelegatingHandler`` (released in version `23.0`_), but this version supported only the built-in `default timeout of 90 seconds`_.\r\n The full :ref:`config-timeout` feature was requested in issue `1314`_, implemented in pull request `2073`_, and officially released as part of version `24.1`_.\r\n\r\n.. _default timeout of 90 seconds: https://github.com/ThreeMammals/Ocelot/blob/24.0.0/src/Ocelot/Requester/MessageInvokerPool.cs#L38\r\n.. _296: https://github.com/ThreeMammals/Ocelot/issues/296\r\n.. _585: https://github.com/ThreeMammals/Ocelot/issues/585\r\n.. _738: https://github.com/ThreeMammals/Ocelot/issues/738\r\n.. _1216: https://github.com/ThreeMammals/Ocelot/issues/1216\r\n.. _1227: https://github.com/ThreeMammals/Ocelot/pull/1227\r\n.. _1314: https://github.com/ThreeMammals/Ocelot/issues/1314\r\n.. _1672: https://github.com/ThreeMammals/Ocelot/issues/1672\r\n.. _1824: https://github.com/ThreeMammals/Ocelot/pull/1824\r\n.. _1990: https://github.com/ThreeMammals/Ocelot/issues/1990\r\n.. _2073: https://github.com/ThreeMammals/Ocelot/pull/2073\r\n\r\n.. _20.0: https://github.com/ThreeMammals/Ocelot/releases/tag/20.0.0\r\n.. _23.0: https://github.com/ThreeMammals/Ocelot/releases/tag/23.0.0\r\n.. _23.2: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0\r\n.. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0\r\n.. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0\r\n.. _25.0: https://github.com/ThreeMammals/Ocelot/milestone/13\r\n"
},
{
"path": "docs/features/delegatinghandlers.rst",
"content": ".. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json\r\n.. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/Program.cs\r\n\r\nDelegating Handlers\r\n===================\r\n\r\n **MS Learn Documentation:**\r\n\r\n * `DelegatingHandler Class `_\r\n * `HTTP Message Handlers in ASP.NET Web API `_\r\n * `HttpClient Message Handlers in ASP.NET Web API `_\r\n\r\nOcelot allows the user to add `delegating handlers `_ to the ``HttpClient`` transport. [#f1]_\r\n\r\nConfiguration\r\n-------------\r\n\r\nIn order to utilize the :doc:`../features/delegatinghandlers` feature, you need to do the following three steps of configuration.\r\n\r\n1. Create a class that can be used as a *delegating handler*: it must inherit from the ``DelegatingHandler`` class.\r\n We are going to register these handlers in the ASP.NET Core DI container, so you can inject any other services you have registered into the constructor of your handler.\r\n\r\n .. code-block:: csharp\r\n\r\n public class MyHandler : DelegatingHandler\r\n {\r\n protected override async Task SendAsync(HttpRequestMessage request, CancellationToken token)\r\n {\r\n // Do stuff before sending request, and optionally call the base handler...\r\n var response = await base.SendAsync(request, token);\r\n // Do post-processing of the response...\r\n return response;\r\n }\r\n }\r\n\r\n2. You must add the handlers to the DI container in your `Program`_, as shown below:\r\n\r\n .. code-block:: csharp\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddDelegatingHandler()\r\n .AddDelegatingHandler();\r\n\r\n Both of these ``AddDelegatingHandler{T}`` methods have an optional parameter called ``global``, which is set to ``false``.\r\n If it is ``false``, then the intent of the *delegating handler* is to be applied to specific routes via `ocelot.json`_ (see step 3).\r\n If it is set to ``true``, then it becomes a global handler and will be applied to all routes, as shown below:\r\n\r\n .. code-block:: csharp\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddDelegatingHandler(true); // it's global!\r\n\r\n.. _break: http://break.do\r\n\r\n **Note 1**: The generic ``AddDelegatingHandler(bool)`` method has another overloaded non-generic one with the ``Type`` parameter: ``AddDelegatingHandler(Type, bool)``.\r\n Thus, here is an alternative to set it up:\r\n\r\n .. code-block:: csharp\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddDelegatingHandler(typeof(MyHandler)) // for selected routes only\r\n .AddDelegatingHandler(typeof(MyGlobalHandler), true); // it's global!\r\n\r\n **Note 2**: Both versions of the methods add transient services to the DI container. It is recommended to utilize the generic version.\r\n\r\n3. If you want route-specific *delegating handlers* or to order your specific and/or global *delegating handlers* (more on this in the :ref:`dh-execution-order` section), then you must add the following to the specific route in `ocelot.json`_.\r\n The names in the array must match the class names of your *delegating handlers* for Ocelot to match them together:\r\n\r\n .. code-block:: json\r\n\r\n \"DelegatingHandlers\": [ \"MyHandlerTwo\", \"MyHandler\" ]\r\n\r\n.. _dh-execution-order:\r\n\r\nExecution Order\r\n---------------\r\n\r\nYou can have as many *delegating handlers* as you want, and they are run in the following order:\r\n\r\n1. Any globals that are left in the order they were added to services and are not in the ``DelegatingHandlers`` option array from `ocelot.json`_.\r\n2. Any non-global *delegating handlers* plus any globals that were in the ``DelegatingHandlers`` option array from `ocelot.json`_, ordered as they are in the ``DelegatingHandlers`` array.\r\n3. Tracing *delegating handler*, if enabled (refer to the :doc:`../features/tracing` chapter).\r\n4. Quality of Service *delegating handler*, if enabled (refer to the :doc:`../features/qualityofservice` chapter).\r\n5. The ``HttpClient`` sends the ``HttpRequestMessage``.\r\n\r\nHopefully, other people will find this feature useful!\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] This feature was requested in issue `208`_, and the team decided that it would be useful in various ways, releasing it in version `3.0.3`_. Since then, we extended it in issue `264`_ and released it in version `5.0.0`_.\r\n\r\n.. _208: https://github.com/ThreeMammals/Ocelot/issues/208\r\n.. _264: https://github.com/ThreeMammals/Ocelot/issues/264\r\n\r\n.. _3.0.3: https://github.com/ThreeMammals/Ocelot/releases/tag/3.0.3\r\n.. _5.0.0: https://github.com/ThreeMammals/Ocelot/releases/tag/5.0.0\r\n"
},
{
"path": "docs/features/dependencyinjection.rst",
"content": ".. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json\n.. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/Program.cs\n.. _ServiceCollectionExtensions: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/DependencyInjection/ServiceCollectionExtensions.cs\n.. _ConfigurationBuilderExtensions: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/DependencyInjection/ConfigurationBuilderExtensions.cs\n\nDependency Injection\n====================\n\n | Namespace: ``Ocelot.DependencyInjection``\n | Source code: `DependencyInjection `_\n\n.. _di-services-overview:\n\nServices Overview\n-----------------\n\n*Dependency Injection* feature in Ocelot is designed to extend and/or control the building of Ocelot Core as ASP.NET Core pipeline services.\nThe main methods of the `ServiceCollectionExtensions`_ class are:\n\n* The :ref:`di-services-addocelot-method` adds the required Ocelot services to the DI container and adds default services using the :ref:`di-adddefaultaspnetservices-method`.\n* The :ref:`di-addocelotusingbuilder-method` adds the required Ocelot services to the DI container and adds custom ASP.NET services with configuration injected implicitly or explicitly.\n\nUse :ref:`di-iservicecollection-extensions` in your `Program`_ (ASP.NET Core app) to add and build Ocelot Core services.\nThe fact is, the :ref:`di-ocelotbuilder-class` is Ocelot's cornerstone logic.\n\n.. _di-iservicecollection-extensions:\n\n``IServiceCollection`` extensions\n---------------------------------\n\n Class: ``Ocelot.DependencyInjection.`` `ServiceCollectionExtensions`_\n\nBased on the current implementations for the :ref:`di-ocelotbuilder-class`, the :ref:`di-services-addocelot-method` adds the required ASP.NET services to the DI container.\nYou could call the more extended :ref:`di-addocelotusingbuilder-method` while configuring services to build and use a custom builder via an ``IMvcCoreBuilder`` object.\n\n.. _di-services-addocelot-method:\n\n``AddOcelot`` method\n^^^^^^^^^^^^^^^^^^^^\n\n**Signatures**:\n\n.. code-block:: csharp\n\n IOcelotBuilder AddOcelot(this IServiceCollection services);\n IOcelotBuilder AddOcelot(this IServiceCollection services, IConfiguration configuration);\n\nThese ``IServiceCollection`` extension methods add default ASP.NET services and Ocelot application services with configuration injected implicitly or explicitly.\n\n **Note**: Both methods add the required and *default* ASP.NET Core services for Ocelot Core in the :ref:`di-adddefaultaspnetservices-method`, which is the default builder.\n\nIn this scenario, you do nothing other than call the ``AddOcelot`` method, which is often mentioned in feature chapters if additional startup settings are required.\nWith this method, you simply reuse the default settings to build the Ocelot Core. The alternative is the ``AddOcelotUsingBuilder`` method; see the next subsection.\n\n.. _di-addocelotusingbuilder-method:\n\n``AddOcelotUsingBuilder`` method\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n**Signatures**:\n\n.. code-block:: csharp\n\n using CustomBuilderFunc = System.Func;\n\n IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, CustomBuilderFunc customBuilder);\n IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, IConfiguration configuration, CustomBuilderFunc customBuilder);\n\nThese ``IServiceCollection`` extension methods add Ocelot application services and **custom** ASP.NET Core services with configuration injected implicitly or explicitly.\n\n **Note**: The method adds **custom** ASP.NET Core services required for Ocelot Core using a custom builder (aka ``customBuilder`` parameter).\n It is highly recommended to read the documentation of the :ref:`di-adddefaultaspnetservices-method`,\n or even review the implementation to understand the default ASP.NET Core services which are the minimal part of the gateway pipeline.\n\nIn this custom scenario, you control everything during the ASP.NET Core build process, and you provide custom settings to build Ocelot Core.\n\n.. _di-ocelotbuilder-class:\n\n``OcelotBuilder`` class\n-----------------------\n\nThe `OcelotBuilder `_ class is the core of Ocelot which does the following:\n\n- Contructs itself by single public constructor:\n\n .. code-block:: csharp\n\n public OcelotBuilder(IServiceCollection services, IConfiguration configurationRoot, Func customBuilder = null);\n\n- Initializes and stores public properties: ``Services`` (of ``IServiceCollection`` type), ``Configuration`` (of ``IConfiguration`` type), and ``MvcCoreBuilder`` (of ``IMvcCoreBuilder`` type).\n- Adds *all application services* during the construction phase via the ``Services`` property.\n- Adds ASP.NET Core services by builder using ``Func`` object in these 2 development scenarios:\n- Adds ASP.NET Core services by builder using a ``Func`` object in these two development scenarios:\n\n 1. By default builder (:ref:`di-adddefaultaspnetservices-method`) if there is no ``customBuilder`` parameter provided.\n 2. By :ref:`di-custom-builder` with the provided delegate object as the ``customBuilder`` parameter.\n\n- Adds (switches on/off) Ocelot features through the following methods:\n\n * ``AddSingletonDefinedAggregator`` and ``AddTransientDefinedAggregator`` methods\n * ``AddCustomLoadBalancer`` method\n * ``AddDelegatingHandler`` method\n * ``AddConfigPlaceholders`` method\n\n.. _di-adddefaultaspnetservices-method:\n\n``AddDefaultAspNetServices`` method\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n Part of the :ref:`di-ocelotbuilder-class`\n\nCurrently, the method is protected, and overriding is forbidden.\nThe role of the method is to inject the required services via both the ``IServiceCollection`` and ``IMvcCoreBuilder`` interface objects for the minimal part of the gateway pipeline.\n\nCurrent `implementation `_ is the folowing:\n\n.. code-block:: csharp\n\n protected IMvcCoreBuilder AddDefaultAspNetServices(IMvcCoreBuilder builder, Assembly assembly)\n {\n Services\n .AddLogging()\n .AddMiddlewareAnalysis()\n .AddWebEncoders();\n return builder\n .AddApplicationPart(assembly)\n .AddControllersAsServices()\n .AddAuthorization()\n .AddNewtonsoftJson();\n }\n\nThe method cannot be overridden. It is not virtual, and there is no way to override the current behavior by inheritance.\nThe method is the default builder of Ocelot Core when calling the :ref:`di-services-addocelot-method`.\nAs an alternative, to \"override\" this default builder, you can design and reuse a custom builder as a ``Func`` delegate object and pass it as a parameter to the :ref:`di-addocelotusingbuilder-method`.\nIt gives you full control over the design and building of Ocelot Core, but be careful when designing your custom Ocelot pipeline as a customizable ASP.NET Core pipeline.\n\n **Warning**: Most of the services from the minimal part of the pipeline should be reused, but only a few services can be removed.\n\n **Warning**: The method above is called after adding the required services of the ASP.NET Core pipeline by the `AddMvcCore `_ method via the ``Services`` property in the upper calling context.\n These services are the absolute minimum core services for the ASP.NET MVC pipeline.\n They must always be added to the DI container and are added implicitly before calling the method by the caller in the upper context.\n So, ``AddMvcCore`` creates an ``IMvcCoreBuilder`` object and assigns it to the ``MvcCoreBuilder`` property.\n Finally, as a default builder, the method above receives the ``IMvcCoreBuilder`` object, making it ready for further extensions.\n\nThe next section shows you an example of designing a custom Ocelot Core using a custom builder.\n\n.. _di-custom-builder:\n\nCustom Builder\n--------------\n\n**Goal**: Replace ``Newtonsoft.Json`` services with ``System.Text.Json`` services.\n\nProblem\n^^^^^^^\n\nThe main :ref:`di-services-addocelot-method` adds `Newtonsoft JSON `_ services\nusing the ``AddNewtonsoftJson`` extension method in the default builder (:ref:`di-adddefaultaspnetservices-method`).\nThe ``AddNewtonsoftJson`` method was introduced in earlier .NET and Ocelot releases, which was necessary before Microsoft launched the ``System.Text.Json`` library.\nHowever, it now affects normal use, so we intend to solve the problem.\n\nModern `JSON services `_ \nout of `the box `_\nwill help configure JSON settings using the ``JsonSerializerOptions`` property for JSON formatters during (de)serialization.\n\nSolution\n^^^^^^^^\n\nWe have the following methods in `ServiceCollectionExtensions`_ class:\n\n.. code-block:: csharp\n\n IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, Func customBuilder);\n IOcelotBuilder AddOcelotUsingBuilder(this IServiceCollection services, IConfiguration configuration, Func customBuilder);\n\nThese methods with a custom builder allow you to use any desired JSON library for (de)serialization.\nHowever, we are going to create a custom ``MvcCoreBuilder`` with support for JSON services, such as ``System.Text.Json``.\nTo do that, we need to call the ``AddJsonOptions`` extension of the ``MvcCoreMvcCoreBuilderExtensions`` class\n(NuGet `Microsoft.AspNetCore.Mvc.Core `_ package) in `Program`_:\n\n.. code-block:: csharp\n :emphasize-lines: 6\n\n builder.Services\n .AddLogging()\n .AddMiddlewareAnalysis()\n .AddWebEncoders()\n // Add your custom builder\n .AddOcelotUsingBuilder(builder.Configuration, MyCustomBuilder);\n\n static IMvcCoreBuilder MyCustomBuilder(IMvcCoreBuilder builder, Assembly assembly) => builder\n .AddApplicationPart(assembly)\n .AddControllersAsServices()\n .AddAuthorization()\n // Replace AddNewtonsoftJson() by AddJsonOptions()\n .AddJsonOptions(options =>\n {\n options.JsonSerializerOptions.WriteIndented = true; // use System.Text.Json\n });\n\nThe sample code provides settings to render JSON as indented text rather than as compressed plain JSON text without spaces.\nThis is just one common use case, and you can add additional services to the builder.\n\n---------------------------------------------------------------------------------------------------------------------------\n\n.. _di-configuration-overview:\n\nConfiguration Overview\n----------------------\n\n*Dependency Injection* for the :doc:`../features/configuration` feature in Ocelot is designed to extend and set up the configuration of the Ocelot Core **before** the stage of building ASP.NET Core services (see :ref:`di-services-overview`).\nTo configure the Ocelot Core services, use the :ref:`di-configuration-extensions` in your `Program`_ of your gateway app.\n\n.. _di-configuration-extensions:\n\n``IConfigurationBuilder`` extensions\n------------------------------------\n\n Class: ``Ocelot.DependencyInjection.`` `ConfigurationBuilderExtensions`_\n\nThe main methods are the :ref:`di-configuration-addocelot-methods` within the `ConfigurationBuilderExtensions`_ class.\nThese methods have a list of overloaded versions with corresponding signatures.\n\nThe purpose of the ``AddOcelot`` method is to prepare everything before actually configuring with native extensions.\nIt involves the following steps:\n\n1. **Merging Partial JSON Files**: The ``GetMergedOcelotJson`` method merges partial JSON files.\n2. **Selecting Merge Type**: It allows you to choose a merge type to save the merged JSON configuration data either ``ToFile`` or ``ToMemory``.\n3. **Framework Extensions**: Finally, the method calls the following native ``IConfigurationBuilder`` framework extensions:\n\n * The ``AddJsonFile`` method adds the primary configuration file (commonly known as `ocelot.json`_) after the merge stage. It writes the file back *to the file system* using the ``ToFile`` merge type option, which is implicitly the default.\n * The ``AddJsonStream`` method adds the JSON data of the primary configuration file as a UTF-8 stream *into memory* after the merge stage. It uses the ``ToMemory`` merge type option.\n\n.. _di-configuration-addocelot-methods:\n\n``AddOcelot`` methods\n^^^^^^^^^^^^^^^^^^^^^\n\n**Signatures** of the most common versions:\n\n.. code-block:: csharp\n\n IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, IWebHostEnvironment env);\n IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, string folder, IWebHostEnvironment env);\n\n.. _break: http://break.do\n\n **Note**: These versions use the implicit ``ToFile`` merge type to write `ocelot.json`_ back to disk. Finally, they call the ``AddJsonFile`` extension.\n\n**Signatures** of the versions to specify a ``MergeOcelotJson`` option:\n\n.. code-block:: csharp\n\n IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, IWebHostEnvironment env, MergeOcelotJson mergeTo,\n string primaryConfigFile = null, string globalConfigFile = null, string environmentConfigFile = null, bool? optional = null, bool? reloadOnChange = null);\n IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, string folder, IWebHostEnvironment env, MergeOcelotJson mergeTo,\n string primaryConfigFile = null, string globalConfigFile = null, string environmentConfigFile = null, bool? optional = null, bool? reloadOnChange = null);\n\n.. _break2: http://break.do\n\n **Note**: These versions include optional arguments to specify the location of the three main files involved in the merge operation.\n In theory, these files can be located anywhere, but in practice, it is better to keep them in one folder.\n\n**Signatures** of the versions to indicate the ``FileConfiguration`` object of a self-created out-of-the-box configuration: [#f1]_\n\n.. code-block:: csharp\n\n IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, FileConfiguration fileConfiguration,\n string primaryConfigFile = null, bool? optional = null, bool? reloadOnChange = null);\n IConfigurationBuilder AddOcelot(this IConfigurationBuilder builder, FileConfiguration fileConfiguration, IWebHostEnvironment env, MergeOcelotJson mergeTo,\n string primaryConfigFile = null, string globalConfigFile = null, string environmentConfigFile = null, bool? optional = null, bool? reloadOnChange = null);\n\n.. _break3: http://break.do\n\n **Note 1**: These versions include optional arguments to specify the location of the three main files involved in the merge operation.\n\n **Note 2**: Your ``FileConfiguration`` object can be serialized/deserialized from anywhere: local or remote storage, Consul KV storage, and even a database.\n For more information about this super useful feature, please read PR `1569`_.\n\n\"\"\"\"\n\n.. [#f1] The :ref:`config-build-from-scratch` feature was requested in issues `1228`_ and `1235`_. It was delivered by PR `1569`_ as part of version `20.0`_. Since then, we have extended it in PR `1227`_ and released it as part of version `23.2`_.\n\n.. _1227: https://github.com/ThreeMammals/Ocelot/pull/1227\n.. _1228: https://github.com/ThreeMammals/Ocelot/issues/1228\n.. _1235: https://github.com/ThreeMammals/Ocelot/issues/1235\n.. _1569: https://github.com/ThreeMammals/Ocelot/pull/1569\n.. _20.0: https://github.com/ThreeMammals/Ocelot/releases/tag/20.0.0\n.. _23.2: https://github.com/ThreeMammals/Ocelot/releases/tag/23.2.0\n"
},
{
"path": "docs/features/errorcodes.rst",
"content": "Error Handling\r\n==============\r\n.. _Handle errors in ASP.NET Core: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling\r\n.. _standard error handling: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/error-handling\r\n\r\n MS Learn: `Handle errors in ASP.NET Core`_\r\n\r\nOcelot has custom error handling for ``Exception`` objects.\r\nThus, we override the `standard error handling`_ provided by ASP.NET Core, which is based on manipulating ``Exception`` objects.\r\n\r\n.. _eh-middleware:\r\n\r\nMiddleware\r\n----------\r\n.. _499 Client Closed Request: https://learn.microsoft.com/en-us/dotnet/api/microsoft.aspnetcore.http.statuscodes.status499clientclosedrequest\r\n.. _500 Internal Server Error: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/500\r\n\r\n Class: `ExceptionHandlerMiddleware `_\r\n\r\nThe ``ExceptionHandlerMiddleware`` produces the following status codes, in fallback order, after setting the :ref:`lg-request-id`:\r\n\r\n1. Native response status: Returned when no exception is present, or when a mapped error status is available (excluding ``499`` and ``500``).\r\n2. `499 Client Closed Request`_: A custom Ocelot status returned when an ``OperationCanceledException`` occurs due to an aborted request.\r\n A warning is logged.\r\n3. `500 Internal Server Error`_: The standard status returned when a generic ``Exception`` occurs and Ocelot does not process or map the error.\r\n An error record is logged.\r\n\r\nOcelot returns HTTP status codes based on internal logic in specific cases of :ref:`eh-client-error-responses` and :ref:`eh-server-error-responses`.\r\n\r\n.. _eh-client-error-responses:\r\n\r\nClient Error Responses\r\n----------------------\r\n.. _401 Unauthorized: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/401\r\n.. _403 Forbidden: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/403\r\n.. _404 Not Found: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/404\r\n.. _RequestCanceledError: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+RequestCanceledError&type=code\r\n.. _OcelotErrorCode.RequestCanceled: https://github.com/search?q=repo%3AThreeMammals%2FOcelot%20OcelotErrorCode.RequestCanceled&type=code\r\n\r\n- `401 Unauthorized`_: If the authentication middleware runs and the user is not authenticated.\r\n- `403 Forbidden`_: If the authorization middleware runs and the user is unauthorized, if the claim value is not authorized, if the scope is not authorized, if the user does not have the required claim, or if the claim cannot be found.\r\n- `404 Not Found`_: If a downstream route cannot be found, or if Ocelot is unable to map an internal error code to an HTTP status code.\r\n- `499 Client Closed Request`_: If the request is canceled by the client.\r\n\r\n | Ocelot Error: `RequestCanceledError `_\r\n | Ocelot Code: `OcelotErrorCode.RequestCanceled `_\r\n\r\n According to Ocelot Core's design, HTTP status code ``499`` is returned in the following ``OperationCanceledException`` scenarios:\r\n\r\n 1. By ``ExceptionHandlerMiddleware``, if an ``OperationCanceledException`` is thrown and the context's cancellation token is in the \"cancellation requested\" state.\r\n Ocelot logs a warning with the exception body. If the response has not started, the status code will be set to ``499``.\r\n 2. By ``ResponderMiddleware``, if the default ``IErrorsToHttpStatusCodeMapper`` service maps the detected `OcelotErrorCode.RequestCanceled`_ to status ``499``.\r\n This error code is produced by the ``IExceptionToErrorMapper`` service when an ``OperationCanceledException`` is thrown by other middlewares.\r\n\r\n.. _eh-server-error-responses:\r\n\r\nServer Error Responses\r\n----------------------\r\n.. _502 Bad Gateway: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/502\r\n.. _503 Service Unavailable: https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/503\r\n\r\n- `500 Internal Server Error`_: If unable to complete the HTTP request to the downstream service, and the exception is not ``OperationCanceledException`` or ``HttpRequestException``.\r\n- `502 Bad Gateway`_: If unable to connect to the downstream service.\r\n- `503 Service Unavailable`_: Returned when the downstream request times out.\r\n\r\n | Ocelot Error: `RequestTimedOutError `_\r\n | Ocelot Code: `OcelotErrorCode.RequestTimedOutError `_\r\n\r\n According to Ocelot Core's design, status code ``503`` is produced in the following ``TimeoutException`` scenarios:\r\n\r\n 1. By ``TimeoutDelegatingHandler`` from the ``IMessageInvokerPool`` service, when an ``OperationCanceledException`` is thrown and the context's cancellation token is not in the “cancellation requested” state.\r\n Ocelot does not log an error with the exception body, but the ``IExceptionToErrorMapper`` service generates the internal `OcelotErrorCode.RequestTimedOutError`_.\r\n 2. By ``ResponderMiddleware``, if the default ``IErrorsToHttpStatusCodeMapper`` service maps the detected `OcelotErrorCode.RequestTimedOutError`_ to status ``503``.\r\n This error code is produced by the ``IExceptionToErrorMapper`` service when a ``TimeoutException`` is thrown by other middlewares—especially by ``TimeoutDelegatingHandler``.\r\n\r\n.. _eh-error-mapper:\r\n\r\nError Mapper\r\n------------\r\n\r\n Class: `HttpExceptionToErrorMapper `_\r\n\r\nHistorically, Ocelot errors are implemented by the `Exception-to-Error mapper `_.\r\nThe ``Map`` method converts an ``Exception`` object to a native ``Ocelot.Errors.Error`` object.\r\n\r\nWe override HTTP status codes because of ``Exception``-to-``Error`` mapping.\r\nThis can be confusing for the developer since the actual status code of the downstream service may be different and get lost.\r\nPlease research and review all response headers of the upstream service.\r\nIf you do not find status codes and/or required headers, then the :doc:`../features/headerstransformation` feature should help.\r\n\r\nWe expect you to share your use case with us in the `Discussions `_ space of the repository. |octocat|\r\n\r\n.. |octocat| image:: https://github.githubassets.com/images/icons/emoji/octocat.png\r\n :alt: octocat\r\n :height: 25\r\n :class: img-valign-middle\r\n"
},
{
"path": "docs/features/graphql.rst",
"content": ".. _GraphQL: https://graphql.org/\r\n.. _Ocelot.Samples.GraphQL: https://github.com/ThreeMammals/Ocelot/tree/main/samples/GraphQL\r\n.. _graphql-dotnet: https://github.com/graphql-dotnet/graphql-dotnet\r\n.. |GraphQL Logo| image:: https://avatars.githubusercontent.com/u/13958777\r\n :alt: GraphQL Logo\r\n :width: 40\r\n\r\n|GraphQL Logo| GraphQL\r\n======================\r\n\r\nOcelot does not directly support `GraphQL`_, but many people have asked about it.\r\nWe wanted to show how easy it is to integrate the `GraphQL for .NET `_ library.\r\n\r\nSample\r\n------\r\n\r\n **Sample**: `Ocelot.Samples.GraphQL`_\r\n\r\nPlease see the sample project `Ocelot.Samples.GraphQL`_.\r\nUsing a combination of the `graphql-dotnet`_ project and Ocelot :doc:`../features/delegatinghandlers` feature, this is pretty easy to do.\r\nHowever, we do not intend to integrate more closely with `GraphQL`_ at the moment.\r\nCheck out the sample's `README.md `_ for detailed instructions on how to do this.\r\n\r\nFuture\r\n------\r\n\r\nIf you have sufficient experience with `GraphQL`_ and the mentioned .NET `graphql-dotnet`_ package, we would welcome your contribution to the sample. |octocat|\r\n\r\n.. |octocat| image:: https://github.githubassets.com/images/icons/emoji/octocat.png\r\n :alt: octocat\r\n :height: 25\r\n :class: img-valign-middle\r\n\r\nWho knows, maybe you will get inspired by the sample development and come up with a design solution in the form of a rough draft of a *GraphQL* feature to implement in Ocelot.\r\nGood luck!\r\nAnd welcome to the `Discussions `_ space of the repository!\r\n"
},
{
"path": "docs/features/headerstransformation.rst",
"content": ".. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json\r\n.. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/Program.cs\r\n\r\nHeaders Transformation\r\n======================\r\n\r\nOcelot allows the user to transform `HTTP headers `_ both before and after the downstream request.\r\n\r\n **Note**: *Headers Transformation* is generally available for static routes with a global configuration.\r\n For dynamic and aggregate routes, this feature is not implemented. This limitation is noted in the current :ref:`ht-roadmap`.\r\n\r\nSchema\r\n------\r\n\r\nAs you may already know from the :doc:`../features/configuration` chapter and the :ref:`config-route-schema` section, the route's *Headers Transformation* schema is quite simple, a JSON dictionary:\r\n\r\n.. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n // \"header_name\": \"transformation_expression\",\r\n },\r\n \"UpstreamHeaderTransform\": {\r\n // \"header_name\": \"transformation_expression\",\r\n }, \r\n\r\nTypically, a ``transformation_expression`` is a constant header value, a single placeholder from the :ref:`ht-placeholders` list, or a \":ref:`Find and Replace `\" expression.\r\nAdditionally, the :ref:`config-global-configuration-schema` allows configuring global *Headers Transformations* (refer to the :ref:`Configuration ` section).\r\n\r\n.. _ht-configuration:\r\n\r\nConfiguration [#f1]_\r\n--------------------\r\n\r\nA complete *configuration* consists of both route-level and global *Headers Transformations*.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"Routes\": [\r\n {\r\n \"DownstreamHeaderTransform\": {\r\n // ...\r\n },\r\n \"UpstreamHeaderTransform\": {\r\n // ...\r\n }\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"DownstreamHeaderTransform\": {\r\n // ...\r\n },\r\n \"UpstreamHeaderTransform\": {\r\n // ...\r\n }\r\n }\r\n }\r\n\r\n.. _break: http://break.do\r\n.. _Merge: https://github.com/search?q=repo%3AThreeMammals%2FOcelot+%22public+static+IEnumerable%3CHeader%3E+Merge%22&type=code\r\n\r\n **Note**: Route-level transformations take precedence over global transformations.\r\n In addition, when route-level transformations are defined, they do not entirely override the full set of header names from the global configuration.\r\n Ocelot's Core internal `Merge`_ algorithm identifies global header names not specified at the route level and appends them to the route's header set.\r\n\r\n.. _ht-find-and-replace:\r\n\r\nFind and Replace [#f2]_\r\n-----------------------\r\n\r\nIn order to transform a header first we specify the header key and then the type of transform we want e.g.\r\n\r\n.. code-block:: json\r\n\r\n \"Test\": \"http://www.bbc.co.uk/, http://ocelot.net/\"\r\n\r\nThe key is ``Test`` and the value is ``http://www.bbc.co.uk/, http://ocelot.net/``.\r\nThe value is saying: replace ``http://www.bbc.co.uk/`` with ``http://ocelot.net/``.\r\nThe syntax is ``{find}, {replace}``. Hopefully pretty simple. There are examples below that explain more.\r\n\r\n**Pre Downstream Request**\r\n\r\nAdd the following to a Route in `ocelot.json`_ in order to replace ``http://www.bbc.co.uk/`` with ``http://ocelot.net/``.\r\nThis header will be changed before the request downstream and will be sent to the downstream server.\r\n\r\n.. code-block:: json\r\n\r\n \"UpstreamHeaderTransform\": {\r\n \"Test\": \"http://www.bbc.co.uk/, http://ocelot.net/\"\r\n }\r\n\r\n**Post Downstream Request**\r\n\r\nAdd the following to a Route in `ocelot.json`_ in order to replace ``http://www.bbc.co.uk/`` with ``http://ocelot.net/``.\r\nThis transformation will take place after Ocelot has received the response from the downstream service.\r\n\r\n.. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n \"Test\": \"http://www.bbc.co.uk/, http://ocelot.net/\"\r\n }\r\n\r\n.. _ht-add-to-request:\r\n\r\nAdd to Request [#f3]_\r\n---------------------\r\n\r\nIf you want to add a header to your upstream request please add the following to a route in your `ocelot.json`_:\r\n\r\n.. code-block:: json\r\n\r\n \"UpstreamHeaderTransform\": {\r\n \"Uncle\": \"Bob\"\r\n }\r\n\r\nIn the example above a header with the key ``Uncle`` and value ``Bob`` would be send to to the upstream service.\r\n\r\n :ref:`ht-placeholders` are supported too (see below).\r\n\r\n.. _ht-add-to-response:\r\n\r\nAdd to Response [#f4]_\r\n----------------------\r\n\r\nIf you want to add a header to your downstream response, please add the following to a route in `ocelot.json`_:\r\n\r\n.. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n \"Uncle\": \"Bob\"\r\n }\r\n\r\nIn the example above a header with the key ``Uncle`` and value ``Bob`` would be returned by Ocelot when requesting the specific route.\r\n\r\nIf you want to return the :ref:`tr-butterfly` Trace ID, do something like the following:\r\n\r\n.. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n \"AnyKey\": \"{TraceId}\"\r\n }\r\n\r\n.. _ht-placeholders:\r\n\r\nPlaceholders\r\n------------\r\n\r\nOcelot allows placeholders that can be used in header transformation.\r\n\r\n.. list-table::\r\n :widths: 25 75\r\n :header-rows: 1\r\n\r\n * - *Placeholder*\r\n - *Description*\r\n * - ``{BaseUrl}``\r\n - This will use Ocelot base URL e.g. ``http://localhost:5000`` as its value.\r\n * - ``{DownstreamBaseUrl}``\r\n - This will use the downstream services base URL e.g. ``http://localhost:5000`` as its value. This only works for ``DownstreamHeaderTransform`` route option at the moment.\r\n * - ``{RemoteIpAddress}``\r\n - This will find the clients IP address using ``HttpContext.Connection.RemoteIpAddress``, so you will get back some IP. See more in the `GetRemoteIpAddress `_ method.\r\n * - ``{TraceId}``\r\n - This will use the :ref:`tr-butterfly` Trace ID. This only works for ``DownstreamHeaderTransform`` route option at the moment.\r\n * - ``{UpstreamHost}``\r\n - This will look for the incoming ``Host`` header.\r\n\r\nFor now, we believe these placeholders are sufficient for basic user scenarios.\r\nHowever, if you need additional placeholders, refer to the :ref:`ht-roadmap`.\r\n\r\nSamples\r\n-------\r\n\r\nHandling 302 redirects\r\n^^^^^^^^^^^^^^^^^^^^^^\r\n\r\nOcelot will by default automatically follow redirects, however if you want to return the location header to the client, you might want to change the location to be Ocelot not the downstream service.\r\nOcelot allows this with the following configuration:\r\n\r\n.. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n \"Location\": \"http://www.bbc.co.uk/, http://ocelot.net/\"\r\n },\r\n \"HttpHandlerOptions\": {\r\n \"AllowAutoRedirect\": false,\r\n }\r\n\r\nOr, you could use the ``{BaseUrl}`` placeholder.\r\n\r\n.. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n \"Location\": \"http://localhost:6773, {BaseUrl}\"\r\n },\r\n \"HttpHandlerOptions\": {\r\n \"AllowAutoRedirect\": false,\r\n }\r\n\r\nFinally, if you are using a load balancer with Ocelot, you will get multiple downstream base URLs so the above would not work.\r\nIn this case you can do the following:\r\n\r\n.. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n \"Location\": \"{DownstreamBaseUrl}, {BaseUrl}\"\r\n },\r\n \"HttpHandlerOptions\": {\r\n \"AllowAutoRedirect\": false,\r\n }\r\n\r\n``X-Forwarded-For`` header\r\n^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n\r\nAn example of using ``{RemoteIpAddress}`` placeholder:\r\n\r\n.. code-block:: json\r\n\r\n \"UpstreamHeaderTransform\": {\r\n \"X-Forwarded-For\": \"{RemoteIpAddress}\"\r\n }\r\n\r\n.. _ht-roadmap:\r\n\r\nRoadmap\r\n-------\r\n\r\n1. Ideally the \":ref:`Find and Replace `\" feature would be able to support the fact that a header can have multiple values.\r\n At the moment it just assumes one.\r\n It would also be nice if it could multi find and replace e.g. \r\n\r\n .. code-block:: json\r\n\r\n \"DownstreamHeaderTransform\": {\r\n \"Location\": \"[{one,one},{two,two}]\"\r\n },\r\n \"HttpHandlerOptions\": {\r\n \"AllowAutoRedirect\": false,\r\n }\r\n\r\n.. _break2: http://break.do\r\n.. _moderate effort: https://github.com/ThreeMammals/Ocelot/labels/medium%20effort\r\n.. _significant effort: https://github.com/ThreeMammals/Ocelot/labels/large%20effort\r\n\r\n2. The *Headers Transformation* feature is not implemented for :ref:`Dynamic Routes ` and :ref:`Aggregate Routes `.\r\n For :ref:`Dynamic Routing `, potential development would require `moderate effort`_.\r\n However, the Ocelot team expects that designing and implementing *Headers Transformation* for :doc:`../features/aggregation` will demand `significant effort`_, as aggregated routes typically lose their headers.\r\n\r\n.. |octocat| image:: https://github.githubassets.com/images/icons/emoji/octocat.png\r\n :alt: octocat\r\n :height: 25\r\n :class: img-valign-middle\r\n\r\nIdeas and proposals are welcome in the repository's `Discussions `_ space. |octocat|\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] The global :ref:`Configuration ` feature was requested in issue `1658`_ and released in version `24.1`_.\r\n.. [#f2] The \":ref:`Find and Replace `\" feature was requested in issue `190`_, initially released in version `2.0.11`_, and the team decided that it would be useful in various ways.\r\n.. [#f3] The \":ref:`Add to Request `\" feature was requested in issue `313`_ and released in version `5.5.3`_.\r\n.. [#f4] The \":ref:`Add to Response `\" feature was requested in issue `280`_ and released in version `5.1.0`_.\r\n\r\n.. _2.0.11: https://github.com/ThreeMammals/Ocelot/releases/tag/2.0.11\r\n.. _5.1.0: https://github.com/ThreeMammals/Ocelot/releases/tag/5.1.0\r\n.. _5.5.3: https://github.com/ThreeMammals/Ocelot/releases/tag/5.5.3\r\n.. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0\r\n.. _190: https://github.com/ThreeMammals/Ocelot/issues/190\r\n.. _280: https://github.com/ThreeMammals/Ocelot/issues/280\r\n.. _313: https://github.com/ThreeMammals/Ocelot/issues/313\r\n.. _1658: https://github.com/ThreeMammals/Ocelot/issues/1658\r\n"
},
{
"path": "docs/features/kubernetes.rst",
"content": ".. role:: htm(raw)\r\n :format: html\r\n.. role:: pdf(raw)\r\n :format: latex pdflatex\r\n.. |K8sLogo| image:: https://raw.githubusercontent.com/kubernetes/kubernetes/master/logo/logo.png\r\n :alt: K8s Logo\r\n :height: 50\r\n :class: img-valign-bottom\r\n :target: https://kubernetes.io\r\n.. |logo-kubernetes| image:: ../images/k8s-logo-kubernetes.png\r\n :alt: kubernetes logo\r\n :height: 30\r\n :class: img-valign-middle\r\n :target: https://kubernetes.io\r\n\r\n.. _KubeClient: https://www.nuget.org/packages/KubeClient\r\n.. _Ocelot.Provider.Kubernetes: https://www.nuget.org/packages/Ocelot.Provider.Kubernetes\r\n.. _package: https://www.nuget.org/packages/Ocelot.Provider.Kubernetes\r\n\r\n|K8sLogo| Kubernetes (K8s) [#f1]_\r\n=================================\r\n\r\n | Feature of: :doc:`../features/servicediscovery`\r\n | Quick Links: `K8s Website `_ | `K8s Documentation `_ | `K8s GitHub `_\r\n\r\nOcelot will call the `K8s `_ endpoints API in a given namespace to get all of the endpoints for a pod and then load balance across them.\r\nOcelot used to use the services API to send requests to the `K8s`_ service but this was changed in pull request `1134`_ because the service did not load balance as expected.\r\n\r\nOur NuGet `Ocelot.Provider.Kubernetes`_ extension package is based on the `KubeClient`_ package.\r\nFor a comprehensive understanding, it is essential refer to the `KubeClient`_ documentation.\r\n\r\n.. _k8s-install:\r\n\r\nInstall\r\n-------\r\n\r\nThe first thing you need to do is install the `package`_ that provides |logo-kubernetes| support in Ocelot:\r\n\r\n.. code-block:: powershell\r\n\r\n Install-Package Ocelot.Provider.Kubernetes\r\n\r\n``AddKubernetes(bool)`` method\r\n------------------------------\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 3\r\n\r\n public static class OcelotBuilderExtensions\r\n {\r\n public static IOcelotBuilder AddKubernetes(this IOcelotBuilder builder, bool usePodServiceAccount = true);\r\n }\r\n\r\nThis extension-method adds `K8s`_ services **with** or **without** using a pod service account.\r\nThen add the following to your `Program `_:\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 3\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddKubernetes(); // usePodServiceAccount is true\r\n\r\nIf you have services deployed in Kubernetes, you will normally use the naming service to access them.\r\n\r\n1. By default the ``useServiceAccount`` argument is true, which means that Service Account using Pod to access the service of the `K8s`_ cluster needs to be Service Account based on RBAC authorization:\r\n\r\n You can replicate a Permissive using RBAC role bindings (see `Permissive RBAC Permissions `_),\r\n `K8s`_ API server and token will read from pod.\r\n\r\n .. code-block:: bash\r\n\r\n kubectl create clusterrolebinding permissive-binding --clusterrole=cluster-admin --user=admin --user=kubelet --group=system:serviceaccounts\r\n\r\n Finally, it creates the `KubeClient`_ from pod service account.\r\n\r\n2. When the ``useServiceAccount`` argument is false, you need to provide `KubeClientOptions `_ to create `KubeClient`_ using them.\r\n You have to bind the options configuration section for the DI ``IOptions`` interface or register a custom action to initialize the options:\r\n\r\n .. code-block:: csharp\r\n :emphasize-lines: 9, 10, 13\r\n\r\n Action configureKubeClient = opts => \r\n { \r\n opts.ApiEndPoint = new UriBuilder(\"https\", \"my-host\", 443).Uri;\r\n opts.AccessToken = \"my-token\";\r\n opts.AuthStrategy = KubeAuthStrategy.BearerToken;\r\n opts.AllowInsecure = true; \r\n };\r\n builder.Services\r\n .AddOptions()\r\n .Configure(configureKubeClient); // manual binding options via IOptions\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddKubernetes(false); // don't use pod service account, and IOptions is reused\r\n\r\n .. _break: http://break.do\r\n\r\n **Note**, this could also be written like this (shortened version):\r\n\r\n .. code-block:: csharp\r\n :emphasize-lines: 2, 10\r\n\r\n builder.Services\r\n .AddKubeClientOptions(opts =>\r\n {\r\n opts.ApiEndPoint = new UriBuilder(\"https\", \"my-host\", 443).Uri;\r\n opts.AuthStrategy = KubeAuthStrategy.BearerToken;\r\n opts.AccessToken = \"my-token\";\r\n opts.AllowInsecure = true;\r\n })\r\n .AddOcelot(builder.Configuration)\r\n .AddKubernetes(false); // don't use pod service account, and client options provided via AddKubeClientOptions\r\n\r\n Finally, it creates the `KubeClient`_ from your options.\r\n\r\n **Note 1**: For understanding the ``IOptions`` interface, please refer to the Microsoft Learn documentation: `Options pattern in .NET `_.\r\n\r\n **Note 2**: Please consider this Case 2 as an example of manual setup when you **do not** use a pod service account.\r\n We recommend using our official extension method, which receives an ``Action`` argument with your options: refer to the :ref:`k8s-addkubernetes-action-method` below.\r\n\r\n.. _k8s-addkubernetes-action-method:\r\n\r\n``AddKubernetes(Action)`` method [#f2]_\r\n----------------------------------------------------------\r\n\r\n.. code-block:: csharp\r\n :emphasize-lines: 3\r\n\r\n public static class OcelotBuilderExtensions\r\n {\r\n public static IOcelotBuilder AddKubernetes(this IOcelotBuilder builder, Action configureOptions, /*optional params*/);\r\n }\r\n\r\nThis extension method adds `K8s`_ services **without** using a pod service account, explicitly calling an action to initialize configuration options for `KubeClient`_.\r\nIt operates in two modes:\r\n\r\n1. If ``configureOptions`` is provided (action is not null), it calls the action, ignoring all optional arguments.\r\n\r\n .. code-block:: csharp\r\n :emphasize-lines: 8\r\n\r\n Action configureKubeClient = opts => \r\n {\r\n opts.ApiEndPoint = new UriBuilder(\"https\", \"my-host\", 443).Uri;\r\n // ...\r\n };\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddKubernetes(configureKubeClient); // without optional arguments\r\n\r\n.. _break: http://break.do\r\n\r\n **Note**: Optional arguments do not make sense; all settings are defined inside the ``configureKubeClient`` action.\r\n\r\n2. If ``configureOptions`` is not provided (action is null), it reads the global ``ServiceDiscoveryProvider`` :ref:`k8s-configuration` options and reuses them to initialize the following properties:\r\n ``ApiEndPoint``, ``AccessToken``, and ``KubeNamespace``, finally initializing the rest of the properties with optional arguments.\r\n\r\n .. code-block:: csharp\r\n :emphasize-lines: 3, 5\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddKubernetes(null, allowInsecure: true, /*optional args*/) // shortened version\r\n // or\r\n .AddKubernetes(configureOptions: null, allowInsecure: true, /*optional args*/); // long version\r\n\r\n.. _break2: http://break.do\r\n\r\n **Note**: Optional arguments must be used here in addition to the options coming from the global ``ServiceDiscoveryProvider`` :ref:`k8s-configuration`.\r\n Find the comprehensive documentation in the C# code of the `AddKubernetes `_ methods.\r\n\r\n.. _k8s-configuration:\r\n\r\nConfiguration\r\n-------------\r\n\r\nThe following examples show how to set up a route that will work in Kubernetes.\r\nThe most important thing is the ``ServiceName`` which is made up of the Kubernetes service name.\r\nWe also need to set up the ``ServiceDiscoveryProvider`` in ``GlobalConfiguration``.\r\n\r\nRegarding global and route configurations, if your downstream service resides in a different namespace, you can override the global setting at the route level by specifying a ``ServiceNamespace``.\r\n\r\n.. code-block:: json\r\n\r\n \"Routes\": [\r\n {\r\n \"ServiceName\": \"my-service\",\r\n \"ServiceNamespace\": \"my-namespace\"\r\n }\r\n ]\r\n\r\n.. _k8s-kube-provider:\r\n\r\n``Kube`` provider\r\n-----------------\r\n\r\nThe example here shows a typical configuration:\r\n\r\n.. code-block:: json\r\n\r\n \"Routes\": [\r\n {\r\n \"ServiceName\": \"my-service\",\r\n // ...\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"ServiceDiscoveryProvider\": {\r\n \"Scheme\": \"https\",\r\n \"Host\": \"my-host\",\r\n \"Port\": 443,\r\n \"Token\": \"my-token\",\r\n \"Namespace\": \"Dev\",\r\n \"Type\": \"Kube\"\r\n }\r\n }\r\n\r\nService deployment in ``Dev`` namespace, and discovery provider type is ``Kube``, you also can set :ref:`PollKube ` or :ref:`WatchKube ` provider type.\r\n\r\n **Note 1**: ``Scheme``, ``Host``, ``Port``, and ``Token`` are not used if ``usePodServiceAccount`` is true when `KubeClient`_ is created from a pod service account.\r\n Please refer to the :ref:`k8s-install` section for technical details.\r\n\r\n **Note 2**: The ``Kube`` provider searches for the service entry using ``ServiceName`` and then retrieves the first available port from the ``EndpointSubsetV1.Ports`` collection.\r\n Therefore, if the port name is not specified, the default downstream scheme will be ``http``; \r\n Please refer to the \":ref:`Downstream Scheme vs Port Names `\" section for technical details.\r\n\r\n.. _k8s-pollkube-provider:\r\n\r\n``PollKube`` provider [#f3]_\r\n----------------------------\r\n\r\nYou use Ocelot to poll Kubernetes for latest service information rather than per request.\r\nIf you want to poll Kubernetes for the latest services rather than per request (default behaviour of the :ref:`k8s-kube-provider`) then you need to set the following configuration:\r\n\r\n.. code-block:: json\r\n\r\n \"ServiceDiscoveryProvider\": {\r\n \"Namespace\": \"dev\",\r\n \"Type\": \"PollKube\",\r\n \"PollingInterval\": 100 // ms\r\n } \r\n\r\nThe polling interval is in milliseconds and tells Ocelot how often to call Kubernetes for changes in service configuration.\r\n\r\n **Note**, there are tradeoffs here.\r\n If you poll Kubernetes, it is possible Ocelot will not know if a service is down depending on your polling interval and you might get more errors than if you get the latest services per request.\r\n This really depends on how volatile your services are.\r\n We doubt it will matter for most people and polling may give a tiny performance improvement over calling Kubernetes per request.\r\n There is no way for Ocelot to work these out for you, except perhaps through a `discussion `_. \r\n\r\n.. _k8s-watchkube-provider:\r\n\r\n``WatchKube`` provider [#f4]_\r\n-----------------------------\r\n.. _Kubernetes API: https://kubernetes.io/docs/reference/using-api/\r\n.. _watch requests: https://kubernetes.io/docs/reference/using-api/api-concepts/#efficient-detection-of-changes\r\n\r\nWith this configuration, `Kubernetes API`_ \"`watch requests`_\" are used to fetch service configuration.\r\nEssentially, it establishes one streamed HTTP connection with the `Kubernetes API`_ per downstream service.\r\nChanges streamed through this connection will be used to update the list of available endpoints.\r\n\r\n.. code-block:: json\r\n\r\n \"ServiceDiscoveryProvider\": {\r\n \"Namespace\": \"dev\",\r\n \"Type\": \"WatchKube\"\r\n }\r\n\r\n.. note::\r\n\r\n The ``WatchKube`` provider is specifically designed for high-load Ocelot vs. Kubernetes environments with high RPS ratios.\r\n To better understand which type is suitable for your needs, we have added a table :ref:`k8s-comparing-providers`.\r\n\r\nThe provider has an implicit configuration for fine-tuned watching, which are available and can only be initialized in C# code.\r\n\r\n* ``WatchKube.FirstResultsFetchingTimeoutSeconds``: `This `_ is the default number of seconds to wait after Ocelot starts, following the provider's creation, to fetch the first result from the Kubernetes endpoint. :sup:`1`\r\n* ``WatchKube.FailedSubscriptionRetrySeconds``: `This `__ is the default number of seconds to wait before scheduling the next retry for the subscription operation. :sup:`1`\r\n\r\n.. _break3: http://break.do\r\n\r\n :sup:`1` For both ``static int`` properties, the default value is 1 (one) second. The constraint ensures that the assigned value is greater than or equal to 1 (one). Therefore, the minimum value is 1 (one) second.\r\n \r\n.. _k8s-comparing-providers:\r\n\r\nComparing providers\r\n-------------------\r\nThis table explains the most important indicators that may influence Ocelot vs. Kubernetes deployment or DevOps strategy.\r\nThe evolution path of all providers follows: ``Kube`` -> ``PollKube`` -> ``WatchKube``, with ``WatchKube`` being the most advanced provider.\r\n\r\n.. list-table::\r\n :widths: 34 22 22 22\r\n :header-rows: 1\r\n\r\n * - *Indicators \\\\ Providers*\r\n - :ref:`Kube `\r\n - :ref:`PollKube `\r\n - :ref:`WatchKube `\r\n * - Extra latency\r\n - One hop per route\r\n - \\-\r\n - \\-\r\n * - Speed of response to endpoints changes\r\n - High\r\n - Low :sup:`1`\r\n - High\r\n * - Pressure on `Kubernetes API`_\r\n - High\r\n - Low :sup:`1`\r\n - Low\r\n * - Ocelot load (estimated) :sup:`2`\r\n - < 1000 RPS\r\n - > 1000 RPS\r\n - > 5000 RPS\r\n * - Ocelot deployment :sup:`3`\r\n - Single instance\r\n - Multiple instances\r\n - Cluster of instances\r\n\r\n.. _break4: http://break.do\r\n\r\n | :sup:`1` Depends on the ``PollingInterval`` option.\r\n | :sup:`2` Please consider this a rough load estimation, as our team has not provided any tests or benchmarks.\r\n | :sup:`3` The term \"instance\" refers to an Ocelot instance, not a Kubernetes one.\r\n\r\n.. _k8s-downstream-scheme-vs-port-names:\r\n\r\nDownstream Scheme vs Port Names [#f5]_\r\n--------------------------------------\r\n\r\nKubernetes configuration permits the definition of multiple ports with names for each address of an endpoint subset.\r\nWhen binding multiple ports, you assign a name to each subset port.\r\nTo allow the ``Kube`` provider to recognize the desired port by its name, you need to specify the ``DownstreamScheme`` with the port's name;\r\nif not, the collection's first port entry will be chosen by default.\r\n\r\nFor instance, consider a service on Kubernetes that exposes two ports: ``https`` for 443 and ``http`` for 80, as follows:\r\n\r\n.. code-block:: text\r\n\r\n Name: my-service\r\n Namespace: default\r\n Subsets:\r\n Addresses: 10.1.161.59\r\n Ports:\r\n Name Port Protocol\r\n ---- ---- --------\r\n https 443 TCP\r\n http 80 TCP\r\n\r\n**When** you need to use the ``http`` port while intentionally bypassing the default ``https`` port (first one),\r\nyou must define ``DownstreamScheme`` to enable the provider to recognize the desired ``http`` port by comparing ``DownstreamScheme`` with the port name as follows:\r\n\r\n.. code-block:: json\r\n\r\n \"Routes\": [\r\n {\r\n \"ServiceName\": \"my-service\",\r\n \"DownstreamScheme\": \"http\", // port name -> http -> port is 80\r\n }\r\n ]\r\n\r\n.. note::\r\n\r\n In the absence of a specified ``DownstreamScheme`` (the default behavior), the :ref:`k8s-kube-provider`—as well as other providers—will select *the first available port* from the ``EndpointSubsetV1.Ports`` collection.\r\n Consequently, if the port name is not designated, the default downstream scheme utilized will be ``http``.\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] The \":doc:`../features/kubernetes`\" feature was requested as part of issue `345`_ to add support for `Kubernetes `_ :doc:`../features/servicediscovery` provider, and released in version `13.5.0`_ \r\n.. [#f2] The \":ref:`AddKubernetes(Action{KubeClientOptions}) method `\" was requested as part of issue `2255`_ (pull request `2257`_), and released in version `24.0`_\r\n.. [#f3] The evolution of the \":ref:`PollKube provider `\" began with pull request `772`_ (version `13.2.0`_).\r\n Since then, the provider's design was reviewed due to reported bug `2304`_, and patch `2335`_ was applied and rolled out in version `24.1`_.\r\n.. [#f4] The \":ref:`WatchKube provider `\" was first discussed in thread `2168`_, later implemented in pull request `2174`_, and released in version `24.1`_.\r\n.. [#f5] The \":ref:`Downstream Scheme vs Port Names `\" feature was requested as part of issue `1967`_ and released in version `23.3`_\r\n\r\n.. _345: https://github.com/ThreeMammals/Ocelot/issues/345\r\n.. _772: https://github.com/ThreeMammals/Ocelot/pull/772\r\n.. _1134: https://github.com/ThreeMammals/Ocelot/pull/1134\r\n.. _1967: https://github.com/ThreeMammals/Ocelot/issues/1967\r\n.. _2168: https://github.com/ThreeMammals/Ocelot/discussions/2168\r\n.. _2174: https://github.com/ThreeMammals/Ocelot/pull/2174\r\n.. _2255: https://github.com/ThreeMammals/Ocelot/issues/2255\r\n.. _2257: https://github.com/ThreeMammals/Ocelot/pull/2257\r\n.. _2304: https://github.com/ThreeMammals/Ocelot/issues/2304\r\n.. _2335: https://github.com/ThreeMammals/Ocelot/pull/2335\r\n.. _13.2.0: https://github.com/ThreeMammals/Ocelot/releases/tag/13.2.0\r\n.. _13.5.0: https://github.com/ThreeMammals/Ocelot/releases/tag/13.5.0\r\n.. _23.3: https://github.com/ThreeMammals/Ocelot/releases/tag/23.3.0\r\n.. _24.0: https://github.com/ThreeMammals/Ocelot/releases/tag/24.0.0\r\n.. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0\r\n"
},
{
"path": "docs/features/loadbalancer.rst",
"content": ".. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json\r\n.. _Program: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/Program.cs\r\n\r\nLoad Balancer\r\n=============\r\n\r\nOcelot can load balance across available downstream services for each route.\r\nThis means you can scale your downstream services, and Ocelot can use them effectively.\r\n\r\n``LoadBalancerOptions`` Schema\r\n------------------------------\r\n\r\n.. _FileLoadBalancerOptions: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileLoadBalancerOptions.cs\r\n\r\n Class: `FileLoadBalancerOptions`_\r\n\r\nThe following is the full *load balancer* configuration, used in both the :ref:`config-route-schema` and the :ref:`config-dynamic-route-schema`.\r\nNot all of these options need to be configured; however, the ``Type`` option is mandatory.\r\n\r\n.. code-block:: json\r\n\r\n \"LoadBalancerOptions\": {\r\n \"Type\": \"\",\r\n \"Key\": \"\", // CookieStickySessions balancer\r\n \"Expiry\": 1 // ms, CookieStickySessions balancer\r\n }\r\n\r\n.. list-table::\r\n :widths: 15 85\r\n :header-rows: 1\r\n\r\n * - *Option*\r\n - *Description*\r\n * - ``Type``\r\n - An in-built *load balancer* type selected from the list of available :ref:`lb-balancers`, or a user-defined type (refer to the \":ref:`Custom Balancers `\" section).\r\n * - ``Key``\r\n - The name of the cookie you wish to use for sticky sessions. This option is applicable only to the :ref:`CookieStickySessions type `.\r\n * - ``Expiry``\r\n - Expiration period specifies how long, in milliseconds, the session should remain sticky.\r\n This value refreshes with each request to mimic typical session behavior. Note: This option applies only to the :ref:`CookieStickySessions type `.\r\n\r\nThe actual ``LoadBalancerOptions`` schema with all the properties can be found in the C# `FileLoadBalancerOptions`_ class.\r\n\r\n.. _lb-configuration:\r\n\r\nConfiguration\r\n-------------\r\n\r\nThe following shows how to set up multiple downstream services for a static route using `ocelot.json`_ and then select the ``LeastConnection`` *load balancer*.\r\nThis is the simplest way to configure load balancing without using service discovery.\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 10-12\r\n\r\n {\r\n \"UpstreamPathTemplate\": \"/posts/{postId}\",\r\n \"UpstreamHttpMethod\": [ \"Put\", \"Delete\" ],\r\n \"DownstreamPathTemplate\": \"/api/posts/{postId}\",\r\n \"DownstreamScheme\": \"https\",\r\n \"DownstreamHostAndPorts\": [\r\n { \"Host\": \"10.0.1.10\", \"Port\": 5000 },\r\n { \"Host\": \"10.0.1.11\", \"Port\": 5000 }\r\n ],\r\n \"LoadBalancerOptions\": {\r\n \"Type\": \"LeastConnection\"\r\n }\r\n }\r\n\r\nThe following shows how to set up a route using :doc:`../features/servicediscovery` and then select the ``RoundRobin`` *load balancer*.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n // ...\r\n \"ServiceName\": \"product\",\r\n \"LoadBalancerOptions\": {\r\n \"Type\": \"RoundRobin\"\r\n }\r\n }\r\n\r\nWhen this is set up, Ocelot will look up the downstream host and port from the :doc:`../features/servicediscovery` provider and load balance requests across any available services.\r\nIf you add and remove services from the :doc:`../features/servicediscovery` provider [#f1]_,\r\nOcelot should respect this and stop calling services that have been removed and start calling services that have been added.\r\n\r\n.. _lb-global-configuration:\r\n\r\nGlobal Configuration [#f2]_\r\n^^^^^^^^^^^^^^^^^^^^^^^^^^^\r\n\r\nA complete configuration consists of both route-level and global *load balancing*.\r\nYou can configure the following options in the ``GlobalConfiguration`` section of `ocelot.json`_:\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 4-8, 12, 17-20\r\n\r\n \"Routes\": [\r\n {\r\n \"Key\": \"R0\", // optional\r\n \"LoadBalancerOptions\": {\r\n \"Type\": \"CookieStickySessions\",\r\n \"Key\": \".AspNetCore.Session\",\r\n \"Expiry\": 1200000 // milliseconds, 20 minutes\r\n }\r\n },\r\n {\r\n \"Key\": \"R1\", // this route is part of a group\r\n \"LoadBalancerOptions\": {} // optional due to grouping\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"https://ocelot.net\",\r\n \"LoadBalancerOptions\": {\r\n \"RouteKeys\": [\"R1\"], // if undefined or empty array, opts will apply to all routes\r\n \"Type\": \"LeastConnection\"\r\n }\r\n }\r\n\r\n:doc:`../features/servicediscovery` dynamic routes intentionally override the global :ref:`dynamic routing ` configuration:\r\n\r\n.. code-block:: json\r\n :emphasize-lines: 5-7, 16-19\r\n\r\n \"DynamicRoutes\": [\r\n {\r\n \"Key\": \"\", // optional\r\n \"ServiceName\": \"my-service\",\r\n \"LoadBalancerOptions\": {\r\n \"Type\": \"LeastConnection\" // switch from RoundRobin to LeastConnection\r\n }\r\n }\r\n ],\r\n \"GlobalConfiguration\": {\r\n \"BaseUrl\": \"https://ocelot.net\",\r\n \"DownstreamScheme\": \"http\",\r\n \"ServiceDiscoveryProvider\": {\r\n // required section for dynamic routing\r\n },\r\n \"LoadBalancerOptions\": {\r\n \"RouteKeys\": [], // no grouping, thus opts apply to all dynamic routes\r\n \"Type\": \"RoundRobin\"\r\n }\r\n }\r\n\r\nIn this configuration, the ``RoundRobin`` balancer is used for all implicit dynamic routes.\r\nHowever, for the \"my-service\" service, the load balancer type has been explicitly switched from ``RoundRobin`` to ``LeastConnection``.\r\n\r\n.. note::\r\n\r\n 1. If the ``RouteKeys`` option is not defined or the array is empty in the global ``LoadBalancerOptions``, the global options will apply to all routes.\r\n If the array contains route keys, it defines a single group of routes to which the global options apply.\r\n Routes excluded from this group must specify their own route-level ``LoadBalancerOptions``.\r\n\r\n 2. Prior to version `24.1`_, global ``LoadBalancerOptions`` were only accessible in the special :ref:`Dynamic Routing ` mode.\r\n Since version `24.1`_, global configuration has been available for both static and dynamic routes.\r\n As a team, we would consider the idea of implementing such a global configuration for aggregated routes.\r\n However, an aggregated route is essentially a combination of static routes.\r\n\r\n.. _lb-balancers:\r\n\r\nBalancers\r\n---------\r\n\r\nThe available types of built-in *load balancers* are:\r\n\r\n.. list-table::\r\n :widths: 25 75\r\n :header-rows: 1\r\n\r\n * - *Type*\r\n - *Description*\r\n * - ``CookieStickySessions``\r\n - This uses a cookie to stick all requests to a specific server. More information can be found in the \":ref:`CookieStickySessions Type`\" section.\r\n * - ``LeastConnection``\r\n - This tracks which services are dealing with requests and sends new requests to the service with the fewest (\"least\") existing requests. The algorithm state is not distributed across a cluster of Ocelots.\r\n * - ``RoundRobin``\r\n - This loops through available services and sends requests. The algorithm state is not distributed across a cluster of Ocelots.\r\n * - ``NoLoadBalancer``\r\n - This takes the first available service from :ref:`configuration ` or :doc:`../features/servicediscovery` provider.\r\n\r\nYou must choose which *load balancer* to use in your :ref:`configuration `.\r\n\r\n.. _lb-cookiestickysessions-type:\r\n\r\n``CookieStickySessions`` Type [#f3]_\r\n------------------------------------\r\n\r\nWe have implemented a basic sticky session type of *load balancer*.\r\nThe scenario it is meant to support involves having a number of downstream servers that do not share session state.\r\nIf you receive more than one request for one of these servers, it should go to the same server each time; otherwise, the session state might be incorrect for the given user.\r\n\r\nIn order to set up the ``CookieStickySessions`` *load balancer*, you need to do something like the following:\r\n\r\n.. code-block:: json\r\n\r\n {\r\n \"UpstreamPathTemplate\": \"/posts/{postId}\",\r\n \"UpstreamHttpMethod\": [ \"Put\", \"Delete\" ],\r\n \"DownstreamPathTemplate\": \"/api/posts/{postId}\",\r\n \"DownstreamScheme\": \"https\",\r\n \"DownstreamHostAndPorts\": [\r\n { \"Host\": \"10.0.1.10\", \"Port\": 5000 },\r\n { \"Host\": \"10.0.1.11\", \"Port\": 5000 }\r\n ],\r\n \"LoadBalancerOptions\": {\r\n \"Type\": \"CookieStickySessions\",\r\n \"Key\": \".AspNetCore.Session\",\r\n \"Expiry\": 1200000 // milliseconds, 20 minutes\r\n }\r\n }\r\n\r\nThese ``LoadBalancerOptions`` configure the ``CookieStickySessions`` load balancer using the standard session cookie ``Key`` for ASP.NET Core apps with sessions enabled.\r\nThe default expiration time is 20 minutes, matching the default session timeout in ASP.NET Core.\r\n\r\n **Note 1**: If you have multiple routes with the same ``LoadBalancerOptions``, then all of those routes will use the same *load balancer* for their subsequent requests.\r\n This means the sessions will be stuck across routes.\r\n\r\n **Note 2**: If you define more than one ``DownstreamHostAndPort``, or if you are using a :doc:`../features/servicediscovery` provider such as :ref:`sd-consul` and it returns more than one service, then ``CookieStickySessions`` uses ``RoundRobin`` to select the next server.\r\n This is hard-coded at the moment but could be changed.\r\n\r\n.. _lb-custom-balancers:\r\n\r\nCustom Balancers [#f4]_\r\n-----------------------\r\n\r\nIn order to create and use a custom *load balancer*, you can do the following.\r\nBelow, we set up a basic load balancing configuration, and note that the ``Type`` is ``MyLoadBalancer``, which is the name of a class we will set up to perform load balancing.\r\n\r\n.. code-block:: json\r\n\r\n {\r\n // ...\r\n \"DownstreamHostAndPorts\": [\r\n { \"Host\": \"10.0.1.10\", \"Port\": 5000 },\r\n { \"Host\": \"10.0.1.11\", \"Port\": 5000 }\r\n ],\r\n \"LoadBalancerOptions\": {\r\n \"Type\": \"MyLoadBalancer\"\r\n }\r\n }\r\n\r\nThen, you need to create a class that implements the ``ILoadBalancer`` interface. Below is a simple round-robin example:\r\n\r\n.. code-block:: csharp\r\n\r\n using Ocelot.LoadBalancer.LoadBalancers;\r\n using Ocelot.Responses;\r\n using Ocelot.Values;\r\n\r\n public class MyLoadBalancer : ILoadBalancer\r\n {\r\n private readonly Func>> _services;\r\n private static object Locker = new();\r\n private int _last;\r\n\r\n public MyLoadBalancer() { }\r\n public MyLoadBalancer(Func>> services)\r\n => _services = services;\r\n\r\n public string Type => nameof(MyLoadBalancer);\r\n public void Release(ServiceHostAndPort hostAndPort) { }\r\n\r\n public async Task> LeaseAsync(HttpContext context)\r\n {\r\n var services = await _services.Invoke();\r\n lock (Locker)\r\n {\r\n _last = (_last >= services.Count) ? 0 : _last;\r\n var next = services[_last++];\r\n return new OkResponse(next.HostAndPort);\r\n }\r\n }\r\n }\r\n\r\nFinally, you need to register this class with Ocelot.\r\nWe have used the most complex example below to show all of the data and types that can be passed into the factory that creates *load balancers*.\r\n\r\n.. code-block:: csharp\r\n\r\n using Ocelot.Configuration;\r\n using Ocelot.DependencyInjection;\r\n using Ocelot.ServiceDiscovery.Providers;\r\n\r\n Func lbFactory\r\n = (serviceProvider, Route, discoveryProvider) => new MyLoadBalancer(discoveryProvider.GetAsync);\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddCustomLoadBalancer(lbFactory);\r\n\r\nHowever, there is a much simpler example that will work the same way:\r\n\r\n.. code-block:: csharp\r\n\r\n using Ocelot.DependencyInjection;\r\n\r\n builder.Services\r\n .AddOcelot(builder.Configuration)\r\n .AddCustomLoadBalancer();\r\n\r\n.. note::\r\n\r\n 1. There are numerous ``IOcelotBuilder`` `methods `_ to add a custom *load balancer*.\r\n The interface is as follows:\r\n\r\n .. code-block:: csharp\r\n\r\n IOcelotBuilder AddCustomLoadBalancer()\r\n where T : ILoadBalancer, new();\r\n IOcelotBuilder AddCustomLoadBalancer(Func loadBalancerFactoryFunc)\r\n where T : ILoadBalancer;\r\n IOcelotBuilder AddCustomLoadBalancer(Func loadBalancerFactoryFunc)\r\n where T : ILoadBalancer;\r\n IOcelotBuilder AddCustomLoadBalancer(Func loadBalancerFactoryFunc)\r\n where T : ILoadBalancer;\r\n IOcelotBuilder AddCustomLoadBalancer(Func loadBalancerFactoryFunc)\r\n where T : ILoadBalancer;\r\n\r\n 2. When you enable custom *load balancers*, Ocelot looks up your *load balancer* by its class name when it decides whether to perform load balancing.\r\n\r\n * If it finds a match, it will use your load balancer to load balance.\r\n * If Ocelot cannot match the *load balancer* type in your configuration with the name of the registered *load balancer* class, then you will receive an HTTP `500 Internal Server Error`_.\r\n * If your *load balancer* factory throws an exception when Ocelot calls it, you will receive an HTTP `500 Internal Server Error`_.\r\n\r\n.. warning::\r\n\r\n Remember, if you specify no *load balancer* in your :ref:`lb-configuration`, Ocelot will not attempt to load balance.\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] Currently supported :doc:`../features/servicediscovery` providers are :ref:`sd-consul`, :doc:`Kubernetes <../features/kubernetes>`, :ref:`Eureka `, :doc:`../features/servicefabric`, and manually developed :ref:`sd-custom-providers`.\r\n.. [#f2] The \":ref:`Global Configuration `\" feature, as part of issue `585`_, was introduced in pull request `2324`_ and released in version `24.1`_.\r\n.. [#f3] The \":ref:`CookieStickySessions Type `\" feature was requested in issue `322`_, though what the user wants is more complicated than just sticky sessions. Anyway, we thought this would be a nice feature to have! Initially, the feature was released in version `6.0.0`_.\r\n.. [#f4] The \":ref:`Custom Balancers `\" feature by `David Lievrouw`_ implemented a way to provide Ocelot with a custom *load balancer* in pull request `1155`_ (issue `961`_, released in version `15.0.3`_).\r\n\r\n.. _322: https://github.com/ThreeMammals/Ocelot/issues/322\r\n.. _585: https://github.com/ThreeMammals/Ocelot/issues/585\r\n.. _961: https://github.com/ThreeMammals/Ocelot/issues/961\r\n.. _1155: https://github.com/ThreeMammals/Ocelot/pull/1155\r\n.. _2324: https://github.com/ThreeMammals/Ocelot/pull/2324\r\n.. _6.0.0: https://github.com/ThreeMammals/Ocelot/releases/tag/6.0.0\r\n.. _15.0.3: https://github.com/ThreeMammals/Ocelot/releases/tag/15.0.3\r\n.. _24.1: https://github.com/ThreeMammals/Ocelot/releases/tag/24.1.0\r\n.. _David Lievrouw: https://github.com/DavidLievrouw\r\n.. _500 Internal Server Error: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500\r\n"
},
{
"path": "docs/features/logging.rst",
"content": ".. _Logging in .NET Core and ASP.NET Core: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/logging\r\n.. _Serilog: https://serilog.net\r\n\r\nLogging\r\n=======\r\n\r\n | MS Learn: `Logging in .NET Core and ASP.NET Core`_\r\n | Interfaces: `ILoggerFactory `_ and `ILogger `_\r\n\r\nOcelot uses the standard ASP.NET Core logging interfaces ``ILoggerFactory`` and ``ILogger`` at the moment.\r\nThis is encapsulated in `IOcelotLogger `_ and `IOcelotLoggerFactory `_ with the implementation for the standard `ASP.NET Core logging `_ stuff at the moment.\r\nThis is because Ocelot adds some extra info to the logs such as :ref:`lg-request-id` if it is configured.\r\n\r\nThere is a global :doc:`../features/errorcodes` :ref:`eh-middleware` that catches any exceptions thrown and logs them as errors.\r\nFinally, if logging is set to the ``Trace`` level, Ocelot will log the start, finish, and any middlewares that throw an exception, which can be quite useful.\r\n\r\n.. _lg-warning:\r\n\r\nWarning\r\n-------\r\n\r\nIf you are logging to the MS `Console `_, you will experience terrible performance.\r\nThe community has encountered many performance issues with Ocelot, and it is always related to the ``Debug`` logging level when logging to the console/terminal.\r\n\r\n- **Warning**! Make sure you are logging to an appropriate destination/storage in the production environment!\r\n- Use ``Error`` and ``Critical`` levels in the production environment!\r\n- Use the ``Warning`` level in testing & staging environments!\r\n\r\nThese and other recommendations can be found below in the :ref:`lg-best-practices` section.\r\n\r\n.. _lg-best-practices:\r\n\r\nBest Practices\r\n--------------\r\n\r\n Microsoft Learn complete reference: `Logging in .NET Core and ASP.NET Core`_\r\n\r\nOur recommendations for achieving the best logging with Ocelot are as follows.\r\n\r\n1. Ensure the minimum log level while `Configure logging `_.\r\n The minimum log level is set in the application's ``appsettings.json`` file.\r\n This level is defined in the ``Logging`` section, for example:\r\n\r\n .. code-block:: json\r\n\r\n {\r\n \"Logging\": {\r\n \"LogLevel\": {\r\n \"Default\": \"Information\",\r\n \"Microsoft.AspNetCore\": \"Warning\"\r\n }\r\n }\r\n }\r\n\r\n Whether you are using `Serilog`_ or the standard Microsoft providers, the logging configuration will be retrieved from this section.\r\n\r\n .. code-block:: csharp\r\n :emphasize-lines: 3\r\n\r\n builder.Configuration\r\n .SetBasePath(builder.Environment.ContentRootPath)\r\n .AddJsonFile($\"appsettings.{builder.Environment.EnvironmentName}.json\", false, false) // read logging settings of the environment\r\n .AddOcelot(builder.Environment);\r\n\r\n However, there is one thing to be aware of. It is possible to use the ``SetMinimumLevel()`` method to define the minimum logging level.\r\n Be careful and make sure you set the log level in only one place, like this:\r\n\r\n .. code-block:: csharp\r\n\r\n builder.Logging\r\n .ClearProviders()\r\n .SetMinimumLevel(LogLevel.Warning);\r\n // MS Console for Development and/or Testing environments only\r\n if (!builder.Environment.IsProduction())\r\n {\r\n builder.Logging.AddConsole();\r\n }\r\n\r\n Please also use the ``ClearProviders()`` method so that only the providers you wish to use are taken into account, such as the console in the example above.\r\n\r\n2. Ensure the proper usage of the minimum logging level for each environment: development, testing, production, etc.\r\n So, once again, read the important notes in the :ref:`lg-warning` section!\r\n\r\n3. Ocelot's logging has been improved in version `22.0`_:\r\n it is now possible to use a factory method for message strings that will only be executed if the minimum log level allows it.\r\n\r\n For example, let's take a message containing information about several variables that should only be generated if the minimum log level is ``Debug``.\r\n If the minimum log level is ``Warning``, then the string is never generated.\r\n\r\n Therefore, when the string contains dynamic information (e.g., ``string.Format``), or the string value is generated by a `string interpolation `_ expression,\r\n it is recommended to call the ``LogX`` method using an anonymous delegate via an ``=>`` expression function:\r\n\r\n .. code-block:: csharp\r\n\r\n Logger.LogDebug(\r\n () => $\"Downstream template is {httpContext.Items.DownstreamRoute().DownstreamPathTemplate.Value}\");\r\n\r\n otherwise a constant string is sufficient\r\n\r\n .. code-block:: csharp\r\n\r\n Logger.LogDebug(\"My const string\");\r\n\r\n.. _lg-request-id:\r\n\r\nRequest ID\r\n----------\r\n\r\n Also known as \"Correlation ID\" or `HttpContext.TraceIdentifier `_\r\n\r\nOcelot allows a client to send a *Request ID* through an HTTP header.\r\nIf provided, Ocelot uses the *Request ID* for logging as soon as it becomes available in the middleware pipeline.\r\nAdditionally, Ocelot forwards the *Request ID* via the specified header to the downstream service.\r\n\r\n * You can still obtain the ASP.NET Core *Request ID* in the logs if you set ``IncludeScopes`` to ``true`` in your logging configuration.\r\n * The reason for not just using the `bog standard `_ framework logging is that\r\n we could not work out how to override the ``RequestId`` that gets logged when setting ``IncludeScopes`` to ``true`` in the logging settings.\r\n Nicely onto the next feature.\r\n\r\nEvery log record has these 2 properties:\r\n\r\n.. list-table::\r\n :widths: 25 75\r\n :header-rows: 1\r\n\r\n * - *Property*\r\n - *Description*\r\n * - ``RequestId``\r\n - This represents ID of the current request as plain string, for example ``0HMVD33IIJRFR:00000001``\r\n * - ``PreviousRequestId``\r\n - This represents ID of the previous request\r\n\r\n.. _break: http://break.do\r\n\r\n As an ``IOcelotLogger`` interface object is injected into the constructors of service classes, the current default Ocelot logger (``OcelotLogger`` class) reads these two properties from the ``IRequestScopedDataRepository`` interface object.\r\n\r\nFind out more about these properties and other details on the *Request ID* logging feature below.\r\n\r\nConfiguration\r\n^^^^^^^^^^^^^\r\n\r\nIn order to use the *Request ID* feature, you have two options: specifying it globally or for the route.\r\n\r\nIn your `ocelot.json`_, set the following configuration in the ``GlobalConfiguration`` section.\r\nThis setting will apply to all requests processed by Ocelot.\r\n\r\n.. code-block:: json\r\n\r\n \"GlobalConfiguration\": {\r\n \"RequestIdKey\": \"Oc-RequestId\"\r\n }\r\n\r\n.. _break: http://break.do\r\n\r\n We recommend using the ``GlobalConfiguration`` unless it is absolutely necessary to make it route-specific.\r\n\r\nIf you want to override this for a specific route, add the following to `ocelot.json`_:\r\n\r\n.. code-block:: json\r\n\r\n \"RequestIdKey\": \"Oc-RequestId\"\r\n\r\nOnce Ocelot identifies incoming requests that match a route, it will set the *Request ID* based on the route configuration.\r\n\r\nProblem\r\n^^^^^^^\r\n\r\nThis can lead to a small issue.\r\nIf you set a ``GlobalConfiguration``, it is possible to use one *Request ID* until the route is identified and then another afterward, as the *Request ID* key can change.\r\nThis behavior is intentional and represents the best solution we have devised for now.\r\nIn this case, the ``OcelotLogger`` will display both the current *Request ID* and the previous *Request ID* in the logs.\r\n\r\nBelow is an example of the logging when the ``Debug`` level is set for a normal request:\r\n\r\n .. code-block:: text\r\n\r\n info: Microsoft.AspNetCore.Hosting.Diagnostics[1]\r\n Request starting HTTP/1.1 GET https://localhost:7778/ocelot2/posts/3 - - -\r\n dbug: Ocelot.Errors.Middleware.ExceptionHandlerMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n Ocelot pipeline started\r\n dbug: Ocelot.DownstreamRouteFinder.Middleware.DownstreamRouteFinderMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n Upstream URL path: /ocelot2/posts/3\r\n dbug: Ocelot.DownstreamRouteFinder.Middleware.DownstreamRouteFinderMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n Downstream templates: /ocelot/posts/{id}\r\n info: Ocelot.RateLimiting.Middleware.RateLimitingMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n EnableEndpointEndpointRateLimiting is not enabled for downstream path: /ocelot/posts/{id}\r\n info: Ocelot.Authentication.Middleware.AuthenticationMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n No authentication needed for path: /ocelot2/posts/3\r\n info: Ocelot.Authorization.Middleware.AuthorizationMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n No authorization needed for upstream path: /ocelot2/posts/{id}\r\n dbug: Ocelot.DownstreamUrlCreator.Middleware.DownstreamUrlCreatorMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n Downstream URL: http://localhost:5555/ocelot/posts/3\r\n info: Microsoft.AspNetCore.Hosting.Diagnostics[1]\r\n Request starting HTTP/1.1 GET https://localhost:7778/ocelot2/posts/5 - - -\r\n dbug: Ocelot.Errors.Middleware.ExceptionHandlerMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n Ocelot pipeline started\r\n dbug: Ocelot.DownstreamRouteFinder.Middleware.DownstreamRouteFinderMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n Upstream URL path: /ocelot2/posts/5\r\n dbug: Ocelot.DownstreamRouteFinder.Middleware.DownstreamRouteFinderMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n Downstream templates: /ocelot/posts/{id}\r\n info: Ocelot.RateLimiting.Middleware.RateLimitingMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n EnableEndpointEndpointRateLimiting is not enabled for downstream path: /ocelot/posts/{id}\r\n info: Ocelot.Authentication.Middleware.AuthenticationMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n No authentication needed for path: /ocelot2/posts/5\r\n info: Ocelot.Authorization.Middleware.AuthorizationMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n No authorization needed for upstream path: /ocelot2/posts/{id}\r\n dbug: Ocelot.DownstreamUrlCreator.Middleware.DownstreamUrlCreatorMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n Downstream URL: http://localhost:5555/ocelot/posts/5\r\n info: Ocelot.Requester.Middleware.HttpRequesterMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n 200 OK status code of request URI: http://localhost:5555/ocelot/posts/3\r\n dbug: Ocelot.Requester.Middleware.HttpRequesterMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n Setting HTTP response message...\r\n dbug: Ocelot.Responder.Middleware.ResponderMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n No pipeline errors: setting and returning completed response...\r\n dbug: Ocelot.Errors.Middleware.ExceptionHandlerMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNJ:11111111, PreviousRequestId: -\r\n Ocelot pipeline finished\r\n info: Microsoft.AspNetCore.Hosting.Diagnostics[2]\r\n Request finished HTTP/1.1 GET https://localhost:7778/ocelot2/posts/3 - 200 84 application/json;+charset=utf-8 404.7256ms\r\n info: Microsoft.AspNetCore.Hosting.Diagnostics[16]\r\n Request reached the end of the middleware pipeline without being handled by application code. Request path: GET https://localhost:7778/ocelot2/posts/3, Response status code: 200\r\n info: Ocelot.Requester.Middleware.HttpRequesterMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n 200 OK status code of request URI: http://localhost:5555/ocelot/posts/5\r\n dbug: Ocelot.Requester.Middleware.HttpRequesterMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n Setting HTTP response message...\r\n dbug: Ocelot.Responder.Middleware.ResponderMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n No pipeline errors: setting and returning completed response...\r\n dbug: Ocelot.Errors.Middleware.ExceptionHandlerMiddleware[0]\r\n RequestId: 0HNBA3NEIQUNK:AAAAAAAA, PreviousRequestId: 0HNBA3NEIQUNJ:11111111\r\n Ocelot pipeline finished\r\n info: Microsoft.AspNetCore.Hosting.Diagnostics[2]\r\n Request finished HTTP/1.1 GET https://localhost:7778/ocelot2/posts/5 - 200 128 application/json;+charset=utf-8 347.2607ms\r\n info: Microsoft.AspNetCore.Hosting.Diagnostics[16]\r\n Request reached the end of the middleware pipeline without being handled by application code. Request path: GET https://localhost:7778/ocelot2/posts/5, Response status code: 200\r\n\r\n.. Note by Maintainer:\r\n.. The PreviousRequestId feature requires review and possible redesign, as it may not be implemented or could be broken.\r\n.. Typically, PreviousRequestId is '-' for all requests.\r\n\r\nTechnical Facts\r\n^^^^^^^^^^^^^^^\r\n\r\n* Every log record has these 2 properties:\r\n\r\n * ``RequestId`` represents ID of the current request as plain string, for example ``0HNBA3NEIQUNJ:00000001``.\r\n * ``PreviousRequestId`` represents ID of the previous request.\r\n* As an ``IOcelotLogger`` interface object is injected into the constructors of service classes, the current default Ocelot logger (the ``OcelotLogger`` class) retrieves these two properties from the ``IRequestScopedDataRepository`` service.\r\n\r\n.. _lg-performance:\r\n\r\nPerformance [#f1]_\r\n------------------\r\n\r\nHere is a quick recipe for your production environment to achieve top *performance*.\r\nYou need to ensure the minimum log level is ``Critical`` or ``None``. Nothing more!\r\nHaving top logging *performance* means having fewer log records written by the logging provider. So, the logs should be pretty empty.\r\n\r\nAnyway, during the initial period after a version release to production, we recommend monitoring the system and the current version's app behavior by specifying the minimum log level as ``Error``.\r\nIf the release engineer ensures the stability of the version in production, then the minimum log level can be increased to ``Critical`` or ``None`` to achieve top *performance*.\r\nTechnically, this will disable the logging feature entirely.\r\n\r\nBenchmarks\r\n----------\r\n\r\nWe currently have two types of benchmarks:\r\n\r\n- ``SerilogBenchmarks`` with `Serilog`_ logging to a file. See the ``ConfigureLogging`` method with ``logging.AddSerilog(_logger)``.\r\n- ``MsLoggerBenchmarks`` with MS default logging to the MS Console. See the ``ConfigureLogging`` method with ``logging.AddConsole()``.\r\n\r\nBenchmark results largely depend on the environment and hardware on which they run.\r\nWe are pleased to invite you to run logging benchmarks on your machine by following the instructions below.\r\n\r\n1. Open PowerShell or Command Prompt console\r\n2. Build the Ocelot solution in Release mode: ``dotnet build --configuration Release``\r\n3. Go to the ``test\\Ocelot.Benchmarks\\bin\\Release\\`` folder\r\n4. Choose the .NET version by changing the folder, for example, to ``net9.0``\r\n5. Run benchmarks: ``.\\Ocelot.Benchmarks.exe``\r\n6. Run ``SerilogBenchmarks`` or ``MsLoggerBenchmarks`` by pressing the appropriate number of a benchmark (5 or 6), then press Enter.\r\n7. Wait for 3+ minutes to complete the benchmark and get the final results.\r\n8. Read and analyze your benchmark session results.\r\n\r\n..\r\n Indicators\r\n ^^^^^^^^^^\r\n To be developed...\r\n\r\n\"\"\"\"\r\n\r\n.. [#f1] Logging :ref:`performance ` was improved in pull request `1745`_ and released in version `22.0`_.\r\n These changes were requested as part of issue `1744`_ following the team's discussion in thread `1736`_.\r\n\r\n.. _22.0: https://github.com/ThreeMammals/Ocelot/releases/tag/22.0.0\r\n.. _1745: https://github.com/ThreeMammals/Ocelot/pull/1745\r\n.. _1744: https://github.com/ThreeMammals/Ocelot/issues/1744\r\n.. _1736: https://github.com/ThreeMammals/Ocelot/discussions/1736\r\n\r\n.. _ocelot.json: https://github.com/ThreeMammals/Ocelot/blob/main/samples/Basic/ocelot.json\r\n"
},
{
"path": "docs/features/metadata.rst",
"content": "Metadata\n========\n\n [#f1]_ Feature of: :doc:`../features/configuration`\n\nOcelot provides various features such as routing, authentication, caching, load balancing, and more.\nHowever, some users may encounter situations where Ocelot does not meet their specific needs or they want to customize its behavior.\nIn such cases, Ocelot allows users to add *metadata* to the route configuration.\nThis property can store any arbitrary data that users can access in middlewares or delegating handlers.\n\nSchema\n------\n\nAs you may already know from the :doc:`../features/configuration` chapter and the :ref:`config-route-metadata` section, the route *metadata* schema is quite simple which is JSON dictionary:\n\n.. code-block:: json\n\n \"Metadata\": {\n // \"key\": \"value\",\n }\n\n.. _FileMetadataOptions: https://github.com/ThreeMammals/Ocelot/blob/main/src/Ocelot/Configuration/File/FileMetadataOptions.cs\n\nHowever, **global** metadata configuration consists of both the ``Metadata`` and ``MetadataOptions`` sections.\nYou do not need to set all of these things, but this is everything that is available at the moment.\n\n.. code-block:: json\n\n \"GlobalConfiguration\": {\n \"Metadata\": {\n // \"key\": \"value\",\n },\n \"MetadataOptions\": {\n \"CurrentCulture\": \"en-GB\",\n \"NumberStyle\": \"Any\",\n \"Separators\": [\",\"],\n \"StringSplitOption\": \"None\",\n \"TrimChars\": [\" \"],\n }\n }\n\nThe actual global *metadata* schema with all the properties can be found in the C# `FileMetadataOptions`_ class.\nThis configuration type is parsed to a `MetadataOptions `_ type object.\n\n.. list-table::\n :widths: 20 80\n :header-rows: 1\n\n * - *Option*\n - *Description*\n * - ``CurrentCulture``\n - | Parsed as the ``System.Globalization.CultureInfo`` object (refer to `CultureInfo `_ class)\n | Default value is current culture aka ``CultureInfo.CurrentCulture.Name``\n * - ``NumberStyle``\n - | Parsed as the ``System.Globalization.NumberStyles`` object (refer to `NumberStyles `_ enum)\n | Default value is ``NumberStyles.Any``\n * - ``Separators``\n - Array of ``string``. Default value is ``[\",\"]`` aka comma.\n * - ``StringSplitOption``\n - | Parsed as the ``System.StringSplitOptions`` object (refer to `StringSplitOptions `_ enum)\n | Default value is ``StringSplitOptions.None``\n * - ``TrimChars``\n - Array of ``char``. Default value is ``[\" \"]`` aka whitespace.\n * - ``Metadata``\n - | Parsed as the ``Dictionary`` object containing all global *metadata* which ``string`` values are parsed to a target type value by the :ref:`md-getmetadata-method`.\n\nConfiguration\n-------------\n\nBy using the *metadata*, users can implement their own logic and extend the functionality of Ocelot e.g.\n\n.. code-block:: json\n\n {\n \"Routes\": [\n {\n \"UpstreamHttpMethod\": [ \"GET\" ],\n \"UpstreamPathTemplate\": \"/posts/{postId}\",\n \"DownstreamPathTemplate\": \"/api/posts/{postId}\",\n \"DownstreamHostAndPorts\": [\n { \"Host\": \"localhost\", \"Port\": 80 }\n ],\n \"Metadata\": {\n \"id\": \"FindPost\",\n \"tags\": \"tag1, tag2, area1, area2, func1\",\n \"plugin1.enabled\": \"true\",\n \"plugin1.values\": \"[1, 2, 3, 4, 5]\",\n \"plugin1.param\": \"value2\",\n \"plugin1.param2\": \"123\",\n \"plugin2/param1\": \"overwritten-value\",\n \"plugin2/data\": \"{\\\"name\\\":\\\"John Doe\\\",\\\"age\\\":30,\\\"city\\\":\\\"New York\\\",\\\"is_student\\\":false,\\\"hobbies\\\":[\\\"reading\\\",\\\"hiking\\\",\\\"cooking\\\"]}\"\n }\n }\n ],\n \"GlobalConfiguration\": {\n \"Metadata\": {\n \"instance_name\": \"machine-1\",\n \"plugin2/param1\": \"default-value\"\n },\n \"MetadataOptions\": {\n }\n }\n }\n\nNow, the route *metadata* can be accessed through the ``DownstreamRoute`` object:\n\n.. code-block:: csharp\n :emphasize-lines: 20\n\n using Ocelot.Middleware;\n using Ocelot.Metadata;\n using Ocelot.Logging;\n\n public class MyMiddleware : OcelotMiddleware\n {\n private readonly RequestDelegate _next;\n private readonly IMyService _myService;\n\n public MyMiddleware(RequestDelegate next, IOcelotLoggerFactory loggerFactory, IMyService myService)\n : base(loggerFactory.CreateLogger