Issho (Issho v0.1.0)

Copy Markdown View Source

Collaboration for Phoenix: one engine for people and agents working together live, under every component on a page.

Start an instance in your supervision tree, after your PubSub:

{Issho,
 name: MyApp.Issho,
 pubsub: MyApp.PubSub,
 endpoint: MyAppWeb.Endpoint,
 policy: MyApp.Collaboration,
 store: {MyApp.CollabStore, MyApp.Repo}}

Options

  • :name (required): the instance's name, given to every call.
  • :pubsub (required): your app's Phoenix.PubSub.
  • :policy (required): your Issho.Policy, which authorizes every action and says what each document is.
  • :endpoint or :secret_key_base: to sign join tokens.
  • :store: {module, context}, an Issho.Store for documents.
  • :registry: :global (the default) or a module with name(instance, document_id), for the documents' authorities.
  • :presence: whether this instance starts Issho.Presence (true).
  • :ttl: how long, in milliseconds, an unused document stays open (30 seconds).
  • :awareness_interval: milliseconds between awareness frames (50).
  • :awareness_max_bytes: the largest awareness state of a session, as JSON (64 KB).
  • :max_document_bytes (16 MB), :max_message_bytes (1 MB) and :token_max_age (300 seconds).

See the architecture guide for how the parts fit together.

Summary

Functions

The content of a document's revision, for a form that publishes exactly what a person saw: the epoch and revision the browser posts.

Joins a room as an actor from Elixir (an agent, a job), as a browser would. Gives an Issho.Participant. Options: :can (:write), :on_behalf_of, :claims and :notify (the process that receives the room's events, the caller unless given).

Takes an actor out of a room now, on every node: its sessions end, and it receives nothing more. Your app calls it when it takes access away; the policy refuses the actor from then on.

Starts an instance. See the options above.

Commits operations to a document from your server (a job, an import), through the same checks and authority as everyone else's. author is the key it is recorded under ("server" unless given).

Functions

content(instance, document_id, epoch, revision)

@spec content(atom(), String.t(), String.t(), non_neg_integer()) ::
  {:ok, term()} | {:error, term()}

The content of a document's revision, for a form that publishes exactly what a person saw: the epoch and revision the browser posts.

join_as(instance, actor, room, opts \\ [])

@spec join_as(atom(), Issho.Actor.t(), String.t(), keyword()) ::
  {:ok, pid()} | {:error, term()}

Joins a room as an actor from Elixir (an agent, a job), as a browser would. Gives an Issho.Participant. Options: :can (:write), :on_behalf_of, :claims and :notify (the process that receives the room's events, the caller unless given).

revoke(instance, room, actor_or_key)

@spec revoke(atom(), String.t(), Issho.Actor.t() | String.t()) :: :ok

Takes an actor out of a room now, on every node: its sessions end, and it receives nothing more. Your app calls it when it takes access away; the policy refuses the actor from then on.

start_link(opts)

@spec start_link(keyword()) :: Supervisor.on_start()

Starts an instance. See the options above.

transact(instance, document_id, ops, opts \\ [])

@spec transact(atom(), String.t(), [map()], keyword()) ::
  {:ok, map()} | {:error, term()}

Commits operations to a document from your server (a job, an import), through the same checks and authority as everyone else's. author is the key it is recorded under ("server" unless given).