Crate codemp

Code MultiPlexer - cooperative development

codemp is an async client library to create cooperation tools for any text editor.

It is built as a batteries-included client library managing an authenticated user, multiple workspaces each containing any number of buffers.

The Client is completely managed by the library itself, making its use simple across async contexts and FFI boundaries. All memory is managed by the library itself, which gives out always atomic reference-counted pointers to internally mutable objects. Asynchronous actions are abstracted away by the api::Controller, providing an unopinionated approach with both callback-based and blocking-based APIs.

The library also provides ready-to-use bindings in a growing number of other programming languages, to support a potentially infinite number of editors.

Overview

The main entrypoint is Client::connect, which establishes an authenticated connection with a supported remote server and returns a Client handle to interact with it.

let client = codemp::Client::connect(
  codemp::api::Config::new(
    "mail@example.net",
    "dont-use-this-password"
  )
)
  .await
  .expect("failed to connect!");

A Client can acquire a Workspace handle by joining an existing one it can access with Client::attach_workspace or create a new one with Client::create_workspace.

client.create_workspace("my-workspace").await.expect("failed to create workspace!");
let workspace = client.attach_workspace("my-workspace").await.expect("failed to attach!");

A Workspace handle can be used to acquire a cursor::Controller to track remote api::Cursors and one or more buffer::Controller to send and receive api::TextChanges.

use codemp::api::controller::{AsyncSender, AsyncReceiver}; // needed to access trait methods
let cursor = workspace.cursor();
let event = cursor.recv().await.expect("disconnected while waiting for event!");
println!("user {} moved on buffer {}", event.user, event.sel.buffer);

Internally, buffer::Controllers store the buffer state as a diamond_types CRDT, guaranteeing eventual consistency. Each api::TextChange is translated in a network counterpart that is guaranteed to converge.

let buffer = workspace.attach_buffer("/some/file.txt").await.expect("failed to attach");
buffer.content(); // force-sync
if let Some(mut update) = buffer.try_recv().await.unwrap() {
  println!(
    "content: {}, span: {}-{}",
    update.change.content, update.change.start_idx, update.change.end_idx
  );
  buffer.ack(update.version);
} // if None, no changes are currently available

FFI

As mentioned, we provide bindings in various programming languages. To obtain them, you can compile with the appropriate feature flag. Currently, the following are supported:

• lua
• javascript
• java (requires additional build steps to be usable)
• python

For some of these, ready-to-use packages are available in various registries:

• npm (javascript)
• PyPI (python)
• Maven Central (java)
• LuaRocks (lua)

Re-exports

pub use workspace::Workspace;

pub use client::Client;

Modules

api

core structs and traits

buffer

buffer related types and controller

client

client handle, containing all of the above

cursor

cursor related types and controller

errors

crate error types

ext

common utils used in this library and re-exposed

ffi

language-specific ffi “glue”

prelude

all-in-one imports : use codemp::prelude::*;

workspace

workspace handle and operations

Functions

version

Get the current version of the client