Neovim HTTP API

This plugin serves as an example of Java plugin that can be used with neovim-java-plugin-host. It provides Neovim RPC API through HTTP endpoints.

NOTE: This example uses request instead of notification for starting. In this case, notification could have been used as well (and is probably the better solution, since it won't block Neovim). To use notifications instead @NeovimNotificationHandler annotation should be used, and from neovim notify instead of request should be used.

Requirements

• Neovim version 0.7.0+
• neovim-java-plugin-host

Usage

Installation

There are a couple of different ways to install the plugin.

Plugin manager

Using your favourite plugin manager, e.g. Packer.nvim:

use {
  'https://codeberg.org/neovim-java/neovim-http-api-plugin',
  requires = { 'https://codeberg.org/neovim-java/neovim-java-plugin-host' },
  run = { 'mkdir -p rplugin/hosted-jar && mvn package && cp target/*.jar rplugin/hosted-jar/' }
}

For this way to work, require("java_plugin_host").setup() needs to be called and rplugins.load_hosted needs to be true (it is true by default). This is one of the easiest ways to install the plugin and it also supports any custom documentation added in doc/ directory.

Java plugin host

If esensar/neovim-java-plugin-host is already installed and used, this plugin can be added to its configuration (in this case JAR will be downloaded from specified repository):

require("java_plugin_host").setup {
  -- ...
  common_host = {
    -- ...
    hosted_plugins = {
      -- ...
      {
        group_id = "com.ensarsarajcic.neovim.http",
        artifact_id = "neovim-http-api-plugin",
        version = "0.1.0"
      },
      -- ...
    },
    -- ...
  }
  -- ...
}

NOTE: To use custom repositories (GitHub), GitHub Packages Auth needs to be set up.

Starting the API

API can be started with a request, that can be made using java_plugin_host:

require("java_plugin_host").request(
  "com.ensarsarajcic.neovim.http.NeovimHttpApi.start",
  {
    -- Port is required!
    port = 8080,
    -- Optionally define thread count for HTTP handler
    -- thread_count = 4,
    -- Optionally define root URL
    -- root_url = "/",
    -- Optionally define request timeout in millisecond
    -- request_timeout_ms = 10000
  }
)

After this API should be available on http://localhost:8080.

Calling the API

Example calls:

curl "http://localhost:8080?opts.builtin=false"

{"AbortDispatch":{"name":"AbortDispatch","definition":"execute dispatch#abort_command(<bang>0, <q-args>)","script_id":84,"bang":true,"bar":true,"register":false,"keepscript":false,"nargs":"*","complete":null,"complete_arg":null,"count":null,"range":null,"addr":null},"...}

curl "http://localhost:8080/buf/0/name"

"/home/user/.cache/nvim/java_plugin_host/common_host.log"

curl "http://localhost:8080/buf/0/name" -X PUT -d '{"name": "new_name"}'

null

curl "http://localhost:8080/buf/0/name"

"/home/user/.cache/nvim/java_plugin_host/new_name"

API supports GET, PUT, DELETE and POST requests. Command name is generated by adding nvim_ prefix to the request path, as well as additional prefix based on used method (GET = get_, PUT = set_ and DELETE = del_ - special case is nvim_buf_delete). Methods for buffers, windows and tabpages are supported as well, following the format:

http://localhost:8080/{buf,window,tabpage}/{id}/method_name

As seen in the example above - http://localhost:8080/buf/0/name = nvim_get_buf_name for buffer 0

Arguments can be passed in query params (suitable for GET requests) and body too. Body should be in JSON using names as defined by nvim_get_api_info, and query should use the same names, using . to set nested fields - example: http://localhost:8080?opts.builtin=false

License

MIT