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.

131 lines
4.3 KiB

1 year ago
1 year ago
1 year ago
1 year ago
  1. * GN proxy & access control
  2. ** Dependencies and starting the proxy
  3. The only dependencies are "redis-rkt" and "threading", and they
  4. can be installed using raco:
  5. #+begin_src bash
  6. git clone git@github.com:chfi/gn-proxy.git
  7. cd gn-proxy
  8. raco pkg install
  9. #+end_src
  10. The REST server can then be started by running server/rest.rkt, while
  11. providing the SQL username and password as environment variables:
  12. #+begin_src bash
  13. env SQL_USER=username SQL_PASSWORD=password racket server/rest.rkt
  14. #+end_src
  15. By default it listens on port 8080 and listens on 127.0.0.1, however
  16. the port can be changed with the PORT environment variable.
  17. The Redis and MariaDB connections are handled in ~server/db.rkt~, and
  18. can be configured by editing ~connect-redis~ and ~connect-sql~. See the
  19. documentation for the respective packages for more information, if needed:
  20. - Redis: https://docs.racket-lang.org/redis@redis-doc/client.html
  21. - SQL: https://docs.racket-lang.org/db/connect.html
  22. ** Resources
  23. Resources can be created using the constructors in Racket (e.g.
  24. ~new-geno-resource~), and then serialized into stringified JSON using
  25. ~serialize-resource~, which can then be inserted into Redis.
  26. This is an example of the JSON representation of a resource. The only
  27. fields that will differ between resource types are "type", "data", and
  28. the mask fields. The "type" must be one of the keys in the ~resource-type~
  29. hash defined in resource.rkt, and the "data" and mask fields depend
  30. on the resource type.
  31. #+begin_src js
  32. { "name": "r1",
  33. "owner_id": 0,
  34. "data": { "path": "test1.txt",
  35. "metadata": "test1" },
  36. "type": "dataset-file",
  37. "default_mask" : { "metadata": "no-access",
  38. "data": "no-access"},
  39. "group_masks": {"0": {"metadata": "edit",
  40. "data": "edit"}
  41. }
  42. }
  43. #+end_src
  44. For reference, these are the types currently defined:
  45. *** dataset-file
  46. ~data~ should be a hash containing two fields, ~path~ which is a path
  47. to the data file, and ~metadata~ which is a Redis key containing
  48. some metadata.
  49. This type was created mainly for testing, hence its simplicity.
  50. *** dataset-geno
  51. ~data~ should be a hash containing two fields, ~dataset~ which is
  52. the name of a genotype dataset, and ~trait~ which is the name
  53. of a trait dataset. These are ~dataset.name~ and ~trait.name~
  54. in the Python query, respectively. One example is "BXDGeno"
  55. for the dataset name, and "rs3657281" for the trait name.
  56. Currently this only has one action branch, and really only one
  57. action, namely viewing data.
  58. A JSON example:
  59. #+begin_src js
  60. { "name": "some-resource",
  61. "owner_id": 0,
  62. "data": { "dataset": "BXDGeno",
  63. "trait": "rs365781" },
  64. "type": "dataset-geno",
  65. "default_mask" : { "data": "view" },
  66. "group_masks": { "0": {"data": "view"} }
  67. }
  68. #+end_src
  69. The query is defined in the function ~select-geno~, in ~resource.rkt~,
  70. and the result is provided as a string-encoded JSON array, transformed
  71. straight from the SQL result.
  72. *** dataset-publish
  73. ~data~ should be a hash containing two fields, ~dataset~ and ~trait~.
  74. The Python equivalents are ~dataset.id~ and ~trait.name~,
  75. respectively. The action set is essentially the same as for
  76. dataset-geno.
  77. A JSON example:
  78. #+begin_src js
  79. { "name": "some-resource",
  80. "owner_id": 0,
  81. "data": { "dataset": "1",
  82. "trait": "17465" },
  83. "type": "dataset-publish",
  84. "default_mask" : { "data": "view" },
  85. "group_masks": { "0": {"data": "view"} }
  86. }
  87. #+end_src
  88. The query is defined in the same module as dataset-geno, as the
  89. function ~select-publish~. The query result is transformed into
  90. a JSON array, with SQL nulls replaced by JSON nulls.
  91. ** Defining new resource types
  92. To define a new resource type, the ~resource-types~ hash in
  93. ~resource.rkt~ must be extended with an entry mapping the new resource
  94. type name (as a symbol) to the corresponding action set.
  95. An action set is a hash of action "branches", which are alists that
  96. map the name of each action (as a string) to the corresponding
  97. ~action~. An ~action~ is a value of the ~action~ struct, defined in
  98. ~privileges.rkt~, and is a function of two arguments, along with the
  99. names of any additional parameters that need to be provided by the
  100. user (e.g. in the request to the REST endpoint).
  101. It's probably best to just look at how one of the existing resource
  102. types are defined, and ~dataset-geno~ is one of the simplest, while
  103. still querying the SQL database.