{"id":18077090,"url":"https://github.com/vydd/farcall","last_synced_at":"2026-01-20T03:01:32.691Z","repository":{"id":91086311,"uuid":"220714215","full_name":"vydd/farcall","owner":"vydd","description":"Farcall is a Common Lisp library that lets you expose functions over HTTP using JSON-RPC 2.0","archived":false,"fork":false,"pushed_at":"2019-11-17T15:57:52.000Z","size":12,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-05T20:11:09.523Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Common Lisp","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vydd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-09T22:56:36.000Z","updated_at":"2024-11-19T16:21:28.000Z","dependencies_parsed_at":null,"dependency_job_id":"cc40daf9-b4af-4960-884f-0d2dad635d4c","html_url":"https://github.com/vydd/farcall","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/vydd/farcall","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vydd%2Ffarcall","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vydd%2Ffarcall/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vydd%2Ffarcall/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vydd%2Ffarcall/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vydd","download_url":"https://codeload.github.com/vydd/farcall/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vydd%2Ffarcall/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28594958,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-20T02:08:49.799Z","status":"ssl_error","status_checked_at":"2026-01-20T02:08:44.148Z","response_time":117,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-31T11:12:10.693Z","updated_at":"2026-01-20T03:01:32.676Z","avatar_url":"https://github.com/vydd.png","language":"Common Lisp","funding_links":[],"categories":[],"sub_categories":[],"readme":"# farcall\n\nFarcall is a Common Lisp library that lets you expose functions over HTTP using [JSON-RPC 2.0](https://www.jsonrpc.org/specification).\n\n## Unstable API\n\nPlease keep in mind that the API should not be considered stable. This is expected to change in early 2020. Also, not every JSON-RPC (really, batching) feature is supported, and for such a tiny specification, this needs to change - in other words, Farcall should support the complete JSON-RPC 2.0 spec. If you need this for a production project, then maybe wait for a bit. If not - let's get started!\n\n## Requirements\n\nCurrently only tested (and known to work) with\n\n| Lisp  | Version                | Platform    |\n| ----- | ---------------------- | ----------- |\n| CCL   | 1.12-dev (v1.12-dev.5) | DarwinX8664 |\n\nIf you decide to test the library, please post a PR with results.\n\n## Installation\n\nFarcall is currently not in [Quicklisp](https://www.quicklisp.org/beta/), so you should clone this repository into your `~/quicklisp/local-projects` folder before proceeding.\n\n## Getting started\n\nWe're going to test the library by starting up a JSON-RPC server in a CL REPL, and then calling a method exposed by that server from a terminal window, using [curl](https://curl.haxx.se).\n\nType the following in the CL REPL:\n\n```lisp\n(ql:quickload :farcall)\n\n(farcall:defrpc add (a b)\n  \"Adds two numbers\"\n  (+ a b))\n\n(farcall:start-server)\n```\n\n_This will first load the library, then define a rpc method using a syntax that's completely similar to `DEFUN`, and will finally start the HTTP server on port 2000._\n\nThen type the following in the terminal:\n\n```sh\ncurl -H \"Content-Type: application/json\" localhost:2000/ -d'{\"jsonrpc\":\"2.0\",\"method\":\"add\",\"params\":[1,2],\"id\":\"1\"}'\n```\n\n_We're setting `application/json` as content type, as it's the only one supported by the specification (and farcall). The data we're sending is formatted as per specification - \"jsonrpc\" and \"id\" fields are mandatory._\n\nIf you've done everything correctly, this is the response you should receive:\n\n```sh\n{\"jsonrpc\":\"2.0\",\"id\":\"1\",\"result\":3}\n```\n\n## Why a new library\n\nIf you're happy with [fukamachi's jsonrpc](https://github.com/fukamachi/jsonrpc), with [cl-json's](https://common-lisp.net/project/cl-json/cl-json.html) included RPC capabilities, or any other library - that's great, and you should probably continue using it, at least until Farcall is stable.\n\nThe reason why I started this project is that:\n\n- Other libraries weren't necessarily well documented. CL-JSON's docs are non existent, and I'm not really sure how easy it'd be to put its capabilities behind Hunchentoot.\n- Reviewed libraries didn't work with HTTP out of the box. Fukamachi's jsonrpc looks great, but it only seems to support raw TCP \u0026 Websockets. I would guess it's possible to add another transport, but it felt like much more work than just writing the library from scratch.\n- OpenRPC or other discovery \u0026 documentation mechanisms don't seem to be available elsewhere. In my opinion, this is an important feature for production APIs.\n- Authorization is important for building most APIs. However, as JSON-RPC is not bound to any single protocol, it naturally does not specify how to do it in context of HTTP. Contemporary APIs are usually built with token based authorization in mind, and this is what Farcall is set to support. (The very method of authenticating the token and authorizing the provided request is left to the user.)\n\n## Reference\n\n### START-SERVER\n\nfunction `(\u0026optional (port 2000))`\n\nStarts the JSON-RPC server on the provided port. Farcall uses Hunchentoot in the backend, and there is no need to run it separately.\n\n### STOP-SERVER\n\nfunction `()`\n\nStops the currently started JSON-RPC server.\n\n### SET-AUTHORIZER\n\nfunction `(authorizer)`\n\nThe authorization function set by this method will be used on all RPC requests. The function needs to be of type (lambda (rpc token)), where RPC is an alist obtained after parsing the JSON RPC payload, and TOKEN is the string obtained from Authorization HTTP header.\n\n### REGISTER-RPC\n\nfunction `(name)`\n\nRegisters an already defined FUNCTION as a rpc method with the given NAME. The disadvantage of using this instead of DEFRPC is twofold: Not only that there's more code to write, but recompiling the function on the fly will not work - REGISTER-RPC will have to be called again. The advantage, of course, is that REGISTER-RPC can be used to retrofit JSON RPC functionality when working with existing, unchangeable code.\n\n### UNREGISTER-RPC\n\nfunction `(name)`\n\nUnregisters a defined RPC. No error is thrown if the NAME isn't registered.\n\n### DEFRPC\n\nmacro `(name arglist \u0026body body)`\n\nDefines a remote procedure call using syntax similar to DEFUN. Should be used instead of REGISTER-RPC for new code.\n\n## Plan\n\n- [ ] Complete JSON-RPC 2.0 support (add batching)\n- [ ] Settle on the API\n- [ ] Publish on Quicklisp\n- [ ] Implement [OpenRPC](https://open-rpc.org)\n- [ ] Implement the client part of the library with remote procedure\n    stubs automatically generated from OpenRPC specification\n\n## Resources\n\n- [JSON-RPC 2.0 Specification](https://www.jsonrpc.org/specification)\n\n## Outro\n\nFor everything else, read the code or ask vydd at #lispgames.\nGo make something pretty!\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvydd%2Ffarcall","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvydd%2Ffarcall","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvydd%2Ffarcall/lists"}