async library for manda (adaptive backend manager protocol)
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.
 
 
 
 

109 lines
4.3 KiB

  1. #ifndef _LIBMANDA_LIBMANDA_PROTOCOL_H
  2. #define _LIBMANDA_LIBMANDA_PROTOCOL_H
  3. /*
  4. * The webserver side is considered to be the *client* here,
  5. * and the spawn manager the *server*.
  6. *
  7. * 16-bit | 16-bit
  8. * +------------+------------+
  9. * | Command | Paket size |
  10. * +-------------------------+
  11. * | Req ID | ResponseID |
  12. * +-------------------------+
  13. * | Payload... |
  14. * +-------------------------+
  15. *
  16. * ReqID == 0 if no response is expected
  17. * ResponseID != 0: response to the request with that id
  18. * Each side maintains its own set of request ids
  19. *
  20. * A response may use a different command; this depends on the commands.
  21. *
  22. * A request id can be reused after a response for it was received.
  23. * Don't use the same id for different commands at the same time.
  24. *
  25. * For now, commands are either:
  26. * - Requests: they have ReqID != 0 and ResponseID == 0
  27. * - Responses: ReqID == 0 and ResponseID == the request id the response is for
  28. * - Notifications: ReqID == 0 and ResponseID == 0
  29. *
  30. * Encoding rules:
  31. *
  32. * Integers are encoded in network byte order: the word 0xABCD is encoded as 0xAB 0xCD
  33. *
  34. * Socket adresses are encoded as strings, currently the following formats are defined:
  35. * - unix:/path/to/socket
  36. * - tcp:127.0.0.1:9000
  37. * - tcp:[::1]:9000
  38. * - udp:127.0.0.1:9000
  39. * - udp:[::1]:9000
  40. *
  41. * Strings are encoded as | length (unsigned 16-bit) | length * byte |, without terminating '\0'
  42. *
  43. * Commands:
  44. *
  45. * - 0x0001: Bind a new backend
  46. * Client -> Server (Request): bind_backend
  47. * payload is the "name" string.
  48. *
  49. * request the socket address for a "new" backend; the name can
  50. * basically be anything, it is recommended to use either the
  51. * socket address (for example "unix:/var/run/fastcgi_php_www-default.sock")
  52. * or a comma separated list of key=value pairs ("type=php5,user=www-default")
  53. *
  54. * Server -> Client (Response): return_backend
  55. * payload is a 32-bit backend identifier, followed by the socket address (or an error message)
  56. *
  57. * A valid backend identifier mustn't be zero, and a valid backend must have a valid socket address.
  58. * An error is signaled by a zero identifier, the following string contains an optional error message.
  59. *
  60. * The server should not return the same id more than once, not even for the same backend;
  61. * but different ids can point to the same backend and address.
  62. * (The reason here is that the server needs to sum up the update notifications.)
  63. * The backend id should only be unique per connection; you can reuse the ids for a different
  64. * connection.
  65. *
  66. * - 0x0002: Release backend
  67. * Client -> Server (Notification): release_backend
  68. * payload is the 32-bit backend identifier
  69. *
  70. * A connection close is an implicit release of all remaining backends.
  71. *
  72. * Server -> Client (Notification): lost_backend
  73. * payload ist the 32-bit backend identifier, followed by a string describing the reason
  74. *
  75. * I the client didn't already release the backend, it should send a release_backend
  76. * notification to release the id.
  77. *
  78. * - 0x0003: Update backend
  79. * Client -> Server (Notification): update_backend
  80. * payload are three unsigned 32-bit integers: backend identifier, "load" and "workers"
  81. * "load" is the number of requests the client would like to process with the backend right now,
  82. * and "workers" is the number of "workers" the client thinks the server should spawn.
  83. *
  84. * It is up to the server what to make of this information; in most cases it will ignore the "workers"
  85. * parameter and calculate the needed workers from the "load" parameter.
  86. *
  87. * The "workers" parameter may be useful in cases where you cascade different spawn-managers; the
  88. * main spawn-manager may tell a sub spawn-manager how many children / threads it should use.
  89. *
  90. * - 0xffff: Unknown command
  91. * Any direction; by default a notification, can be a response.
  92. * payload is the 16-bit id of the unknown command.
  93. *
  94. * If you get such a message, you should check for the id of the command, and close the connection
  95. * if the original message wasn't optional.
  96. *
  97. */
  98. typedef enum {
  99. MANDA_CMD_BIND_BACKEND = 0x0001,
  100. MANDA_CMD_RELEASE_BACKEND = 0x0002,
  101. MANDA_CMD_UPDATE_BACKEND = 0x0003,
  102. MANDA_CMD_UNKNOWN_COMMAND = 0xffff
  103. } manda_commands;
  104. #endif