Note on valid Snowflake range #3745
Conversation
|
If a snowflake can't be zero, this note should reflect that |
|
sure it can |
|
0 is valid and won't give you errors |
docs/Reference.md
Outdated
| @@ -108,7 +108,7 @@ All HTTP-layer services and protocols (e.g. HTTP, WebSocket) within the Discord | |||
|
|
|||
| ## Snowflakes | |||
|
|
|||
| Discord utilizes Twitter's [snowflake](https://github.com/twitter/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/etfjson) for more information regarding Gateway encoding. | |||
| Discord utilizes Twitter's [snowflake](https://github.com/twitter/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/etfjson) for more information regarding Gateway encoding. Note that Discords only accepts and returns snowflakes in the range from `0` to `9223372036854775807` (both inclusive), these are all values a 63 bit unsigned integer could hold. | |||
There was a problem hiding this comment.
| Discord utilizes Twitter's [snowflake](https://github.com/twitter/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/etfjson) for more information regarding Gateway encoding. Note that Discords only accepts and returns snowflakes in the range from `0` to `9223372036854775807` (both inclusive), these are all values a 63 bit unsigned integer could hold. | |
| Discord utilizes Twitter's [snowflake](https://github.com/twitter/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size, they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/etfjson) for more information regarding Gateway encoding. Currently the largest snowflake Discord will accept is `9223372036854775807` but this may change in the future. |
There was a problem hiding this comment.
The earlier reference to "uint64" should be removed. Referencing "63 bits" is just confusing and not necessary, and clashes with earlier wording.
There was a problem hiding this comment.
I think it should also include 0 as the smallest.
| Discord utilizes Twitter's [snowflake](https://github.com/twitter/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/etfjson) for more information regarding Gateway encoding. Note that Discords only accepts and returns snowflakes in the range from `0` to `9223372036854775807` (both inclusive), these are all values a 63 bit unsigned integer could hold. | |
| Discord utilizes Twitter's [snowflake](https://github.com/twitter/snowflake/tree/snowflake-2010) format for uniquely identifiable descriptors (IDs). These IDs are guaranteed to be unique across all of Discord, except in some unique scenarios in which child objects share their parent's ID. Because Snowflake IDs are up to 64 bits in size (e.g. a uint64), they are always returned as strings in the HTTP API to prevent integer overflows in some languages. See [Gateway ETF/JSON](#DOCS_TOPICS_GATEWAY/etfjson) for more information regarding Gateway encoding. Currently the smallest snowflake Discord will accept is `0` and the largest is `9223372036854775807` but this may change in the future. |
|
How about removing references to the int size and just document the acceptable range as seen by users? |
|
Thanks for your suggestions! |
|
Any updates on this? |
|
This is technically correct, but doesn't seem necessary to document? It will be about 140 years before we create any snowflakes that reach anything near the upper limit, so it's not like you are ever going to receive a snowflake that large and need to know how to handle it. This seems like an edge that's only really hit if you're trying to do so, not in the "normal course of operations". This can be reopened if there's a real need to document it, but I'm not sure there is. |
|
If you want to provide some max Snowflake constant in your Library that is actually valid, this would be useful. (Used for "get me everything" in pagination.) |
|
Yes, but that max snowflake constant is not a necessary thing to have. Snowflakes are generated by Discord; you aren't going to receive ones that are currently out of bounds. More so, if we decide to change database infra and can then support larger snowflakes, this would be incorrect (though still not really useful). I'm not doubting the validity of the information, but I think it's unnecessary complexity. |
Snowflakes can be generated by users. For example, the after/before/around value in a message pagination does not have to be the exact snowflake of a message; it can be synthesized to represent a date and time. The lower bound may be useful for getting the first message in a channel (or you can use the channel ID) and the upper bound may be useful for getting the last message in a channel (or you can use a synthetic snowflake for the current date and time). And even if you don't generate your own snowflake, shouldn't the fact that there is a bound be sufficient to document it? Why should it matter that it's not practically reachable?
Trivial, but |
|
you can use |
Then it would only take one little change to make it correct again. |
You have to track messages to know the last id, so you would have the last message anyway, if you cached it, and if you even tracked messages. Some users may not do that.
And yes I listed this. That's not the point, though. I'm just giving an example of where users input snowflakes instead of receive them. |
This will change over time, right? So you would need to keep it up to date. |
See #3733