summaryrefslogtreecommitdiff
path: root/indra/llcorehttp/httprequest.h
blob: 7f23723b0b005a5f44a4380594d49f605a444423 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
/**
 * @file httprequest.h
 * @brief Public-facing declarations for HttpRequest class
 *
 * $LicenseInfo:firstyear=2012&license=viewerlgpl$
 * Second Life Viewer Source Code
 * Copyright (C) 2012-2014, Linden Research, Inc.
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation;
 * version 2.1 of the License only.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * Linden Research, Inc., 945 Battery Street, San Francisco, CA  94111  USA
 * $/LicenseInfo$
 */

#ifndef	_LLCORE_HTTP_REQUEST_H_
#define	_LLCORE_HTTP_REQUEST_H_


#include "httpcommon.h"
#include "httphandler.h"


namespace LLCore
{

class HttpRequestQueue;
class HttpReplyQueue;
class HttpService;
class HttpOptions;
class HttpHeaders;
class HttpOperation;
class BufferArray;

/// HttpRequest supplies the entry into the HTTP transport
/// services in the LLCore libraries.  Services provided include:
///
/// - Some, but not all, global initialization of libcurl.
/// - Starting asynchronous, threaded HTTP requests.
/// - Definition of policy classes affect request handling.
/// - Utilities to control request options and headers
///
/// Requests
///
/// The class supports the current HTTP request operations:
///
/// - requestGetByteRange:  GET with Range header for a single range of bytes
/// - requestGet:
/// - requestPost:
/// - requestPut:
///
/// Policy Classes
///
/// <TBD>
///
/// Usage
///
/// <TBD>
///
/// Threading:  An instance may only be used by one application/
/// consumer thread.  But a thread may have as many instances of
/// this as it likes.
///
/// Allocation:  Not refcounted, may be stack allocated though that
/// hasn't been tested.  Queued requests can still run and any
/// queued replies will keep refcounts to the reply queue leading
/// to memory leaks.
///
/// @pre Before using this class (static or instances), some global
/// initialization is required.  See @see httpcommon.h for more information.
///
/// @nosubgrouping
///

class HttpRequest
{
public:
	HttpRequest();
	virtual ~HttpRequest();

private:
	HttpRequest(const HttpRequest &);			// Disallowed
	void operator=(const HttpRequest &);		// Disallowed		

public:
	typedef unsigned int policy_t;
	typedef unsigned int priority_t;
	
public:
	/// @name PolicyMethods
	/// @{

	/// Represents a default, catch-all policy class that guarantees
	/// eventual service for any HTTP request.
	static const policy_t DEFAULT_POLICY_ID = 0;
	static const policy_t INVALID_POLICY_ID = 0xFFFFFFFFU;
	static const policy_t GLOBAL_POLICY_ID = 0xFFFFFFFEU;

	/// Create a new policy class into which requests can be made.
	///
	/// All class creation must occur before threads are started and
	/// transport begins.  Policy classes are limited to a small value.
	/// Currently that limit is the default class + 1.
	///
	/// @return			If positive, the policy_id used to reference
	///					the class in other methods.  If 0, requests
	///					for classes have exceeded internal limits
	///					or caller has tried to create a class after
	///					threads have been started.  Caller must fallback
	///					and recover.
	///
	static policy_t createPolicyClass();

	enum EPolicyOption
	{
		/// Maximum number of connections the library will use to
		/// perform operations.  This is somewhat soft as the underlying
		/// transport will cache some connections (up to 5).

		/// A long value setting the maximum number of connections
		/// allowed over all policy classes.  Note that this will be
		/// a somewhat soft value.  There may be an additional five
		/// connections per policy class depending upon runtime
		/// behavior.
		///
		/// Both global and per-class
		PO_CONNECTION_LIMIT,

		/// Limits the number of connections used for a single
		/// literal address/port pair within the class.
		///
		/// Per-class only
		PO_PER_HOST_CONNECTION_LIMIT,

		/// String containing a system-appropriate directory name
		/// where SSL certs are stored.
		///
		/// Global only
		PO_CA_PATH,

		/// String giving a full path to a file containing SSL certs.
		///
		/// Global only
		PO_CA_FILE,

		/// String of host/port to use as simple HTTP proxy.  This is
		/// going to change in the future into something more elaborate
		/// that may support richer schemes.
		///
		/// Global only
		PO_HTTP_PROXY,

		/// Long value that if non-zero enables the use of the
		/// traditional LLProxy code for http/socks5 support.  If
		// enabled, has priority over GP_HTTP_PROXY.
		///
		/// Global only
		PO_LLPROXY,

		/// Long value setting the logging trace level for the
		/// library.  Possible values are:
		/// 0 - No tracing (default)
		/// 1 - Basic tracing of request start, stop and major events.
		/// 2 - Connection, header and payload size information from
		///     HTTP transactions.
		/// 3 - Partial logging of payload itself.
		///
		/// These values are also used in the trace modes for
		/// individual requests in HttpOptions.  Also be aware that
		/// tracing tends to impact performance of the viewer.
		///
		/// Global only
		PO_TRACE,

		/// If greater than 1, suitable requests are allowed to
		/// pipeline on their connections when they ask for it.
		/// Value gives the maximum number of outstanding requests
		/// on a connection.
		///
		/// There is some interaction between PO_CONNECTION_LIMIT,
		/// PO_PER_HOST_CONNECTION_LIMIT, and PO_PIPELINING_DEPTH.
		/// When PIPELINING_DEPTH is 0 or 1 (no pipelining), this
		/// library manages connection lifecycle and honors the
		/// PO_CONNECTION_LIMIT setting as the maximum in-flight
		/// request limit.  Libcurl itself may be caching additional
		/// connections under its connection cache policy.
		///
		/// When PIPELINING_DEPTH is 2 or more, libcurl performs
		/// connection management and both PO_CONNECTION_LIMIT and
		/// PO_PER_HOST_CONNECTION_LIMIT should be set and non-zero.
		/// In this case (as of libcurl 7.37.0), libcurl will
		/// open new connections in preference to pipelining, up
		/// to the above limits at which time pipelining begins.
		/// And as usual, an additional cache of open but inactive
		/// connections may still be maintained within libcurl.
		/// For SL, a good rule-of-thumb is to set
		/// PO_PER_HOST_CONNECTION_LIMIT to the user-visible
		/// concurrency value and PO_CONNECTION_LIMIT to twice
		/// that for baked texture loads and region crossings where
		/// additional connection load will be tolerated.  If
		/// either limit is 0, libcurl will prefer pipelining
		/// over connection creation, which is still interesting,
		/// but won't be pursued at this time.
		///
		/// Per-class only
		PO_PIPELINING_DEPTH,

		/// Controls whether client-side throttling should be
		/// performed on this policy class.  Positive values
		/// enable throttling and specify the request rate
		/// (requests per second) that should be targetted.
		/// A value of zero, the default, specifies no throttling.
		///
		/// Per-class only
		PO_THROTTLE_RATE,
		
		PO_LAST  // Always at end
	};

	/// Set a policy option for a global or class parameter at
	/// startup time (prior to thread start).
	///
	/// @param opt			Enum of option to be set.
	/// @param pclass		For class-based options, the policy class ID to
	///					    be changed.  For globals, specify GLOBAL_POLICY_ID.
	/// @param value		Desired value of option.
	/// @param ret_value	Pointer to receive effective set value
	///						if successful.  May be NULL if effective
	///						value not wanted.
	/// @return				Standard status code.
	static HttpStatus setStaticPolicyOption(EPolicyOption opt, policy_t pclass,
											long value, long * ret_value);
	static HttpStatus setStaticPolicyOption(EPolicyOption opt, policy_t pclass,
											const std::string & value, std::string * ret_value);

	/// Set a parameter on a class-based policy option.  Calls
	/// made after the start of the servicing thread are
	/// not honored and return an error status.
	///
	/// @param opt			Enum of option to be set.
	/// @param pclass		For class-based options, the policy class ID to
	///					    be changed.  Ignored for globals but recommend
	///					    using INVALID_POLICY_ID in this case.
	/// @param value		Desired value of option.
	/// @return				Handle of dynamic request.  Use @see getStatus() if
	///						the returned handle is invalid.
	HttpHandle setPolicyOption(EPolicyOption opt, policy_t pclass, long value,
							   HttpHandler * handler);
	HttpHandle setPolicyOption(EPolicyOption opt, policy_t pclass, const std::string & value,
							   HttpHandler * handler);

	/// @}

	/// @name RequestMethods
	///
	/// @{

	/// Some calls expect to succeed as the normal part of operation and so
	/// return a useful value rather than a status.  When they do fail, the
	/// status is saved and can be fetched with this method.
	///
	/// @return			Status of the failing method invocation.  If the
	///					preceding call succeeded or other HttpStatus
	///					returning calls immediately preceded this method,
	///					the returned value may not be reliable.
	///
	HttpStatus getStatus() const;

	/// Queue a full HTTP GET request to be issued for entire entity.
	/// The request is queued and serviced by the working thread and
	/// notification of completion delivered to the optional HttpHandler
	/// argument during @see update() calls.
	///
	/// With a valid handle returned, it can be used to reference the
	/// request in other requests (like cancellation) and will be an
	/// argument when any HttpHandler object is invoked.
	///
	/// Headers supplied by default:
	/// - Connection: keep-alive
	/// - Accept: */*
	/// - Accept-Encoding: deflate, gzip
	/// - Keep-alive: 300
	/// - Host: <stuff>
	///
	/// Some headers excluded by default:
	/// - Pragma:
	/// - Cache-control:
	/// - Range:
	/// - Transfer-Encoding:
	/// - Referer:
	///
	/// @param	policy_id		Default or user-defined policy class under
	///							which this request is to be serviced.
	/// @param	priority		Standard priority scheme inherited from
	///							Indra code base (U32-type scheme).
	/// @param	url				URL with any encoded query parameters to
	///							be accessed.
	/// @param	options			Optional instance of an HttpOptions object
	///							to provide additional controls over the request
	///							function for this request only.  Any such
	///							object then becomes shared-read across threads
	///							and no code should modify the HttpOptions
	///							instance.
	/// @param	headers			Optional instance of an HttpHeaders object
	///							to provide additional and/or overridden
	///							headers for the request.  As with options,
	///							the instance becomes shared-read across threads
	///							and no code should modify the HttpHeaders
	///							instance.
	/// @param	handler			Optional pointer to an HttpHandler instance
	///							whose onCompleted() method will be invoked
	///							during calls to update().  This is a non-
	///							reference-counted object which would be a
	///							problem for shutdown and other edge cases but
	///							the pointer is only dereferenced during
	///							calls to update().
	///
	/// @return					The handle of the request if successfully
	///							queued or LLCORE_HTTP_HANDLE_INVALID if the
	///							request could not be queued.  In the latter
	///							case, @see getStatus() will return more info.
	///
	HttpHandle requestGet(policy_t policy_id,
						  priority_t priority,
						  const std::string & url,
						  HttpOptions * options,
						  HttpHeaders * headers,
						  HttpHandler * handler);


	/// Queue a full HTTP GET request to be issued with a 'Range' header.
	/// The request is queued and serviced by the working thread and
	/// notification of completion delivered to the optional HttpHandler
	/// argument during @see update() calls.
	///
	/// With a valid handle returned, it can be used to reference the
	/// request in other requests (like cancellation) and will be an
	/// argument when any HttpHandler object is invoked.
	///
	/// Headers supplied by default:
	/// - Connection: keep-alive
	/// - Accept: */*
	/// - Accept-Encoding: deflate, gzip
	/// - Keep-alive: 300
	/// - Host: <stuff>
	/// - Range: <stuff>  (will be omitted if offset == 0 and len == 0)
	///
	/// Some headers excluded by default:
	/// - Pragma:
	/// - Cache-control:
	/// - Transfer-Encoding:
	/// - Referer:
	///
	/// @param	policy_id		@see requestGet()
	/// @param	priority		"
	/// @param	url				"
	/// @param	offset			Offset of first byte into resource to be returned.
	/// @param	len				Count of bytes to be returned
	/// @param	options			@see requestGet()
	/// @param	headers			"
	/// @param	handler			"
	/// @return					"
	///
	HttpHandle requestGetByteRange(policy_t policy_id,
								   priority_t priority,
								   const std::string & url,
								   size_t offset,
								   size_t len,
								   HttpOptions * options,
								   HttpHeaders * headers,
								   HttpHandler * handler);


	/// Queue a full HTTP POST.  Query arguments and body may
	/// be provided.  Caller is responsible for escaping and
	/// encoding and communicating the content types.
	///
	/// Headers supplied by default:
	/// - Connection: keep-alive
	/// - Accept: */*
	/// - Accept-Encoding: deflate, gzip
	/// - Keep-Alive: 300
	/// - Host: <stuff>
	/// - Content-Length: <digits>
	/// - Content-Type: application/x-www-form-urlencoded
	///
	/// Some headers excluded by default:
	/// - Pragma:
	/// - Cache-Control:
	/// - Transfer-Encoding: ... chunked ...
	/// - Referer:
	/// - Content-Encoding:
	/// - Expect:
	///
	/// @param	policy_id		@see requestGet()
	/// @param	priority		"
	/// @param	url				"
	/// @param	body			Byte stream to be sent as the body.  No
	///							further encoding or escaping will be done
	///							to the content.
	/// @param	options			@see requestGet()K(optional)
	/// @param	headers			"
	/// @param	handler			"
	/// @return					"
	///
	HttpHandle requestPost(policy_t policy_id,
						   priority_t priority,
						   const std::string & url,
						   BufferArray * body,
						   HttpOptions * options,
						   HttpHeaders * headers,
						   HttpHandler * handler);


	/// Queue a full HTTP PUT.  Query arguments and body may
	/// be provided.  Caller is responsible for escaping and
	/// encoding and communicating the content types.
	///
	/// Headers supplied by default:
	/// - Connection: keep-alive
	/// - Accept: */*
	/// - Accept-Encoding: deflate, gzip
	/// - Keep-Alive: 300
	/// - Host: <stuff>
	/// - Content-Length: <digits>
	///
	/// Some headers excluded by default:
	/// - Pragma:
	/// - Cache-Control:
	/// - Transfer-Encoding: ... chunked ...
	/// - Referer:
	/// - Content-Encoding:
	/// - Expect:
	/// - Content-Type:
	///
	/// @param	policy_id		@see requestGet()
	/// @param	priority		"
	/// @param	url				"
	/// @param	body			Byte stream to be sent as the body.  No
	///							further encoding or escaping will be done
	///							to the content.
	/// @param	options			@see requestGet()K(optional)
	/// @param	headers			"
	/// @param	handler			"
	/// @return					"
	///
	HttpHandle requestPut(policy_t policy_id,
						  priority_t priority,
						  const std::string & url,
						  BufferArray * body,
						  HttpOptions * options,
						  HttpHeaders * headers,
						  HttpHandler * handler);


	/// Queue a NoOp request.
	/// The request is queued and serviced by the working thread which
	/// immediately processes it and returns the request to the reply
	/// queue.
	///
	/// @param	handler			@see requestGet()
	/// @return					"
	///
	HttpHandle requestNoOp(HttpHandler * handler);

	/// While all the heavy work is done by the worker thread, notifications
	/// must be performed in the context of the application thread.  These
	/// are done synchronously during calls to this method which gives the
	/// library control so notification can be performed.  Application handlers
	/// are expected to return 'quickly' and do any significant processing
	/// outside of the notification callback to onCompleted().
	///
	/// @param	usecs			Maximum number of wallclock microseconds to
	///							spend in the call.  As hinted at above, this
	///							is partly a function of application code so it's
	///							a soft limit.  A '0' value will run without
	///							time limit until everything queued has been
	///							delivered.
	///
	/// @return					Standard status code.
	HttpStatus update(long usecs);

	/// @}
	
	/// @name RequestMgmtMethods
	///
	/// @{
	
	HttpHandle requestCancel(HttpHandle request, HttpHandler *);

	/// Request that a previously-issued request be reprioritized.
	/// The status of whether the change itself succeeded arrives
	/// via notification.  
	///
	/// @param	request			Handle of previously-issued request to
	///							be changed.
	/// @param	priority		New priority value.
	/// @param	handler			@see requestGet()
	/// @return					"
	///
	HttpHandle requestSetPriority(HttpHandle request, priority_t priority, HttpHandler * handler);

	/// @}

	/// @name UtilityMethods
	///
	/// @{

	/// Initialization method that needs to be called before queueing any
	/// requests.  Doesn't start the worker thread and may be called befoer
	/// or after policy setup.
	static HttpStatus createService();

	/// Mostly clean shutdown of services prior to exit.  Caller is expected
	/// to have stopped a running worker thread before calling this.
	static HttpStatus destroyService();

	/// Called once after @see createService() to start the worker thread.
	/// Stopping the thread is achieved by requesting it via @see requestStopThread().
	/// May be called before or after requests are issued.
	static HttpStatus startThread();

	/// Queues a request to the worker thread to have it stop processing
	/// and exit (without exiting the program).  When the operation is
	/// picked up by the worker thread, it immediately processes it and
	/// begins detaching from refcounted resources like request and
	/// reply queues and then returns to the host OS.  It *does* queue a
	/// reply to give the calling application thread a notification that
	/// the operation has been performed.
	///
	/// @param	handler			(optional)
	/// @return					The handle of the request if successfully
	///							queued or LLCORE_HTTP_HANDLE_INVALID if the
	///							request could not be queued.  In the latter
	///							case, @see getStatus() will return more info.
	///							As the request cannot be cancelled, the handle
	///							is generally not useful.
	///
	HttpHandle requestStopThread(HttpHandler * handler);

	/// Queue a Spin request.
	/// DEBUG/TESTING ONLY.  This puts the worker into a CPU spin for
	/// test purposes.
	///
	/// @param	mode			0 for hard spin, 1 for soft spin
	/// @return					Standard handle return cases.
	///
	HttpHandle requestSpin(int mode);

	/// @}
	
protected:
	void generateNotification(HttpOperation * op);

private:
	/// @name InstanceData
	///
	/// @{
	HttpStatus			mLastReqStatus;
	HttpReplyQueue *	mReplyQueue;
	HttpRequestQueue *	mRequestQueue;
	
	/// @}
	
	// ====================================
	/// @name GlobalState
	///
	/// @{
	///
	/// Must be established before any threading is allowed to
	/// start.
	///
	
	/// @}
	// End Global State
	// ====================================
	
};  // end class HttpRequest


}  // end namespace LLCore



#endif	// _LLCORE_HTTP_REQUEST_H_