Standardize star channel usage

[adamcfraser]

There continues to be confusion between the usage of the * channel from the document perspective (as an "all docs" channel), and use of the * channel as a wildcard (e.g. when filtering channels in a _changes request).

Need to refactor the usage to avoid this confusion and standardize the handling from an end user's perspective.

[leonid-s-usov]

Reviewing the source I have found that a public document has a ! name. Now I'm confused, how does this align with your "all_docs" channel notation?
https://github.com/couchbase/sync_gateway/blob/master/src/github.com/couchbase/sync_gateway/channels/set.go#L29

[adamcfraser]

• Public channel - ! - docs added to this channel are visible to any user (i.e. all users are automatically granted access to the ! channel)
• All docs channel - * - all docs are added to this channel (i.e. any user that has access to the * channel can view all documents)

[leonid-s-usov]

Thanks, that clarifies.
This should be in the docs somewhere. I would rephrase a bit, saying

• all users are automatically granted access to ! channel
• all docs are automatically assigned to * channel

[adamcfraser]

Improving/standardizing the docs is part of the motivation behind this ticket.

[adamcfraser]

The use case from #787 should be included when considering how we refactor.

[ajres]

There are three separate special channel concepts, two of which use the same symbol.

Internally in Sync Gateway they are referenced by the following constants:

const DocumentStarChannel = "!"
const UserStarChannel = "*"
const AllChannelWildcard = "*" 

Below are the external touch points for each of these concepts:

! (all users are automatically granted access to this channel)

• All users are automatically granted access to the ! channel at runtime.
• The ! channel can be used as a public distribution channel.
• The ! channel is passed in the channel("!") method in a sync function to tag a document as being visible from the ! channel.

* (all docs are automatically assigned to this channel)

• All documents are automatically assigned to the * channel.
• The * channel can be used to give 'admin' users visibility to all docs, without needing access to the Sync Gateway ADMIN REST API.
• The * channel is passed in the sync function method access(user, "*") to give a user visibility to all documents.
• The * channel is passed to the sync function method requireAccess("*") to determine if the user has access to the * channel.
• The * channel can be passed in the "admin_channels":["*"] parameter when creating a user. This will administratively give the user access to the * channel.

* ('all accessible channels' selector)

• The * selector is passed in the 'channels' parameter of a _changes request to indicate that changes should be returned from all of the channels accessible to the calling user.
• If the channels parameter is not passed it defaults to the * selector

[adamcfraser]

Thanks for documenting the usage. I don't think we need any code changes here - just better documentation of the expected usage.

In an ideal world we might deprecate the use of * as wildcard in the _changes channels parameter, since omitting the channels parameter has the same effect, but I don't think we can do that now without breaking applications that are currently using it.

At this point I think this just needs to get turned into documentation - assigning to @zgramana for confirmation.

[zgramana]

Agree. For now, I'm marking this as a 2.0 issue, but expect after we think through this it might break into new issue[s].