Implement a Service Bus Connection String Parser

[jsquire]

Summary

Service Bus allows for authorization using a shared key and shared access signature that is supported using a service-specific shared access key credential. It is common for the shared key or shared access signature to be passed with the service endpoint and entity path as part of a connection string. To align with best practices, we would like to guide library users to down the path of using credentials for authorization within production applications. In order to assist with transforming a connection string for use with credential-based client creation, a parsing utility is desirable.

Scope of Work

• Design and implementation of a means for parsing a Service Bus connection string into its components. These should include:

  • FullyQualifiedNamespace
  • Endpoint
  • EntityPath
  • SharedAccessSignature
  • SharedAccessKeyName
  • SharedAccessKey
    
    

• The parser should adhere to the current validation rules for connection string correctness. For example:

  • Only one form of authorization should be allowed (shared key or shared access signature)
  • The Endpoint must be present
  • The EntityPath is optional
  • All tokens which are present must have an associated value
    
    

• The host name of the Endpoint should be reflected as the FullyQualifiedNamespace.

• Unknown tokens in the connection string are rejected or ignored; they are not reflected in the set of parsed tokens.

• The parsed values should be treated as read-only, if idiomatic to the language.

• The proposed surface area of the parser, as well as any associated types that change the public API surface should be reviewed with the language architect, and approval obtained. Full board review is not necessary.

Success Criteria

• The design of a parser detailed by the scope has been completed and approved by the language architect.

• The parser has been implemented according to the design and is exposed as part of the public API of the library.

• The tests necessary for its validation have been created or adjusted and pass reliably.

• The existing test suite continues to produce deterministic results and pass reliably.

References

• Follow-Up: Client Creation Discussion
• Client Creation Discussion

[ramya-rao-a]

@jsquire Can you share the error message you are using so that we use similar verbiage for the below error scenarios:

• Missing endpoint in connection string
• Both SAS and key present in connection string
• No SAS or Key name, but key present in connection string

[jsquire]

@jsquire Can you share the error message you are using so that we use similar verbiage for the below error scenarios:

We're using the same messages that we currently do during parsing.

• Missing endpoint in connection string
• No SAS or Key name, but key present in connection string

The connection string used for an Event Hub client must specify the Event Hubs namespace host, and either a Shared Access Key (both the name and value) or Shared Access Signature to be valid. The path to an Event Hub must be included in the connection string or specified separately.

• Both SAS and key present in connection string

The authorization for a connection string may specify a shared key or pre-computed shared access signature, but not both. Please verify that your connection string does not have the SharedAccessSignature token if you are passing the SharedKeyName and SharedKey.

Event Hub name specified in the connection string and also the constructor

The path to an Event Hub may be specified as part of the connection string or as a separate value, but not both. Please verify that your connection string does not have the EntityPath token if you are passing an explicit Event Hub name.

The endpoint token exists, but it's not a well-formed URL (or we couldn't override the scheme due to the weird formatting)

The endpoint address could not be parsed; it was either malformed or not using the sb:// scheme.

[ramya-rao-a]

I am thinking of going with the below for JS:

• Connection string should have the Endpoint.
• Connection string cannot have both SharedAccessSignature and SharedAccessKey details.
• Connection string with SharedAccessKey should have SharedAccessKeyName as well.
• Connection string with SharedAccessKeyName should have SharedAccessKey as well.

[ramya-rao-a]

Done with #11949