A JavaScript development environment for Emacs https://indium.readthedocs.io
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.
 
 
 
 
 

346 lines
12 KiB

  1. ;;; indium-client.el --- Indium process client -*- lexical-binding: t; -*-
  2. ;; Copyright (C) 2018 Nicolas Petton
  3. ;; Author: Nicolas Petton <nicolas@petton.fr>
  4. ;; This program is free software; you can redistribute it and/or modify
  5. ;; it under the terms of the GNU General Public License as published by
  6. ;; the Free Software Foundation, either version 3 of the License, or
  7. ;; (at your option) any later version.
  8. ;; This program is distributed in the hope that it will be useful,
  9. ;; but WITHOUT ANY WARRANTY; without even the implied warranty of
  10. ;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  11. ;; GNU General Public License for more details.
  12. ;; You should have received a copy of the GNU General Public License
  13. ;; along with this program. If not, see <https://www.gnu.org/licenses/>.
  14. ;;; Commentary:
  15. ;; The Indium process client starts and communicates with an "indium" process.
  16. ;;
  17. ;; Make sure to install the indium process with:
  18. ;; npm install -g indium
  19. ;;; Code:
  20. (require 'json)
  21. (require 'map)
  22. (require 'subr-x)
  23. (require 'json-process-client)
  24. (require 'indium-structs)
  25. (defcustom indium-client-closed-hook nil
  26. "Hook called after a client is closed."
  27. :group 'indium-client
  28. :type 'hook)
  29. (defcustom indium-client-connected-hook nil
  30. "Hook called after a client is connected."
  31. :group 'indium-client
  32. :type 'hook)
  33. (defcustom indium-client-log-hook nil
  34. "Hook called when a client receives a log event."
  35. :group 'indium-client
  36. :type 'hook)
  37. (defcustom indium-client-breakpoint-resolved-hook nil
  38. "Hook called upon breakpoint resolution."
  39. :group 'indium-client
  40. :type 'hook)
  41. (defcustom indium-client-debugger-resumed-hook nil
  42. "Hook called when the debugger is resumed."
  43. :group 'indium-client
  44. :type 'hook)
  45. (defcustom indium-client-debugger-paused-hook nil
  46. "Hook called when the debugger is paused."
  47. :group 'indium-client
  48. :type 'hook)
  49. (defvar indium-client-debug nil
  50. "When non-nil, log server output to *indium-client-log*.")
  51. (defun indium-client-find-executable ()
  52. "Return the indium executable file."
  53. (if-let ((lisp-filename (or load-file-name (buffer-file-name))))
  54. (let ((executable (thread-last
  55. (file-name-directory lisp-filename)
  56. (expand-file-name "server")
  57. (expand-file-name "bin")
  58. (expand-file-name "indium"))))
  59. (if (file-executable-p executable)
  60. executable
  61. (indium-client-default-executable)))
  62. (indium-client-default-executable)))
  63. (defun indium-client-default-executable ()
  64. "Return the default process executable."
  65. "indium")
  66. (defcustom indium-client-executable (indium-client-find-executable)
  67. "Process executable."
  68. :group 'indium-client
  69. :type 'file)
  70. (defvar indium-client--application nil
  71. "The client connection as returned by `json-process-client-start'.")
  72. (defvar indium-client--process-port 13840
  73. "The port on which the server should listen.")
  74. (defun indium-client-start (callback)
  75. "Start an Indium process and store it as the client process.
  76. Evaluate CALLBACK once the server is started."
  77. (when (indium-client-process-live-p)
  78. (user-error "An indium process is already running"))
  79. (let ((executable (executable-find indium-client-executable)))
  80. (unless executable
  81. (user-error "Cannot find the indium executable. Please run \"npm install -g indium\""))
  82. (setq indium-client--application
  83. (json-process-client-start-with-id
  84. :name "indium"
  85. :executable executable
  86. :port indium-client--process-port
  87. :started-regexp "server listening"
  88. :tcp-started-callback callback
  89. :exec-callback #'indium-client--handle-message
  90. :debug "*indium-debug-log*"
  91. :args (list (number-to-string indium-client--process-port))))))
  92. (defun indium-client-stop ()
  93. "Stop the indium process."
  94. (json-process-client-stop indium-client--application)
  95. (setq indium-client--application nil)
  96. (run-hooks 'indium-client-closed-hook))
  97. (defun indium-client-send (message &optional callback)
  98. "Send MESSAGE to the Indium process.
  99. When CALLBACK is non-nil, evaluate it with the process response."
  100. (json-process-client-send indium-client--application message callback))
  101. (defun indium-client-list-configurations (directory &optional callback)
  102. "Request the list of configurations found in DIRECTORY.
  103. Evaluate CALLBACK with the result."
  104. (indium-client-send `((type . "configurations")
  105. (payload . ((action . "list")
  106. (directory . ,directory))))
  107. callback))
  108. (defun indium-client-connect (directory name)
  109. "Connect to a runtime.
  110. DIRECTORY is the path of the directory where the project file can be found.
  111. NAME is the name of the configuration to use for connecting.
  112. Once the client is connected, run the hook `indium-client-connected-hook'."
  113. (indium-client-send `((type . "connection")
  114. (payload . ((action . "connect")
  115. (directory . ,directory)
  116. (name . ,name))))
  117. (lambda (&rest _)
  118. (run-hooks 'indium-client-connected-hook))))
  119. (defun indium-client-evaluate (expression &optional frame callback)
  120. "Evaluate EXPRESSION in the context of FRAME.
  121. When non-nil, evaluate CALLBACK with the result."
  122. (indium-client-send
  123. `((type . "runtime")
  124. (payload . ((action . "evaluate")
  125. (expression . ,expression)
  126. (frameId . ,(when frame (indium-frame-id frame))))))
  127. (lambda (obj)
  128. (when callback
  129. (funcall callback (indium-remote-object-from-alist obj))))))
  130. (defun indium-client-get-completion (expression &optional frame callback)
  131. "Request the list of completion for EXPRESSION in the context of FRAME.
  132. When non-nil, evaluate CALLBACK with the result."
  133. (indium-client-send `((type . "runtime")
  134. (payload . ((action . "getCompletion")
  135. (expression . ,expression)
  136. (frameId . ,(when frame (indium-frame-id frame))))))
  137. callback))
  138. (defun indium-client-get-properties (id &optional callback)
  139. "Request the list of properties for the remote object with ID.
  140. When non-nil, evaluate CALLBACK with the result."
  141. (indium-client-send
  142. `((type . "runtime")
  143. (payload . ((action . "getProperties")
  144. (id . ,id))))
  145. (lambda (properties)
  146. (when callback
  147. (funcall callback (seq-map #'indium-property-from-alist
  148. properties))))))
  149. (defun indium-client-activate-breakpoints ()
  150. "Activate all breakpoints."
  151. (indium-client-send `((type . "runtime")
  152. (payload . ((action . "activateBreakpoints"))))))
  153. (defun indium-client-deactivate-breakpoints ()
  154. "Deactivate all breakpoints."
  155. (indium-client-send `((type . "runtime")
  156. (payload . ((action . "deactivateBreakpoints"))))))
  157. (defun indium-client-add-breakpoint (breakpoint)
  158. "Request the addition of BREAKPOINT."
  159. (let* ((id (indium-breakpoint-id breakpoint))
  160. (location (indium-breakpoint-location breakpoint))
  161. (file (indium-location-file location))
  162. (line (indium-location-line location))
  163. (column (indium-location-column location)))
  164. (indium-client-send `((type . "runtime")
  165. (payload . ((action . "addBreakpoint")
  166. (id . ,id)
  167. (file . ,(indium-client--convert-path file))
  168. (line . ,line)
  169. (column . ,column)))))))
  170. (defun indium-client-remove-breakpoint (breakpoint)
  171. "Request the removal of BREAKPOINT."
  172. (let ((id (indium-breakpoint-id breakpoint)))
  173. (indium-client-send `((type . "runtime")
  174. (payload . ((action . "removeBreakpoint")
  175. (id . ,id)))))))
  176. (defun indium-client-resume ()
  177. "Resume the runtime execution."
  178. (indium-client-send `((type . "runtime")
  179. (payload . ((action . "resume"))))))
  180. (defun indium-client-step-into ()
  181. "Request a step into."
  182. (indium-client-send `((type . "runtime")
  183. (payload . ((action . "stepInto"))))))
  184. (defun indium-client-step-out ()
  185. "Request a step out."
  186. (indium-client-send `((type . "runtime")
  187. (payload . ((action . "stepOut"))))))
  188. (defun indium-client-step-over ()
  189. "Request a step over."
  190. (indium-client-send `((type . "runtime")
  191. (payload . ((action . "stepOver"))))))
  192. (defun indium-client-continue-to-location (location)
  193. "Request the runtime to resume until LOCATION is reached."
  194. (indium-client-send
  195. `((type . "runtime")
  196. (payload . ((action . "continueToLocation")
  197. (location . ((file . ,(indium-client--convert-path
  198. (indium-location-file location)))
  199. (line . ,(indium-location-line location))
  200. (column . ,(indium-location-column location)))))))))
  201. (defun indium-client-get-frame-source (frame &optional callback)
  202. "Request the source of FRAME.
  203. When CALLBACK is non-nil, evaluate it with the source"
  204. (indium-client-send
  205. `((type . "runtime")
  206. (payload . ((action . "getSource")
  207. (id . ,(indium-frame-script-id frame)))))
  208. callback))
  209. (defun indium-client-get-sourcemap-sources (&optional callback)
  210. "Request the all the sourcemap source paths.
  211. When CALLBACK is non-nil, evaluate it with the list of sources."
  212. (indium-client-send
  213. `((type . "runtime")
  214. (payload . ((action . "getSourcemapSources"))))
  215. callback))
  216. (defun indium-client-get-script-sources (&optional callback)
  217. "Request the all the script source paths.
  218. When CALLBACK is non-nil, evaluate it with the list of sources."
  219. (indium-client-send
  220. `((type . "runtime")
  221. (payload . ((action . "getScriptSources"))))
  222. callback))
  223. (defun indium-client-process-live-p ()
  224. "Return non-nil if the indium process is running."
  225. (json-process-client-process-live-p indium-client--application))
  226. (defun indium-client--handle-message (data callback)
  227. "Handle a server message with DATA.
  228. If DATA is a successful response to a previously-sent message,
  229. evaluate CALLBACK with the payload."
  230. (let-alist data
  231. (pcase .type
  232. ("error" (indium-client--handle-error .payload))
  233. ("success" (indium-client--handle-response .payload callback))
  234. ("notification" (indium-client--handle-notification .payload))
  235. ("log" (indium-client--handle-log .payload)))))
  236. (defun indium-client--handle-error (payload)
  237. "Handle an error from the server.
  238. PAYLOAD is an alist containing the details of the error."
  239. (let-alist payload
  240. (message "Indium server error: %s" .error)))
  241. (defun indium-client--handle-response (payload callback)
  242. "Handle a response to a client request.
  243. PAYLOAD contains the data of the response.
  244. If CALLBACK is non-nil, evaluate it with the PAYLOAD."
  245. (when callback
  246. (unwind-protect
  247. (funcall callback payload))))
  248. (defun indium-client--handle-log (payload)
  249. "Handle a log event from the server.
  250. PAYLOAD is an alist with the details of the log event.
  251. If has the following keys:
  252. type type of message
  253. url url of the message origin
  254. line line number in the resource that generated this message
  255. result object to be logged."
  256. (map-put payload 'result (indium-remote-object-from-alist
  257. (map-elt payload 'result)))
  258. (run-hook-with-args 'indium-client-log-hook
  259. payload))
  260. (defun indium-client--handle-notification (payload)
  261. "Handle a notification event sent from the server.
  262. PAYLOAD is an alist with the details of the notification."
  263. (let-alist payload
  264. (pcase .type
  265. ("breakpointResolved"
  266. (progn
  267. (run-hook-with-args 'indium-client-breakpoint-resolved-hook .id .line)))
  268. ("paused"
  269. (run-hook-with-args 'indium-client-debugger-paused-hook
  270. (seq-map #'indium-frame-from-alist .frames)
  271. .reason
  272. .description))
  273. ("resumed"
  274. (run-hooks 'indium-client-debugger-resumed-hook))
  275. (_ (message "Indium notification %s" payload)))))
  276. (defun indium-client--convert-path (path)
  277. "Convert PATH to a system path that the server component understands."
  278. (when (eq system-type 'windows-nt)
  279. (setq path (replace-regexp-in-string "/" "\\" path nil t))
  280. (setq path (replace-regexp-in-string "^\\([a-z]\\):" #'capitalize path)))
  281. path)
  282. (provide 'indium-client)
  283. ;;; indium-client.el ends here