mozilla/janus-plugin-rs

Rust crate for wrapping the Janus C plugin API, so you can build Janus plugins in Rust.

janus-plugin-rs

Library for creating Rust plugins and event handlers for Janus. Still moderately unstable.

[dependencies]
janus-plugin = "0.13.0"

Compatibility

Currently compatible with Janus versions >= 0.10.9; Janus makes breaking changes relatively frequently to the plugin API, so expect this library to require updating and recompilation for plugins to continue to work with new Janus versions.

Building

Requires the Jansson native library (Ubuntu: libjansson-dev) to link against; tested as compatible with versions >= 2.5.

$ cargo build --all

Testing

$ cargo test --all

Basic usage

Janus expects to dynamically link plugins as libraries and then call a create function on them to return a janus_plugin struct, which has a variety of function pointers that Janus will call when plugin-related events in the core happen.

These bindings provide a build_plugin! macro that accepts as arguments plugin metadata and a set of (extern C) Rust functions, producing a Rust version of the janus_plugin struct, and an export_plugin! macro that defines the create function to return that struct. So to implement a plugin, you should write some handler functions, and then use those macros like so:

use std::os::raw::c_char;

// helper macro for generating C-style strings from Rust string literals at compile time
macro_rules! c_str {
    ($lit:expr) => {
        unsafe {
            std::ffi::CStr::from_ptr(concat!($lit, "\0").as_ptr() as *const c_char)
        }
    }
}

extern "C" fn init(callbacks: *mut PluginCallbacks, config_path: *const c_char) -> c_int {
    janus_info!("Plugin loaded!");
    0
}

extern "C" fn destroy() {
    janus_info!("Plugin destroyed!");
}

// ...other handlers omitted: see
// https://janus.conf.meetecho.com/docs/plugin_8h.html#details

const PLUGIN: Plugin = build_plugin!(
    LibraryMetadata {
        // The Janus plugin API version. The version compiled into the plugin
        // must be identical to the version in the Janus which loads the plugin.
        api_version: 15,
        // Incrementing plugin version number for your own use.
        version: 1,
        // Human-readable metadata which Janus can query.
        name: c_str!("My plugin name"),
        package: c_str!("My plugin package name"),
        version_str: c_str!(env!("CARGO_PKG_VERSION")),
        description: c_str!(env!("CARGO_PKG_DESCRIPTION")),
        author: c_str!(env!("CARGO_PKG_AUTHORS")),
    },
    init,
    destroy,
    // ...other handlers omitted: see
    // https://janus.conf.meetecho.com/docs/plugin_8h.html#details
);

export_plugin!(&PLUGIN);

Examples

Here are some projects which are using these bindings:

• https://github.com/mozilla/janus-plugin-sfu
• https://github.com/ivanovaleksey/janus-echotest-rs
• https://github.com/netology-group/janus-conference/

janus-plugin-rs's Issues

JANUS_PLUGIN_API_VERSION without refcount feature

Hello @mquander,

I have faced with a little problem with my EchoTest plugin.
Today I rebuild a Docker image and apparently Janus Gateway source code was updated.
As it turns out JANUS_PLUGIN_API_VERSION was bumped from 8 to 9.

Currently I use 0.7.1 version without refcount feature.
In that case JANUS_PLUGIN_API_VERSION = 8.

I got the following error.

[ERR] [janus.c:main:3912] The 'janus.plugin.echotest' plugin was compiled against an older version of the API (8 < 9), skipping it: update it to enable it again

It is not a problem really since the plugin is demo-only and could be easily build using refcount.
I would like to ask you for advice.
Janus Gateway already defined new 9 API version on master not refcount branch.
And the crate expects that 9 could be only on refcount branch.
Should we change it somehow?

CODE_OF_CONDUCT.md file missing

As of January 1 2019, Mozilla requires that all GitHub projects include this CODE_OF_CONDUCT.md file in the project root. The file has two parts:

1. Required Text - All text under the headings Community Participation Guidelines and How to Report, are required, and should not be altered.
2. Optional Text - The Project Specific Etiquette heading provides a space to speak more specifically about ways people can work effectively and inclusively together. Some examples of those can be found on the Firefox Debugger project, and Common Voice. (The optional part is commented out in the raw template file, and will not be visible until you modify and uncomment that part.)

If you have any questions about this file, or Code of Conduct policies and procedures, please see Mozilla-GitHub-Standards or email [email protected].

(Message COC001)

Soundness issue

Sdp::get_mlines and Sdp::deref dereference the user accessible raw pointer Sdp::ptr and pass it to ffi. SessionWrapper::drop dereferences the user accessible raw pointer SessionWrapper::handle.

This is unsound because a user could safely modify those pointer fields and call on of the methods to cause UB.

Travis CI free usage ends Dec 3; mozilla repos should switch to other CI platforms

We're opening this issue because your project has used Travis CI within the last 6 months. If you have already migrated off it, you can close and ignore this issue.

Travis CI is ending free builds on public repositories. travis-ci.com stopped providingthem in early November, and travis-ci.org will stop after December 31, 2020. To avoid disruptions to your workflows, you must migrate to another CI service.

For production use cases, we recommend switching to CircleCI. This service is already widely used within Mozilla. There is a guide to migrating from Travis CI to CircleCI available here.

For non production use cases, we recommend either CircleCI or Github Actions. There is a guide to migrating from Travis CI to Github Actions available here. Github Actions usage within Mozilla is new, and you will have to work with our github administrators to enable specific actions following this process.

If you have any questions, reach out in #github-admin:mozilla.org on matrix.

Higher-level and more safe API

Hi!

Thanks for helpful library!

Are there any plans to implement more higher-level and safe API?
I have kind of proposal but there are many details it lacks.

1. Plugin trait which defines all the callbacks user should implement
   in two ways: low-level (raw) and high-level. The latter operates on more idiomatic
   Rust entities such as references, Rust structs, strings and numeric values
   while the former leaves all the raw details in place allowing to skip possibly
   slow conversions and defaults to calling 'high-level' methods.
2. One more macros which defines extern "C" functions along with static
   declaration of user object which implements Plugin trait. Functions just deal
   with acquisition of static object and call methods on it.
3. init callback can be more elaborate - it can initialize callbacks to Janus Core
   which crate then will use to provide more high-level API for them (just regular public functions, no need to fetch
   global PluginCallbacks object and call functions there).

It's unclear to me how to wrap all Janus objects from outside in more convenient
and safe way.

What do you think of this?