{"id":23092603,"url":"https://github.com/kjdev/nginx-jq","last_synced_at":"2025-04-03T18:28:33.726Z","repository":{"id":41370726,"uuid":"481799679","full_name":"kjdev/nginx-jq","owner":"kjdev","description":null,"archived":false,"fork":false,"pushed_at":"2022-10-17T23:56:49.000Z","size":28,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-02-09T06:44:12.894Z","etag":null,"topics":["jq","nginx"],"latest_commit_sha":null,"homepage":"","language":"C","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/kjdev.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}},"created_at":"2022-04-15T01:29:09.000Z","updated_at":"2022-04-29T04:18:30.000Z","dependencies_parsed_at":"2023-01-19T22:49:31.163Z","dependency_job_id":null,"html_url":"https://github.com/kjdev/nginx-jq","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fnginx-jq","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fnginx-jq/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fnginx-jq/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kjdev%2Fnginx-jq/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kjdev","download_url":"https://codeload.github.com/kjdev/nginx-jq/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247055496,"owners_count":20876199,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["jq","nginx"],"created_at":"2024-12-16T21:35:12.645Z","updated_at":"2025-04-03T18:28:33.699Z","avatar_url":"https://github.com/kjdev.png","language":"C","readme":"ngix-jq\n=======\n\nThis nginx module responds by filtering the json file with jq.\n\nDependency\n----------\n\n[jq](http://stedolan.github.io/jq) header and library.\n\n- jv.h\n- jq.so\n\n\nInstallation\n------------\n\n### Build install\n\n``` sh\n$ : \"clone repository\"\n$ git clone https://github.com/kjdev/nginx-jq\n$ cd nginx-jq\n$ : \"get nginx source\"\n$ NGINX_VERSION=1.x.x # specify nginx version\n$ wget http://nginx.org/download/nginx-${NGINX_VERSION}.tar.gz\n$ tar -zxf nginx-${NGINX_VERSION}.tar.gz\n$ cd nginx-${NGINX_VERSION}\n$ : \"build module\"\n$ ./configure --add-dynamic-module=../\n$ make \u0026\u0026 make install\n```\n\nEdit `nginx.conf` and load the required modules.\n\n```\nload_module modules/ngx_http_jq_module.so;\n```\n\n### Docker\n\n``` sh\n$ docker build -t nginx-jq .\n$ : \"app.conf: Create nginx configuration\"\n$ : \"app.json: Create json file\"\n$ docker run -p 80:80 -v $PWD/app.conf:/etc/nginx/http.d/default.conf -v $PWD/app.json:/opt/app.json nginx-jq\n```\n\n\u003e Github package: ghcr.io/kjdev/nginx-jq\n\n\nConfiguration Directives\n------------------------\n\n```\nSyntax: jq_json_file file;\nDefault: -\nContext: server\n```\n\nSpecify the json file to be filtered for jq.\n\n```\nSyntax: jq_library_path path;\nDefault: -\nContext: server\n```\n\nSpecify the library path to be filtered for jq.\n\n```\nSyntax: jq_filter filter;\nDefault: jq_filter .;\nContext: location\n```\n\nSpecify a filter for jq.\n\n```\nSyntax: jq_raw on | off;\nDefault: jq_raw off;\nContext: location\n```\n\nDetermines whether to output raw strings instead of JSON text.\n\n```\nSyntax: jq_sort on | off;\nDefault: jq_sort off;\nContext: location\n```\n\nDetermines whether the object's keys are sorted or not.\n\n```\nSyntax: jq_set_variable field value [final];\nDefault: -\nContext: location\n```\n\nSet the variable `filed` with the value `value`.\n\n\nExample\n-------\n\nJson file: `test.json`\n\n``` json\n{\n  \"test\": \"TEST\",\n  \"items\": [\n    { \"id\": 1, \"data\": \"data-1\" },\n    { \"id\": 2, \"data\": \"data-2\" },\n    { \"id\": 3, \"data\": \"data-3\" }\n  ]\n}\n```\n\nNginx configuration file: `test.conf`\n\n```\nserver {\n  listen 80 default_server;\n  server_name _;\n  default_type application/json;\n\n  jq_json_file /opt/test.json;\n\n  location = / {\n    jq_filter '.';\n  }\n\n  location = /test {\n    jq_filter '.test';\n  }\n\n  location = /test/raw {\n    default_type text/plain;\n    jq_raw on;\n    jq_filter '.test';\n  }\n\n  location = /array {\n    default_type text/plain;\n    jq_filter '.[]';\n  }\n\n  location = /array/raw {\n    default_type text/plain;\n    jq_raw on;\n    jq_filter '.[]';\n  }\n\n  location = /items {\n    default_type text/plain;\n    jq_filter '.items[]';\n  }\n\n  location = /items/sort {\n    default_type text/plain;\n    jq_sort on;\n    jq_filter '.items[]';\n  }\n\n  # id query parameter required\n  location = /items/id {\n    jq_filter '.items[] | select(.id == ($id | tonumber))';\n  }\n\n  # id variable is a string\n  location = /items/id/str {\n    jq_filter '.items[] | select(.id == $id)';\n  }\n\n  # id variable defaults to 2\n  # id variable is overwritten with query parameter\n  location = /items/id/def-2 {\n    jq_set_variable id 2;\n    jq_filter '.items[] | select(.id == ($id | tonumber))';\n  }\n\n  # id variable is not overwritten with query parameter\n  location = /items/id/2 {\n    jq_set_variable id 2 final;\n    jq_filter '.items[] | select(.id == ($id | tonumber))';\n  }\n\n  # error when running jq\n  location = /error/execute {\n    jq_filter '.[] | .error';\n  }\n\n  # incorrect jq filter\n  location = /error/compile {\n    jq_filter 'invalid';\n  }\n}\n```\n\nStart the server using docker.\n\n``` sh\n$ docker run --rm -p 80:80 -v $PWD/test.json:/opt/test.json -v $PWD/test.conf:/etc/nginx/http.d/default.conf ghcr.io/kjdev/nginx-jq\n```\n\nExecution result.\n\n``` sh\n$ alias run=\"curl -w '%{content_type} %{http_code}\\n'\"\n$ run localhost\n{\"test\":\"TEST\",\"items\":[{\"id\":1,\"data\":\"data-1\"},{\"id\":2,\"data\":\"data-2\"},{\"id\":3,\"data\":\"data-3\"}]}\napplication/json 200\n$ run localhost/test\n\"TEST\"\napplication/json 200\n$ run localhost/test/raw\nTEST\ntext/plain 200\n$ run localhost/array\n\"TEST\"\n[{\"id\":1,\"data\":\"data-1\"},{\"id\":2,\"data\":\"data-2\"},{\"id\":3,\"data\":\"data-3\"}]\ntext/plain 200\n$ run localhost/array/raw\nTEST\n[{\"id\":1,\"data\":\"data-1\"},{\"id\":2,\"data\":\"data-2\"},{\"id\":3,\"data\":\"data-3\"}]\ntext/plain 200\n$ run localhost/items\n{\"id\":1,\"data\":\"data-1\"}\n{\"id\":2,\"data\":\"data-2\"}\n{\"id\":3,\"data\":\"data-3\"}\ntext/plain 200\n$ run localhost/items/sort\n{\"data\":\"data-1\",\"id\":1}\n{\"data\":\"data-2\",\"id\":2}\n{\"data\":\"data-3\",\"id\":3}\ntext/plain 200\n$ run localhost/items/id\n\u003chtml\u003e\u003chead\u003e\u003ctitle\u003e400 Bad Request\u003c/title\u003e..\ntext/html 400\n$ run localhost/items/id -G -d id=1\n{\"id\":1,\"data\":\"data-1\"}\napplication/json 200\n$ run localhost/items/id -G -d id=2\n{\"id\":1,\"data\":\"data-1\"}\napplication/json 200\n$ run localhost/items/id -G -d id=10\n\u003chtml\u003e\u003chead\u003e\u003ctitle\u003e404 Not Found\u003c/title\u003e..\ntext/html 404\n$ run localhost/items/id/str -G -d id=1\n\u003chtml\u003e\u003chead\u003e\u003ctitle\u003e404 Not Found\u003c/title\u003e..\ntext/html 404\n$ run localhost/items/id/def-2\n{\"id\":2,\"data\":\"data-2\"}\napplication/json 200\n$ run localhost/items/id/def-2 -G -d id=3\n{\"id\":3,\"data\":\"data-3\"}\napplication/json 200\n$ run localhost/items/id/2\n{\"id\":2,\"data\":\"data-2\"}\napplication/json 200\n$ run localhost/items/id/2 -G -d id=1\n{\"id\":2,\"data\":\"data-2\"}\napplication/json 200\n$ run localhost/error/execute\nCannot index string with string \"error\"\ntext/plain 406\n$ run localhost/error/compile\n\u003chtml\u003e\u003chead\u003e\u003ctitle\u003e400 Bad Request\u003c/title\u003e..\ntext/html 400\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkjdev%2Fnginx-jq","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkjdev%2Fnginx-jq","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkjdev%2Fnginx-jq/lists"}