selector detailed explanation

Edit
Update time: 2021-03-06

Features

  • selector and rule are the key point of soul gateway, you can manage any request with it.

  • this chapter is mainly focus on the concepts of selector and rule and how to use it.

overview

  • one plugin has many selector and a selector has many rules, selector is the first filter of request, and the rule is the final filter.

  • pls consider this, it would be perfect when the plugin executes the request until it reached the config value.

  • selector and rule are designed to execute only when the request meet the specific condition.

  • pls refer to the previous data structure database design.

selector

  • selector detailed explanation:

    • name:create your selector with a distinguish name.
    • type:custom flow is customized request, full flow is full request. customized request will be handled by the conditions as below, while full request won’t.
    • match method: you can combine these conditions with ‘and’ , ‘or’ operators.
    • condition:
      • uri: filter request with uri method and support fuzzy matching (/**).
      • header: filter request with request header.
      • query: filter request with query string.
      • ip: filter request with your real ip.
      • host: filter request with your real host.
      • post: not recommend to use.
      • condition match:
        • match : fuzzy string matching,recommend to combine with uri,support restful matching.(/test/**).
        • = : if the values are the same, then they match.
        • regEx : regex matching,match characters in regex expression.
        • like : string fuzzy matching.
    • open option:only work with enabled.
    • print log:it will print the matching log with the open option enabled.
    • execution order:the smaller will have high priorty to execute among multi-selectors.
  • the above picture means: when the prefix of the request uri is /test and the value of module inheader istest, it will redirect to this service 1.1.1.1:8080.

  • selector advice : combine uri conditon and match prefix(/contextPath)as the first request filter.

rule

  • when the request was passed by the seletor, then it will be processed by the rule, the final filter.

  • rule is the final confirmation about how to execute request logically.

  • rule detailed explanation:

    • name:create your rule with a distinguish name.
    • match method: you can combine these conditions with ‘and’ , ‘or’ operators.
    • condition:
      • uri: filter request with uri method and support fuzzy matching (/**).
      • header: filter request with request header.
      • query: filter request with query string.
      • ip: filter request with your real ip.
      • host: filter request with your real host.
      • post: not recommend to use.
      • condition match:
        • match : fuzzy string matching,recommend to combine with uri,support restful matching.(/test/**)
        • = : if the values are the same, then they match.
        • regEx : regex matching,match characters in regex expression.
        • like : string fuzzy matching.
    • open option:only work with enabled.
    • print log:it will print the matching log with the open option enabled.
    • execution order:the smaller will have high priorty to execute among multi-rules.
    • handle: different plugin has different execution method, pls refer to the specific one.
  • above picture means: when the request uri equals to /http/order/save, it will execute based on this rule,load strategy is random.

  • combine selector means :when the request uri is /http/order/save, it will be redicted to 1.1.1.1:8080 by random method.

  • rule advice: combine uri condition with match the real uri path condition as the final filter.

condition detailed explanation

  • uri matching (recommend)

    • uri matching is based on your request uri, the frontend won’t change anything before accessing the gateway.

    • the match filter method is the same withspringmvc fuzzy matching.

    • in selector,we recommend to match with the prefix of uri, and use the specific path in rule.

    • when changing the match method, the matching field name can be filled randomly, but make sure the match value must be correct.

  • header matching

    • header matches with your http request header value.
  • query matching

    • it matches the query string in your uri, such as: /test?a=1&&b=2.

    • so you can add a new condition, choose query method: a = 1.

  • ip matching

    • it matches the ip of the http caller.

    • especially in the waf plugin, if you find some ip is unsafe, you can add a match condition with this ip, then it can’t access any more.

    • if you use nginx proxy before soul, you can get the right ip with refering to parsing-ip-and-host

  • host matching

    • it matches the host of http caller.

    • especially in waf plugin, if you find some host is unsafe, you can add a match condition with this host, then it can’t access any more.

    • if you use nginx proxy before soul, you can get the right ip with refering to parsing-ip-and-host

  • post matching

    • not recommend to use.