Response.php 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382
  1. <?php
  2. /**
  3. * @copyright Copyright (c) 2016, ownCloud, Inc.
  4. *
  5. * @author Bernhard Posselt <dev@bernhard-posselt.com>
  6. * @author Christoph Wurst <christoph@owncloud.com>
  7. * @author Jörn Friedrich Dreyer <jfd@butonic.de>
  8. * @author Lukas Reschke <lukas@statuscode.ch>
  9. * @author Morris Jobke <hey@morrisjobke.de>
  10. * @author Roeland Jago Douma <roeland@famdouma.nl>
  11. * @author Thomas Müller <thomas.mueller@tmit.eu>
  12. * @author Thomas Tanghus <thomas@tanghus.net>
  13. *
  14. * @license AGPL-3.0
  15. *
  16. * This code is free software: you can redistribute it and/or modify
  17. * it under the terms of the GNU Affero General Public License, version 3,
  18. * as published by the Free Software Foundation.
  19. *
  20. * This program is distributed in the hope that it will be useful,
  21. * but WITHOUT ANY WARRANTY; without even the implied warranty of
  22. * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  23. * GNU Affero General Public License for more details.
  24. *
  25. * You should have received a copy of the GNU Affero General Public License, version 3,
  26. * along with this program. If not, see <http://www.gnu.org/licenses/>
  27. *
  28. */
  29. /**
  30. * Public interface of ownCloud for apps to use.
  31. * AppFramework\HTTP\Response class
  32. */
  33. namespace OCP\AppFramework\Http;
  34. use OCP\AppFramework\Http;
  35. use OCP\AppFramework\Utility\ITimeFactory;
  36. /**
  37. * Base class for responses. Also used to just send headers.
  38. *
  39. * It handles headers, HTTP status code, last modified and ETag.
  40. * @since 6.0.0
  41. */
  42. class Response {
  43. /**
  44. * Headers - defaults to ['Cache-Control' => 'no-cache, no-store, must-revalidate']
  45. * @var array
  46. */
  47. private $headers = array(
  48. 'Cache-Control' => 'no-cache, no-store, must-revalidate'
  49. );
  50. /**
  51. * Cookies that will be need to be constructed as header
  52. * @var array
  53. */
  54. private $cookies = array();
  55. /**
  56. * HTTP status code - defaults to STATUS OK
  57. * @var int
  58. */
  59. private $status = Http::STATUS_OK;
  60. /**
  61. * Last modified date
  62. * @var \DateTime
  63. */
  64. private $lastModified;
  65. /**
  66. * ETag
  67. * @var string
  68. */
  69. private $ETag;
  70. /** @var ContentSecurityPolicy|null Used Content-Security-Policy */
  71. private $contentSecurityPolicy = null;
  72. /** @var bool */
  73. private $throttled = false;
  74. /** @var array */
  75. private $throttleMetadata = [];
  76. /**
  77. * Response constructor.
  78. *
  79. * @since 17.0.0
  80. */
  81. public function __construct() {
  82. $this->setContentSecurityPolicy(new EmptyContentSecurityPolicy());
  83. }
  84. /**
  85. * Caches the response
  86. * @param int $cacheSeconds the amount of seconds that should be cached
  87. * if 0 then caching will be disabled
  88. * @return $this
  89. * @since 6.0.0 - return value was added in 7.0.0
  90. */
  91. public function cacheFor(int $cacheSeconds) {
  92. if($cacheSeconds > 0) {
  93. $this->addHeader('Cache-Control', 'max-age=' . $cacheSeconds . ', must-revalidate');
  94. // Old scool prama caching
  95. $this->addHeader('Pragma', 'public');
  96. // Set expires header
  97. $expires = new \DateTime();
  98. /** @var ITimeFactory $time */
  99. $time = \OC::$server->query(ITimeFactory::class);
  100. $expires->setTimestamp($time->getTime());
  101. $expires->add(new \DateInterval('PT'.$cacheSeconds.'S'));
  102. $this->addHeader('Expires', $expires->format(\DateTime::RFC2822));
  103. } else {
  104. $this->addHeader('Cache-Control', 'no-cache, no-store, must-revalidate');
  105. unset($this->headers['Expires'], $this->headers['Pragma']);
  106. }
  107. return $this;
  108. }
  109. /**
  110. * Adds a new cookie to the response
  111. * @param string $name The name of the cookie
  112. * @param string $value The value of the cookie
  113. * @param \DateTime|null $expireDate Date on that the cookie should expire, if set
  114. * to null cookie will be considered as session
  115. * cookie.
  116. * @return $this
  117. * @since 8.0.0
  118. */
  119. public function addCookie($name, $value, \DateTime $expireDate = null) {
  120. $this->cookies[$name] = array('value' => $value, 'expireDate' => $expireDate);
  121. return $this;
  122. }
  123. /**
  124. * Set the specified cookies
  125. * @param array $cookies array('foo' => array('value' => 'bar', 'expire' => null))
  126. * @return $this
  127. * @since 8.0.0
  128. */
  129. public function setCookies(array $cookies) {
  130. $this->cookies = $cookies;
  131. return $this;
  132. }
  133. /**
  134. * Invalidates the specified cookie
  135. * @param string $name
  136. * @return $this
  137. * @since 8.0.0
  138. */
  139. public function invalidateCookie($name) {
  140. $this->addCookie($name, 'expired', new \DateTime('1971-01-01 00:00'));
  141. return $this;
  142. }
  143. /**
  144. * Invalidates the specified cookies
  145. * @param array $cookieNames array('foo', 'bar')
  146. * @return $this
  147. * @since 8.0.0
  148. */
  149. public function invalidateCookies(array $cookieNames) {
  150. foreach($cookieNames as $cookieName) {
  151. $this->invalidateCookie($cookieName);
  152. }
  153. return $this;
  154. }
  155. /**
  156. * Returns the cookies
  157. * @return array
  158. * @since 8.0.0
  159. */
  160. public function getCookies() {
  161. return $this->cookies;
  162. }
  163. /**
  164. * Adds a new header to the response that will be called before the render
  165. * function
  166. * @param string $name The name of the HTTP header
  167. * @param string $value The value, null will delete it
  168. * @return $this
  169. * @since 6.0.0 - return value was added in 7.0.0
  170. */
  171. public function addHeader($name, $value) {
  172. $name = trim($name); // always remove leading and trailing whitespace
  173. // to be able to reliably check for security
  174. // headers
  175. if(is_null($value)) {
  176. unset($this->headers[$name]);
  177. } else {
  178. $this->headers[$name] = $value;
  179. }
  180. return $this;
  181. }
  182. /**
  183. * Set the headers
  184. * @param array $headers value header pairs
  185. * @return $this
  186. * @since 8.0.0
  187. */
  188. public function setHeaders(array $headers) {
  189. $this->headers = $headers;
  190. return $this;
  191. }
  192. /**
  193. * Returns the set headers
  194. * @return array the headers
  195. * @since 6.0.0
  196. */
  197. public function getHeaders() {
  198. $mergeWith = [];
  199. if($this->lastModified) {
  200. $mergeWith['Last-Modified'] =
  201. $this->lastModified->format(\DateTime::RFC2822);
  202. }
  203. // Build Content-Security-Policy and use default if none has been specified
  204. if(is_null($this->contentSecurityPolicy)) {
  205. $this->setContentSecurityPolicy(new ContentSecurityPolicy());
  206. }
  207. $this->headers['Content-Security-Policy'] = $this->contentSecurityPolicy->buildPolicy();
  208. if($this->ETag) {
  209. $mergeWith['ETag'] = '"' . $this->ETag . '"';
  210. }
  211. return array_merge($mergeWith, $this->headers);
  212. }
  213. /**
  214. * By default renders no output
  215. * @return string
  216. * @since 6.0.0
  217. */
  218. public function render() {
  219. return '';
  220. }
  221. /**
  222. * Set response status
  223. * @param int $status a HTTP status code, see also the STATUS constants
  224. * @return Response Reference to this object
  225. * @since 6.0.0 - return value was added in 7.0.0
  226. */
  227. public function setStatus($status) {
  228. $this->status = $status;
  229. return $this;
  230. }
  231. /**
  232. * Set a Content-Security-Policy
  233. * @param EmptyContentSecurityPolicy $csp Policy to set for the response object
  234. * @return $this
  235. * @since 8.1.0
  236. */
  237. public function setContentSecurityPolicy(EmptyContentSecurityPolicy $csp) {
  238. $this->contentSecurityPolicy = $csp;
  239. return $this;
  240. }
  241. /**
  242. * Get the currently used Content-Security-Policy
  243. * @return EmptyContentSecurityPolicy|null Used Content-Security-Policy or null if
  244. * none specified.
  245. * @since 8.1.0
  246. */
  247. public function getContentSecurityPolicy() {
  248. return $this->contentSecurityPolicy;
  249. }
  250. /**
  251. * Get response status
  252. * @since 6.0.0
  253. */
  254. public function getStatus() {
  255. return $this->status;
  256. }
  257. /**
  258. * Get the ETag
  259. * @return string the etag
  260. * @since 6.0.0
  261. */
  262. public function getETag() {
  263. return $this->ETag;
  264. }
  265. /**
  266. * Get "last modified" date
  267. * @return \DateTime RFC2822 formatted last modified date
  268. * @since 6.0.0
  269. */
  270. public function getLastModified() {
  271. return $this->lastModified;
  272. }
  273. /**
  274. * Set the ETag
  275. * @param string $ETag
  276. * @return Response Reference to this object
  277. * @since 6.0.0 - return value was added in 7.0.0
  278. */
  279. public function setETag($ETag) {
  280. $this->ETag = $ETag;
  281. return $this;
  282. }
  283. /**
  284. * Set "last modified" date
  285. * @param \DateTime $lastModified
  286. * @return Response Reference to this object
  287. * @since 6.0.0 - return value was added in 7.0.0
  288. */
  289. public function setLastModified($lastModified) {
  290. $this->lastModified = $lastModified;
  291. return $this;
  292. }
  293. /**
  294. * Marks the response as to throttle. Will be throttled when the
  295. * @BruteForceProtection annotation is added.
  296. *
  297. * @param array $metadata
  298. * @since 12.0.0
  299. */
  300. public function throttle(array $metadata = []) {
  301. $this->throttled = true;
  302. $this->throttleMetadata = $metadata;
  303. }
  304. /**
  305. * Returns the throttle metadata, defaults to empty array
  306. *
  307. * @return array
  308. * @since 13.0.0
  309. */
  310. public function getThrottleMetadata() {
  311. return $this->throttleMetadata;
  312. }
  313. /**
  314. * Whether the current response is throttled.
  315. *
  316. * @since 12.0.0
  317. */
  318. public function isThrottled() {
  319. return $this->throttled;
  320. }
  321. }