google-app-engineapp-engine-flexible

Semantics of dispatch.yaml

I'm looking at various pages about dispatch.yaml, most of which contain similar information and examples:

https://cloud.google.com/appengine/docs/flexible/nodejs/how-requests-are-routed#routing_with_a_dispatch_file https://cloud.google.com/appengine/docs/python/config/dispatchref https://cloud.google.com/appengine/docs/go/config/dispatchref etc.

I happen to be using node.js on GAE Flexible Environment, but I think it would be the same for every language and environment.

The problem is that these pages don't really specify how dispatch.yaml works. In particular:

  1. Are rules applied in the order given? I'm assuming that the first matching rule is the one used, but nothing seems to say so.
  2. Do leading glob (wildcard) characters match only the domain name, or could they match the first part of the URL's path? If the rule is */hello, would that match myapp.appspot.com/path/hello? I'm guessing not, based on some vague hints in the docs, but it isn't very clear.
  3. If no rule in dispatch.yaml matches the URL, will it be routed to the default service? I would think it would have to, but again, these pages don't say.
  4. Do URLs get rewritten based on the rules before they're sent to the service? If the rule is */path/* and the URL is https://myapp.appspot.com/path/hello, will the service see it as /path/hello or as /hello? I'm guessing the former.

I'm doing some trial and error now, so I may be able to answer my own question soon. I'm also submitting this to Google through their documentation feedback system.

Solution

  • Things I know so far:

    1. Yes, rules are tried in order. So for example, if you want one URL to go to a specific service, and all other URLs to go to another service, you should specify the specific one first:
    dispatch:
  - url: "*/specific"
    module: specific

  - url: "*/*"
    module: general

    If you put those rules in the opposite order, module specific will never be used, because the URL /specific will be caught by the wildcard rule.

    1. Unknown

    2. Yes. You can test this by making a request not matching any dispatch.yaml rule and watching the default's service logs.

    3. No rewriting. If the rule is */path/* and the actual URL is https://myapp.appspot.com/path/hello, your service should still handle /path/hello, not /hello.