Lady’s Gitweb - CGirls/blob - request.h

   1 // SPDX-FileCopyrightText: 2025 Lady <https://www.ladys.computer/about/#lady>
   2 // SPDX-License-Identifier: GPL-2.0-only
   3
   4 /**
   5  ** This file defines types, constants, and function signatures
   6  ** necessary for dealing with the ⹐semantics⹑ of C·Girls requests.
   7  ** (Implementations of these functions are provided in `request.c´.)
   8  **/
   9
  10 #ifndef CGIRLS_REQUEST_H
  11 #define CGIRLS_REQUEST_H
  12
  13 /**
  14  ** § Types
  15  **////////////////////////////////////////////////////////////////////
  16 /**
  17  ** ❦ `enum ⸤cgirls_mtype⸥´
  18  **
  19  ** The `⸤cgirls_mtype⸥´ enumeration is used to indicate recognized
  20  ** mediatype extensions.
  21  **/
  22 enum cgirls_mtype : unsigned char {
  23 /**
  24  ** The value `⟨cgirls_mtype_any⟩´ indicates no mediatype preference.
  25  **/
  26         cgirls_mtype_any = 0,
  27
  28 /**
  29  ** The value `⟨cgirls_mtype_txt⟩´ indicates a preference for
  30  ** `text/plain´ content.
  31  **/
  32         cgirls_mtype_txt = 1,
  33
  34 /**
  35  ** The value `⟨cgirls_mtype_htm⟩´ indicates a preference for
  36  ** `text/html´ content.
  37  **/
  38         cgirls_mtype_htm = 2,
  39
  40 /**
  41  ** The value `⟨cgirls_mtype_xml⟩´ indicates a preference for
  42  ** `application/xml´ content, ideally with an `<?xml-stylesheet?>´
  43  ** processing instruction.
  44  **/
  45         cgirls_mtype_xml = 3,
  46
  47 /**
  48  ** The value `⟨cgirls_mtype_rdf⟩´ indicates a preference for
  49  ** `application/rdf+xml´ content.
  50  **/
  51         cgirls_mtype_rdf = 4,
  52
  53 };
  54 typedef enum cgirls_mtype cgirls_mtype;
  55
  56 /**
  57  ** ❦ `enum ⸤cgirls_vb⸥´
  58  **
  59  ** The `⸤cgirls_vb⸥´ enumeration is used to indicate recognized verbs
  60  ** for requests.
  61  **/
  62 enum cgirls_vb : unsigned char {
  63
  64 /**
  65  ** The value `⟨cgirls_vb_unknown⟩´ indicates an unknown or unspecified
  66  ** verb.
  67  **/
  68         cgirls_vb_unknown = 0,
  69
  70 /**
  71  ** The value `⟨cgirls_vb_index⟩´ indicates a request for an index of
  72  ** projects.
  73  **/
  74         cgirls_vb_index = 1,
  75
  76 /**
  77  ** The value `⟨cgirls_vb_branches⟩´ indicates a request for an index
  78  ** of branches in a given project. The value `⟨cgirls_vb_tags⟩´
  79  ** indicates a request for an index of tags.
  80  **/
  81         // cgirls_vb_branches = ??,
  82         // cgirls_vb_tags = ??,
  83
  84 /**
  85  ** The value `⟨cgirls_vb_show⟩´ indicates a request for an object in a
  86  ** human‐readable manner. The value `⟨cgirls_vb_raw⟩´ indicates a
  87  ** request for the raw contents of an object. The value
  88  ** `⟨cgirls_vb_blame⟩´ indicates a request for a blame of a commit.
  89  **/
  90         cgirls_vb_show = 2,
  91         // cgirls_vb_raw = ??,
  92         // cgirls_vb_blame = ??,
  93
  94 /**
  95  ** The value `⟨cgirls_vb_index⟩´ indicates a request for a diff
  96  ** between two commits.
  97  **/
  98         // cgirls_vb_diff = ??,
  99
 100 /**
 101  ** The values `⟨cgirls_vb_log⟩´, `⟨cgirls_vb_shortlog⟩´,
 102  ** `⟨cgirls_vb_atom⟩´, and `⟨cgirls_vb_patch⟩´ indicate requests for
 103  ** logs of a number of commits in various formats.
 104  **/
 105         // cgirls_vb_log = ??,
 106         // cgirls_vb_shortlog = ??,
 107         // cgirls_vb_atom = ??,
 108         // cgirls_vb_patch = ??,
 109
 110 /**
 111  ** Note that the numbering for verbs does not follow their order in
 112  ** the above list, but rather is fixed to when they were first
 113  ** supported. New verbs may be added in the future.
 114  **
 115  ** Verbs can be categorized into a few distinct classes :—
 116  **
 117  ** • Verbs which do not require a project :— `⟨cgirls_vb_index⟩´.
 118  **
 119  ** • Verbs which require a project, but not a revspec :—
 120  ** `⟨cgirls_vb_branches⟩´, `⟨cgirls_vb_tags⟩´.
 121  **
 122  ** • Verbs which request information about a single object :—
 123  ** `⟨cgirls_vb_show⟩´, `⟨cgirls_vb_raw⟩´, `⟨cgirls_vb_blame⟩´.
 124  **
 125  ** • Verbs which compare two commits :— `⟨cgirls_vb_diff⟩´.
 126  **
 127  ** • Verbs which produce information about an open‐ended number of
 128  ** commits :— `⟨cgirls_vb_log⟩´, `⟨cgirls_vb_shortlog⟩´,
 129  ** `⟨cgirls_vb_atom⟩´, `⟨cgirls_vb_patch⟩´.
 130  **/
 131 };
 132 typedef enum cgirls_vb cgirls_vb;
 133
 134 /**
 135  ** ❦ `struct ⸤cgirls_req_status⸥´
 136  **
 137  ** The struct `⸤cgirls_req_status⸥´ wraps a status code and message
 138  ** for a response.
 139  **
 140  ** The `⟨.message⟩´ is only significant if `⟨.code⟩´ is not `200´.
 141  **/
 142 typedef struct cgirls_req_status cgirls_req_status;
 143 struct cgirls_req_status {
 144         unsigned short code;
 145         char* message; // if `code´ is not ok
 146 };
 147
 148 /**
 149  ** ❦ `struct ⸤cgirls_req⸥´
 150  **
 151  ** The struct `⸤cgirls_req⸥´ represents a request.
 152  **
 153  ** Requests must have a verb, may specify a mediatype extension, and
 154  ** might also reference a project, revspec, and subpath. The value of
 155  ** `⟨.subpath⟩´, if not `⟨nullptr⟩´, must be a `⟨nullptr⟩´‐terminated
 156  ** array of strings.
 157  **
 158  ** All requests have a status, which is used to express request
 159  ** validity. If `⟨.status⟩⟨.code⟩´ is not `200´, the request is
 160  ** invalid and a response with the associated code and message is
 161  ** recommended.
 162  **/
 163 typedef struct cgirls_req cgirls_req;
 164 struct cgirls_req {
 165         cgirls_vb verb;
 166         cgirls_mtype mtype;
 167         char* project;
 168         char* id_THIS_WILL_CHANGE;
 169         char** subpath;
 170         char* baseid_THIS_WILL_CHANGE;
 171         cgirls_req_status status;
 172 };
 173
 174 /**
 175  ** § Functions
 176  **////////////////////////////////////////////////////////////////////
 177 /**
 178  ** ❦ `⸤cgirls_req⸥ ⟨cgirls_path·to·req⟩(⸤char const*const⸥)´
 179  **
 180  ** The `⟨cgirls_path·to·req⟩´ function takes a path string (such as
 181  ** one provided by the C·G·I `⟨PATH_INFO⟩´ environment variable) and
 182  ** returns a `⸤cgirls_req⸥´ which represents its semantics.
 183  **
 184  ** This resulting struct contains a lot of dynamically‐allocated data,
 185  ** so it ☞︎must☜︎ be freed with `⟨cgirls_req·free⟩´ after use.
 186  **
 187  ** Maximally, the path string is processed according to the following
 188  ** form :—
 189  **
 190  ** |`{project}/{action}/{revspec}/{subpath}´
 191  **
 192  ** —: (where `{subpath}´ can contain additional slashes, and
 193  ** `{action}´ consists of a verb and optionally a supported mediatype
 194  ** extension). Not all components necessarily need to be specified,
 195  ** and not all possible values are valid or meaningful.
 196  **
 197  ** In case of an error, `⟨.status⟩⟨.code⟩´ on the returned
 198  ** `⸤cgirls_req⸥´ will be some·thing other than `200´.
 199  **/
 200 cgirls_req cgirls_path·to·req(char const*const);
 201
 202 /**
 203  ** ❦ `⸤void⸥ ⟨cgirls_req·free⟩(⸤cgirls_req⸥)´
 204  **
 205  ** The `⟨cgirls_req·free⟩´ function frees up any dynamically‐allocated
 206  ** memory in the provided `⸤cgirls_req⸥´, assuming that it was created
 207  ** with `⟨cgirls_path·to·req⟩´ or similar.
 208  **/
 209 void cgirls_req·free(cgirls_req);
 210
 211 /**
 212  ** ❦ `⸤char*⸥ ⟨cgirls_req·to·path⟩(⸤cgirls_req⸥)´
 213  **
 214  ** The `⟨cgirls_req·to·path⟩´ function does the reverse of
 215  ** `⟨cgirls_path·to·req⟩´: It takes in a `⸤cgirls_req⸥´ struct and
 216  ** returns the canonical path string which represents it.
 217  **
 218  ** All possible `⸤cgirls_req⸥´s have a canonical string
 219  ** representation; `⟨cgirls_req·to·path⟩´ will only return `⟨nullptr⟩´
 220  ** if it fails to allocate memory while constructing the resulting
 221  ** string. Return values are dynamically allocated and must be
 222  ** manually freed with `⟨free⟩´.
 223  **
 224  ** It is worth noting that, if the `⟨.project⟩´ is the null pointer,
 225  ** the canonical path string will always be the empty string.
 226  **/
 227 char* cgirls_req·to·path(cgirls_req);
 228
 229 #endif /* CGIRLS_REQUEST_H */