Very simple HTTP wrapper around Neovim RPC API - demonstration of neovim-java-plugin-host
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Ensar Sarajcic 4eadd0ecb4 Migrate CI to codeberg 5 months ago
.mvn/wrapper Add maven wrapper 6 months ago
.woodpecker Migrate CI to codeberg 5 months ago
src/main/java/com/ensarsarajcic/neovim/http Add README and release workflows 6 months ago
.gitignore Initial commit 6 months ago
LICENSE Add README and release workflows 6 months ago
README.md Migrate CI to codeberg 5 months ago
mvnw Add maven wrapper 6 months ago
mvnw.cmd Add maven wrapper 6 months ago
pom.xml Migrate CI to codeberg 5 months ago

README.md

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

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