Notable changes to ruma

• Add initial version of the /createRoom endpoint.

  This preliminary version of room creation takes no parameters and just returns the ID of the newly created room.

Notable changes to ruma-events

• Remove event traits.

  Event, RoomEvent, and StateEvent are no longer traits. Instead, each event type just has the necessary fields. This will be revised to use RFC #1546 if it is accepted.

• Make all event type fields public.

• Derive Debug, Deserialize, and Serialize for all types.

• Add types for all m.room.message and all its subtypes.

Matrix at large

Next week, some of the Matrix core team will be visiting San Francisco (from London) for Decentralized Web Summit. Some bay area Matrix developers are planning to get together to meet in person and chat about Matrix. If you live in the bay area and would like to join us, please come chat in #sv:matrix.org and help pick a time and place!

From the editor

In addition to the changes to ruma enumerated below, there was some great progress on the future user-facing documentation for Ruma. My partner, who works as a technical writer, helped me brainstorm and outline what information people would need to understand Matrix and Ruma, how to get a copy of Ruma, configure it, and deploy it. As always, needing to explain something simply to someone else forces you to understand it at a deeper level yourself. I think the project is going to benefit greatly from some longer form explanations of of the what, why, and how of Matrix that aren't targeted at technical people.

Notable changes to ruma

• Usage of the try! macro has been converted to using the new question mark syntax.

  Use of this unstable feature is one nice benefit of Ruma targeting nightly Rust.

• Added support for authentication with an access token.

  This is the mechanism which almost all endpoints that require authentication use.

• Added the /logout endpoint which revokes all access tokens associated with the user.

• Added the /account/password endpoint which lets the user change their account password.

  This endpoint uses both user-interactive authentication and access token authentication. The reasons for this were not clear to me, so I discussed it in #matrix-dev:matrix.org, and was able to distill the results of the discussion into SPEC-407.

• Moved and renamed various free functions into static methods on the types that they manipulate.

• Filled in some missing API documentation and added the #![deny(missing_docs)] attribute to make sure docs are added as new items are.

Matrix at large

This week there was a story posted to Hacker News about how Google failed to recognize the value of Gchat, which resulted in the usual discussion of chat services that exist today. I left a comment encouraging people to look at Matrix, and it generated a good amount of discussion and publicity for the project. Be sure to read the thread!

From the editor

Lots of progress this week! As expected, I finished the /login endpoint, so I can now move on to the real stuff: rooms and the event stream. This week also saw two nice milestones: Ruma's first pull request was merged, and I successfully registered an account with a locally running Ruma server via a locally running Vector client. (The latter also uncovered an undocumented API that Vector was attempting to use which I've brought up with the Matrix team.)

Before taking the plunge into rooms and events, I'm taking some time to think and plan about how to structure the data, and have been talking with the Matrix team about how Synapse handles things, lessons learned, and the trade offs of different approaches. A few months ago, Erik Johnston of the core team wrote up some notes on data storage in Matrix which has been very useful in this planning stage. It's a great read if you're interested in some of the tricky issues in Matrix development.

There was also a little discussion on how difficult it is to represent certain JSON structures in the API as Rust types. There are several data structures in the API that are effectively enums, but can't be automatically deserialized by Serde because of two things: how Serde currently handles enums and the fact that variants can only be determined by examining the values of some of their fields. The latter currently requires manual implementation of deserialization, which gets cumbersome very quickly. The way I'm probably going to address this is to deserialize these types of data structures to an intermediate type so simple deserialization from JSON can be separated from higher level detection and validation logic. To that end, I built the validations library, which provides both an interface for validating a type, and types for representing validation errors.

Notable changes to ruma

• Finished a simple working version of the /login API endpoint.
• Added CORS support to all endpoints.
• Reexported the Iron handlers for API endpoints from their parent module to make imports a little less verbose.
• Renamed the FinalConfig type to Config, and the previously named Config to the now private RawConfig type.
• Revised the README with full documentation of the configuration file's format along with some other improvements.

New contributors

• Johannes Oertel

From the editor

There were only a few commits this week, but there was very good progress on the test suite and some internals. After trying several ways to work around libtest's lack of global setup and teardown hooks, and some issues with the way each test was running an Iron server in a thread keeping database connections open forever, I decided to move the setup and teardown outside of the Rust code itself. I explored the code of libtest and libsyntax and got to understand how it works and some of its limitations. I might be creating an RFC for Rust soon to give the programmer independent control of the test collector and the test runner, which are currently bound together under the --test flag (AKA --cfg test.)

Now the PostgreSQL Docker container is started and stopped, and database migraitons are run from a shell script which wraps cargo test. The Iron app was similarly decoupled from the Iron server, so that integration testing can be done with iron-test without ever starting an actual server. Finally, I made some more progress on Matrix's user-interactive authentication system and got part of the /login endpoint completed. I expect it to be fully functional by next week.

Notable changes to ruma

• Cleaned up test suite

  Complicated setup and teardown extracted from the Rust code. Test cases moved into the modules they test, rather than within a tests-directory-style module in src/test.

• Introduced iron-test to facilitate testing

  The test suite now has a single support type, test::Test, which does per-test setup and teardown via RAII and provides succinct helper methods for making requests and testing the responses.

• Initial version of the /login API added.

  The logic is all there, but there are some places where deserialization of the types used in the request body must be manually implemented because they differ in structure from what Serde can do with its custom derive attributes.

Matrix at large

The sections about authentication, registration, and login in the spec have seen some very nice improvements recently, but there are still some parts that are misleading or unclear. I'm in the process of getting a few things clarified that will help finally nail down how these various APIs should work.

From the editor

I'm back from my vacation to Montreal and Quebec City (which are lovely and you should visit) and working on Ruma again! Although development this past week was hindered a bit by another round of breaking changes to the Rust compiler's libsyntax crate, which affects Ruma's use of serde and diesel, there have been a few changes to Ruma and some movement on the Matrix specification.

For anyone interested in following This Week in Ruma regularly, it is now available via an Atom feed.

Notable changes to ruma

• New CLI subcommand, ruma secret

  This new subcommand generates and prints a secure random value suitable as the macaroon_secret_key in the Ruma config file. This value is used as the secret key for creating user access tokens using Macaroons.

• Interactive authentication removed from /register

  At least for now, user registration will not require any sort of external credential verification. This area of the spec is currently less stable, so implementing it will wait until it makes more sense.

• Simplified structure for crates, modules, and tests

  The integration tests have been moved into the src directory so that it's not necessary to split ruma into a binary and a library just so the integration tests can link to the library. This makes Cargo.toml and various cargo commands simpler.

• Swagger data source

  By default, ruma now serves a JSON structure at /ruma/swagger.json that can be loaded by Swagger UI to display the full Matrix client-server specification that will eventually be implemented by Ruma.

Matrix at large

There has been a bunch of activity on the spec recently. It appears that the Matrix team is preparing for a stable 1.0 release of the client-server API spec. A branch I worked on for the spec landing page of the specification was also merged. Those changes improve the organization of the information to make several things clearer to first-time readers.