server blocks: availability and documentation

[j-q-arnold]

This is issue concerns multiple aspects of 'server blocks'. (I probably should break this into multiple issues, but perhaps they can be addressed in a single release.)

• Current reslang compiler does not accept the syntax.

  reslang /Users/jaarno/code/api-specs/specs-draft/segment-delivery \
      --stdout >/Users/jaarno/code/api-specs/specs-draft/segment-delivery/segment-delivery.openapi.yaml
  Reslang error:  Problem parsing file /Users/jaarno/code/api-specs/specs-draft/segment-delivery/servers.reslang: Expected "/*", "//", "asset-resource", "async", "configuration-resource", "enum", "event", "future", "namespace", "request-resource", "resource", "section", "singleton", "structure", "subresource", "sync", "union", or [ \t\r\n] but "s" found., location: 8, 1

  This error from a simple server block that mirrors the example documentation. After further investigation, this was caused by a description string before the servers block. The language accepts a comment but rejects a description. If similarity with other blocks (resources, etc.), I recommend allowing a description string (even if that string has no effect on the generated yaml).

• The servers name of the block implies the block can define multiple servers. Please document how this is done.
• This is not really a language issue, but need to give the operational values for the server attribute. This could be in an implementation section specific to LiveRamp, but it should exist somewhere.
• How does a reslang namespace contribute (or not) to the server attribute? Should give full details about the value supplied in the block and the value used in the output OpenAPI/event server spec. This includes the port handling.
• Explain how the command line attributes (prefix, etc.) affect the behavior. How do the command line values interact with values from the source code? Is it possible to define prefix in the reslang source? As a recommendation, anything that one can specify on the command line should have an analog in the reslang language.
• The documentation gives environment = PROD, implying other types of servers might be available. Need to document those environments and their values. Also should document the LiveRamp conventions for each environment.
• Similar issue for the protocol attribute.
• The /events section appears to take a "string comment" that describes the server. One imagines this can be done for the /REST section's servers, but the example is unclear.
• A comment on the design. The name environment seems rather generic. The "environment" is a general mechanism for passing multiple name-value pairs around the ecosystem. Picking environment as the specific name of one name-value pair seems likely to cause confusion. Using --env as the command-line flag adds ambiguity. I would expect the current environment value to be one of the names passed through the --vars mechanism. Suggestion: deployment seems like a reasonable name for this value, for example, --vars deployment=STAGING

[njaczko]

I communicated a bit with @j-q-arnold over slack, but the problem here was that servers blocks cannot have string descriptions (yet they can have comments). Individual servers, on the other hand, can have descriptions.

Example (Allowed):

// These are my servers
servers {
    /REST
        "This is the test server"
        server = "http://test-api.liveramp.com:{port:8080}"
    ...

Example (Not Allowed):

"These are my servers"
servers {
    /REST
        "This is the test server"
        server = "http://test-api.liveramp.com:{port:8080}"
    ...

I'm going to remove the bug label, but leave this open with the documentation and enhancement labels - Jim raised a bunch of good points.