polyphony-chat / chorus Goto Github PK

One should be able to create and delete guilds using this library

Add support for sending and receiving live streams of WebRTC Video and Audio.

It should be possible to modify all aspects of a user profile using this library. This includes, but is not limited to:

• Username
• Discriminator
• Avatar
• Accent Color
• Email
• Pronouns
• Banner
• Bio
• Theme Colors
• Phone
• NSFW
• Disabled
• Deletion
• Testing

The foundation for Gateways has been made! The library now allows you to write code which immediately runs, when a specific event is received via the gateway.

However: Actually communicating with the gateway and receiving those events is where I have failed until now. I just couldn't get it to work the way I would have liked to, and I require help on this one.

From my POV, an ideal implementation would have each Gateway/Websocket running in a seperate thread. Each gateway thread updates the GatewayEvents (defined in src/gateway.rs), which would trigger the observers.

Currently, you can "only" login to the API using the conventional way, which is using login and password. It'd be good if one could login using their token as well.

A feature should be added that allows RateLimits to be written to disk as .json, .yml or another format such as .kdl. This would allow RateLimit information to persist, which would make it harder to run into rate limits by accident.

2-Factor-Authentication functionality should be checked for functionality.

Trying to connect an Instance to discord.com's api yields the following error:

thread 'main' panicked at 'called `Result::unwrap()` on an `Err` value: Error("invalid type: string \"404: Not Found\", expected struct Message", line: 1, column: 28)', .../src/api/policies/instance/limits.rs:328:52

This happens because discord.com doesn't implement /policies/instance/limits (since that's a spacebar only endpoint :P)

It returns {"message": "404: Not Found", "code": 0} when chorus tries to deserialize the response into the Limits Config struct

pub struct Config {
        pub user: User,
        pub guild: Guild,
        pub message: Message,
        pub channel: Channel,
        pub rate: Rate,
        pub absoluteRate: AbsoluteRate,
}

invalid type: string \"404: Not Found\", expected struct Message comes from the message field being the same in the real response and the 404 response

Sugestion how to fix this

Check if the GET limits requests returns a 404, if it does, fallback to a default (discord.com's default ratelimits)

Add, delete, modify and get server emojis.

There should be a test for login in. Related: There is an existing auth test for account registration, but the common test bundle setup functionality performs a registration beforehand anyways, so that test can probably be removed.

Schemas.rs is getting pretty big. It should be split up into schemas.rs (which contains actual schemas like the LoginSchema or RegisterSchema) and types.rs, which will contain things like Message, Guild, Channel, etc.

The UserMeta (or User) struct should have a method, which gets all guild objects which the user is a member of.

The two integration tests currently fail. This needs to be fixed ASAP

The current implementation of the Gateway always requests all intents for a Gateway connection. This should be configurable.

Helix uses tokio features ["rt", "macros", "rt-multi-thread", "full"]. full enables all features – as chorus is a library, it should only enable those it needs.

Rust generally uses Option::Some/Result::Ok to indicate success and Option::None/Result::Err to indicate failure. Both implement the Try trait, allowing easier error management with ?.

For functions that don't return a value on success Chorus does the opposite and returns Some on failure and None on success. This can be better represented via Result<(), ChorusLibError>. It's also convention to define a helpful type alias: type Result<T> = std::result::Result<T, ChorusLibError>;.

Message::send (as well as UserMeta::send_message) take a files parameter for attachments, however the MessageSendSchema already has an attachments field. Currently both must agree with each other. Removing the files argument would fix this.

Additionally, the send takes the message by mutable reference (to set attachment placeholder ids), but doesn't document what it mutates. It should either take it directly, document it, or take it by shared reference and not actually change the placeholder ids (which have to be unique, but don't have to be continuous).

Currently a new https client is created for every request, however the Client docs state:

/// The `Client` holds a connection pool internally, so it is advised that
/// you create one and **reuse** it.
///
/// You do **not** have to wrap the `Client` in an [`Rc`] or [`Arc`] to **reuse** it,
/// because it already uses an [`Arc`] internally.

There are a lot of print statements in src/gateway.rs that shouldn't be there. If logging is desired, use log to give control to users.

• Create (Group) DMs
• Leave (Group) DMs
• Add/remove people from (Group) DMs
• Join Guild
• Leave Guild

It should check both username & password length

→ shouldn't return a result

Ensure support for Threads, Forums (and their sub-channels), announcement channels, and anything else that gets added to this list in the mean time.

Tasks:

• Create channel
• Get channel
• Delete channel
• Modify channel

Add all reactions routes.

• DELETE /channels/{channel_id}/messages/{message_id}/reactions/
• GET /channels/{channel_id}/messages/{message_id}/reactions/{emoji}
• DELETE /channels/{channel_id}/messages/{message_id}/reactions/{emoji}
• DELETE /channels/{channel_id}/messages/{message_id}/reactions/{emoji}/{user_id}
• PUT /channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me
• DELETE/channels/{channel.id}/messages/{message.id}/reactions/{emoji}/@me

The current unit and integration tests are really nice, but they should be restructured in my opinion. A lot of integration tests overlap, which leads to a lot of code duplication in the testing area. This should be avoided, which is why I think a restructuring is needed.

the rate limiter should return more custom errors instead of just generic ones. I have already started with this in #44, but this still needs some work.

Implement message sending via the API

Inside UserMeta, the instance is stored in an Rc. However, calling login_account/register_account on an Instance creates a new copy of the instance. Is this intentional?

If not, this could be fixed by changing the functions to take an Rc<Instance>.

The build is currently failing. This is, because the server likely does not have the correct/up-to-date schemas. Should be fixed.

There are a lot of cases where chorus panics instead of handling errors, chief among them in deserialize_response when a request fails. This should not happen, encountering errors is expected.

Additionally, ReceivedErrorCodeError contains the http status code of the failed request, but discards the response body (at least the spacebar server returns useful information about why the request failed), making debugging harder.

Less important: The error handling code can be more succinctly expressed using idioms such as the try operator (?) or .map_err and friends. Also, since this crate is called chorus, not choruslib, the main error type should be called ChorusError, not ChorusLibError; and because it already contains "error", its variants don't need "error" as a suffix.

Cover joining and leaving message threads and actions concerning Forum channels (pinning, unpinning, tag creation, assigning, etc.)

the Guild struct should have a method which can get a guild object by the guild id.

Similar to libraries like discord.js, Chorus should create structs, which update themselves.

If we, for example, get a User object with let user = User::get(<info>);, and this user updates, for example, their Display name, with the current implementation, the user we just defined would already have out-of-date information.

We already receive events such as this Display name update over the Gateway, as soon as they happen. There should be a way to automatically incorporate this info we already receive into the actual object we create, so that we always have up-to-date information, without needing to re-query the API (which is quite expensive).

#50

Currently only a few of the events the server can dispatch are implemented, further ones need to be added to Events and transcribed from the docs into rust types. (A lot of these require more complex types like Guild, Sticker etc)

Making an issue to track the progress of implementing every gateway event

• Application Command Permissions Update
• Auto Mod
  • Rule
    • Create
    • Update
    • Delete
  • Action Execution
• Channel
  • Create
  • Update
  • Unread Update
  • Delete
  • Pins Update
• Call (RE)
  • Create
  • Update
  • Delete
• Thread
  • Create
  • Update
  • Delete
  • List Sync
  • Member Update
  • Members Update
• Guild
  • Create
  • Update
  • Delete
  • Audit Log entry create
  • Ban Add
  • Ban Remove
  • Emojis Update
  • Stickers Update
  • Integrations Update
  • Member
    • Add
    • Remove
    • Update
    • Chunk
  • Role
    • Create
    • Update
    • Delete
  • Scheduled Event
    • Create
    • Update
    • Delete
    • User Add
    • User Remove
  • Passive Update V1 (RE)
• Integration
  • Create
  • Update
  • Delete
• Interaction Create
• Invite
  • Create
  • Delete
• Message
  • Create
  • Update
  • Delete
  • Delete Bulk
  • Reaction
    • Add
    • Remove
    • Remove All
    • Remove Emoji
  • ACK
• Presence Update
• Relationship
  • Add
  • Remove
• Stage Instance
  • Create
  • Update
  • Delete
• Sessions Replace
• Typing Start
• User Update
• Voice State Update
• Voice Server Update
• Webhooks Update

Also, I am working on this already :)

The following checklist should be completed for a release build of Chorus. The list is sourced from here: https://rust-lang.github.io/api-guidelines/checklist.html

These so called API Guidelines should not be forced upon the project, but be just that: a set of guidelines to look up to and apply whereever it makes sense.

• Naming (crate aligns with Rust naming conventions)
  • Casing conforms to RFC 430 (C-CASE)
  • Ad-hoc conversions follow as_, to_, into_ conventions (C-CONV)
  • Getter names follow Rust convention (C-GETTER)
  • Methods on collections that produce iterators follow iter, iter_mut, into_iter (C-ITER)
  • Iterator type names match the methods that produce them (C-ITER-TY)
  • Feature names are free of placeholder words (C-FEATURE)
  • Names use a consistent word order (C-WORD-ORDER)
• Interoperability (crate interacts nicely with other library functionality)
  • Types eagerly implement common traits (C-COMMON-TRAITS)
    • Copy, Clone, Eq, PartialEq, Ord, PartialOrd, Hash, Debug,
      Display, Default
  • Conversions use the standard traits From, AsRef, AsMut (C-CONV-TRAITS)
  • Collections implement FromIterator and Extend (C-COLLECT)
  • Data structures implement Serde's Serialize, Deserialize (C-SERDE)
  • Types are Send and Sync where possible (C-SEND-SYNC)
  • Error types are meaningful and well-behaved (C-GOOD-ERR)
  • Binary number types provide Hex, Octal, Binary formatting (C-NUM-FMT)
  • Generic reader/writer functions take R: Read and W: Write by value (C-RW-VALUE)
• Macros (crate presents well-behaved macros)
  • Input syntax is evocative of the output (C-EVOCATIVE)
  • Macros compose well with attributes (C-MACRO-ATTR)
  • Item macros work anywhere that items are allowed (C-ANYWHERE)
  • Item macros support visibility specifiers (C-MACRO-VIS)
  • Type fragments are flexible (C-MACRO-TY)
• Documentation (crate is abundantly documented)
  • Crate level docs are thorough and include examples (C-CRATE-DOC)
  • All items have a rustdoc example (C-EXAMPLE)
  • Examples use ?, not try!, not unwrap (C-QUESTION-MARK)
  • Function docs include error, panic, and safety considerations (C-FAILURE)
  • Prose contains hyperlinks to relevant things (C-LINK)
  • Cargo.toml includes all common metadata (C-METADATA)
    • authors, description, license, homepage, documentation, repository,
      keywords, categories
  • Release notes document all significant changes (C-RELNOTES)
  • Rustdoc does not show unhelpful implementation details (C-HIDDEN)
• Predictability (crate enables legible code that acts how it looks)
  • Smart pointers do not add inherent methods (C-SMART-PTR)
  • Conversions live on the most specific type involved (C-CONV-SPECIFIC)
  • Functions with a clear receiver are methods (C-METHOD)
  • Functions do not take out-parameters (C-NO-OUT)
  • Operator overloads are unsurprising (C-OVERLOAD)
  • Only smart pointers implement Deref and DerefMut (C-DEREF)
  • Constructors are static, inherent methods (C-CTOR)
• Flexibility (crate supports diverse real-world use cases)
  • Functions expose intermediate results to avoid duplicate work (C-INTERMEDIATE)
  • Caller decides where to copy and place data (C-CALLER-CONTROL)
  • Functions minimize assumptions about parameters by using generics (C-GENERIC)
  • Traits are object-safe if they may be useful as a trait object (C-OBJECT)
• Type safety (crate leverages the type system effectively)
  • Newtypes provide static distinctions (C-NEWTYPE)
  • Arguments convey meaning through types, not bool or Option (C-CUSTOM-TYPE)
  • Types for a set of flags are bitflags, not enums (C-BITFLAG)
  • Builders enable construction of complex values (C-BUILDER)
• Dependability (crate is unlikely to do the wrong thing)
  • Functions validate their arguments (C-VALIDATE)
  • Destructors never fail (C-DTOR-FAIL)
  • Destructors that may block have alternatives (C-DTOR-BLOCK)
• Debuggability (crate is conducive to easy debugging)
  • All public types implement Debug (C-DEBUG)
  • Debug representation is never empty (C-DEBUG-NONEMPTY)
• Future proofing (crate is free to improve without breaking users' code)
  • Sealed traits protect against downstream implementations (C-SEALED)
  • Structs have private fields (C-STRUCT-PRIVATE)
  • Newtypes encapsulate implementation details (C-NEWTYPE-HIDE)
  • Data structures do not duplicate derived trait bounds (C-STRUCT-BOUNDS)
• Necessities (to whom they matter, they really matter)
  • Public dependencies of a stable crate are stable (C-STABLE)
  • Crate and its dependencies have a permissive license (C-PERMISSIVE)

It should be possible to modify all aspects of a user profile using this library. This includes, but is not limited to:

• Username
• Discriminator
• Avatar
• Accent Color
• Email
• Pronouns
• Banner
• Bio
• Theme Colors
• Phone
• NSFW
• Disabled
• Deletion

Permission overrides for channels and categories, which can be set for roles and single users alike.

Cover all API routes which concern themselves with deleting messages.

I just realized, that the Rate limiter counts your rate limits per-instance, and not per-user.
Of course, some limits like Global and IP are shared, but all the other limits should be per-user instead. This shouldn't be too hard, mostly some restructuring.

Reactions::get() returns a generic success/failure, when it should return a list of users instead.

#42 does not implement every user setting there is. This should be done here.

• Modify Guild
• Get Guild Preview
• Modify Guild MFA Level
• Get Guild Members
• Search Guild Members
• Get Guild Member
• Add Guild Member
• Modify Guild Member
• Modify Current Guild Member
• Modify Guild Member Profile
• Add Guild Member Role
• Remove Guild Member Role
• Remove Guild Member
• Get Guild Bans
• Get Guild Ban
• Create Guild Ban
• Delete Guild Ban
• Get Guild Roles
• Get Guild Role Members
• Add Guild Role Members
• Modify Guild Role Positions
• Get Guild Prune
• Prune Guild
• Get Guild Widget Settings
• Modify Guild Widget
• Get Guild Widget
• Get Guild Widget Image
• Get Guild Vanity Invite
• Modify Guild Vanity Invite

Cover Group DM creation, deletion and member management.

There needs to be a working implementation of a gateway, which connects to the Gateway of an instance and can send and receive messages. It would be great if the Gateway would emit 'events' on things like message received, message edited message deleted etc. These events could then, for example, be used by the client to update its UI when the event happens.

Implement the route described here: https://discord-userdoccers.vercel.app/resources/channel#get-private-channels

All types have been moved to a separate repository for re-usability. Chorus will be refactored to use these types instead of the current, duplicate types.

While types and names convey the most important information, often doc comments are helpful or necessary. The current ones still have some issues though:

• Many use ///, but some use /**
• There has been some drift between comments and reality, such as in Channel::modify
• There's a lot of tautology: Often they just restate the types and names of the arguments & return value. For example:

    /// Edits the permission overwrites for a channel.
    ///
    /// # Arguments
    ///
    /// * `user` - A mutable reference to a [`UserMeta`] instance.
    /// * `channel_id` - A string slice representing the ID of the channel.
    /// * `overwrite` - A [`PermissionOverwrite`] instance representing the new permission overwrites.
    ///
    /// # Returns
    ///
    /// This function returns a result that is either [`Ok(())`] if the request is successful, or an [`Err(ChorusLibError)`].
    pub async fn edit_permissions(
        user: &mut UserMeta,
        channel_id: Snowflake,
        overwrite: PermissionOverwrite,
    ) -> ChorusResult<()> {…

  All of the information in the doc comment is a restatement of the types and names present. For that reason, function documentation in rust usually doesn't include an extra arguments section and instead refers to the arguments as needed when describing the function's behavior (example).
• Some functions/structs could do with more descriptions about semantics.
• Ideally there would be doctests (executable examples) as well as a higher-level overview and more examples.

Provide Register and Login functionality using the API Wrapper.

Fetching the general instance info for discord.com fails, because discord.com doesn't implement the endpoint /policies/instanceand just returns a 404.

This makes new Instances unable to connect to discord.com, since Instance::new returns ChorusError::CantGetInformation if fetching the instance info fails.

Cover all friend- and blocking-related routes.

One should be able to modify, create and delete Roles and their permissions. This extends to modifying role and user permissions on channels and channel categories.