idnits 2.17.1 draft-janssen-httpng-wire-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-18) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 1 longer page, the longest (page 1) being 1126 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 35 instances of too long lines in the document, the longest one being 25 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 675 has weird spacing: '...pe with a min...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (1 August 1998) is 9392 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'MUX' is mentioned on line 954, but not defined == Unused Reference: 'RFC 2277' is defined on line 1106, but no explicit reference was found in the text -- Possible downref: Non-RFC (?) normative reference: ref. 'HTTP-ng-arch' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTTP-ng-goals' -- Possible downref: Non-RFC (?) normative reference: ref. 'HTTP-ng-webmux' ** Obsolete normative reference: RFC 1831 (Obsoleted by RFC 5531) ** Obsolete normative reference: RFC 1832 (Obsoleted by RFC 4506) ** Obsolete normative reference: RFC 2278 (Obsoleted by RFC 2978) Summary: 13 errors (**), 0 flaws (~~), 5 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Bill Janssen 2 Internet Draft Xerox PARC 3 expires in six months 1 August 1998 5 w3ng: Binary Wire Protocol for HTTP-ng 7 9 Status of this Document 10 *********************** 12 This document is an Internet-Draft. Internet-Drafts are working 13 documents of the Internet Engineering Task Force (IETF), its areas, and 14 its working groups. Note that other groups may also distribute working 15 documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet-Drafts as reference material 20 or to cite them other than as "work in progress." 22 To view the entire list of current Internet-Drafts, please check the 23 "1id-abstracts.txt" listing contained in the Internet-Drafts Shadow 24 Directories on ftp.is.co.za (Africa), ftp.nordu.net (Northern Europe), 25 ftp.nis.garr.it (Southern Europe), munnari.oz.au (Pacific Rim), 26 ftp.ietf.org (US East Coast), or ftp.isi.edu (US West Coast). 28 This document has been produced as part of the W3C HTTP-ng Activity 29 (for current status, see 30 "http://www.w3.org/Protocols/HTTP-NG/Activity"). This is work in 31 progress and does not imply endorsement by, or the consensus of, either 32 W3C or members of the HTTP-ng Protocol Design Working Group. We expect 33 the document to evolve considerably as the project continues. 35 Distribution of this document is unlimited. Please send comments to 36 the HTTP-NG mailing list at . Discussions 37 are archived at "http://www.w3.org/Protocols/HTTP-NG/". 39 Please read the "HTTP-NG Short- and Longterm Goals" [HTTP-ng-goals] 40 for a discussion of goals and requirements of a potential new 41 generation of the HTTP protocol and how we intend to evaluate these 42 goals. 44 Abstract 45 ******** 47 This document describes a binary `on-the-wire' protocol to be used 48 when sending HTTP-NG operation invocations or terminations across a 49 network connection. 51 Table of Contents 52 ***************** 54 1. Terminology and Syntax 55 2. Model of Operation 56 3. Global Issues 57 4. Utility Types 58 5. Messages 59 5.1. Extension Headers 60 5.2. Request Message 61 5.2.1. Operation and Object Memoizing 62 5.3. Reply Message 63 5.4. InitializeConnection Message 64 5.5. TerminateConnection Message 65 5.6. DefaultCharset Message 66 6. Data Marshalling 67 7. Connection Exceptions 68 8. Security Considerations 69 9. References 70 10. Address of Author 72 1. Terminology and Syntax 73 ************************** 75 Two data description languages are used in this document. The first 76 is a pseudo-C syntax. It should be interpreted as C data structure 77 layouts without any automatic padding to size boundaries, and allowing 78 arbitrary bit-size limits on structs and unions as well as on ints and 79 enums. The second is the data structure definition language defined in 80 the XDR specification [RFC 1832]. Each use of pseudo-C and XDR is 81 marked as to which language is being used. 83 This document uses a number of terms which are defined in the 84 HTTP-ng Architecture Model document [HTTP-ng-arch]. It also references 85 the type system defined in that document. 87 2. Model of Operation 88 ********************** 90 This protocol assumes a particular model of operation based on 91 conventional request/response messaging technology, with certain 92 variations, as described in the HTTP-ng Architecture Model 93 [HTTP-ng-arch]. The basic idea is that clients make use of services 94 exported from a server by invoking operations on objects resident in 95 that server. This model also assumes only hop-by-hop operation; 96 proxying is supported at the application level. 98 The model used here assumes that operations are grouped into sets, 99 the elements of which have a well-defined ordering; each operation set 100 is called an "object type". It further assumes that an object type is 101 identified by a UUID in the form of a URI; and that each operation in an 102 object type can be identified with the ordinal number of the operation 103 within the ordering of the elements of the object type. It assumes 104 that every object has an "object ID", which also forms a unique 105 identifier. It provides for the fact that instances of object types 106 are grouped into "object groups"; an object group may contain any 107 number of instances, even only a single instance. Object IDs always 108 consist of a unique identifier for the object group of the instance, 109 which we call the "group ID", along with a group-relative identifier we 110 call the "instance handle". Note that grouping of instances is not 111 required (i.e., every instance might define its own object group), but 112 the protocol provides an efficiency optimization for the case where it 113 is true. 115 The client is connected to the server by a "connection", which 116 carries operation invocation requests from the client (known as the 117 "caller") to the server (known as the "callee"), and operation results 118 from the callee back to the caller. The connection has state 119 associated with it, which allows the caller and callee to use shorthand 120 notations for some of the data passed to the other party. Connections, 121 in this model, are to a particular object group on the server; multiple 122 connections can exist simultaneously between the same client and server, 123 to different object groups; multiple connections to the same object 124 group are also allowed. This protocol does not currently allow 125 multiplexing of a single connection across multiple object groups; the 126 HTTP-ng webmux transport layer is assumed to fulfill that function 127 [HTTP-ng-webmux]. 129 Two fundamental messages are defined by this protocol: the Request, 130 which is used by the caller to invoke an operation on the callee, and 131 the Reply, which is used to transfer the results of an operation from 132 the callee to the caller. Every Reply message is associated with a 133 particular Request message, but not every Request message has a Reply 134 message associated with it. Connections are directional; operation 135 invocation Requests always flow from the caller to the callee; Replies 136 always flow from the callee to the caller. In addition to these 137 messages, several control messages are defined for this protocol. 138 These control messages are used to improve the efficiency and 139 robustness of the connection. They are intended to be generated and 140 consumed by the implementation of the wire protocol, and should have no 141 direct effect on the applications using the protocol. 143 A Request message indicates two important elements, the "operation" 144 and the "discriminant object", or discriminant; it also contains data 145 values which are the input parameters to the operation. Each Request 146 has an implicit connection-specific serial number associated with it; 147 serial numbers begin with the value one (1), and have a maximum value 148 of 16777215. When the maximum serial number of a connection has been 149 reached, the connection must be terminated, and further operations must 150 be invoked over a new connection. 152 A Reply message indicates the termination status of the operation, 153 provides information about synchronization, and may contain data values 154 which are output parameters or `return values' from the operation. It 155 contains an explicit serial number to indicate which Request it is a 156 reply to. Replies may either indicate successful completion of the 157 operation, or several different kinds of exceptional termination; if an 158 exception is signalled, additional information is passed to indicate 159 which of the possible exceptions for the operation was raised. 161 The model assumes that the messages are carried back and forth 162 between the two parties by a "transport" subsystem. It requires that 163 the transport subsystem be "reliable", "sequenced", and 164 "message-oriented". By reliable, we mean that after a message is 165 handed to the transport, the transport will either deliver it to the 166 other party, or will signal an error if its reliable delivery cannot be 167 ascertained. By sequenced, we mean that the transport will deliver 168 messages to the other party in the same order in which the sender 169 handed them to the transport. By message-oriented, we mean that the 170 transport will provide indication of the beginning and ending of the 171 messages, without reference to any data encoded inside the message. An 172 example of this type of transport would be the record marking defined 173 in ONC RPC [RFC 1831] used with TCP/IP, or the HTTP-ng webmux transport 174 layer [HTTP-ng-webmux] used with TCP/IP. 176 3. Global Issues 177 ***************** 179 3.1. Byte Order 180 ================ 182 All values use `network standard' byte order, i.e. big-endian, 183 because all Internet protocols use it. If in the future this becomes a 184 problem for the Internet, this protocol will be affected by whatever 185 solution is used to solve the problem in the wider Internet context. 186 Note that the data marshalling format defined in XDR, which this 187 protocol incorporates by reference, is also defined to be a big-endian 188 protocol. 190 3.2. Alignment and Padding 191 =========================== 193 The marshalled form of each value begins on a 32-bit boundary. The 194 marshalled form of each value is padded-after, if necessary, to the 195 next 32-bit boundary. The padding bits may be either 0 or 1 in any 196 combination. 198 3.3. Marshalling Format 199 ======================== 201 Marshalling is via the XDR format specified in the XDR specification 202 [RFC 1832]. It could be argued that this format is inexcusably 203 wasteful with certain value types, such as boolean (32 bits) or byte 204 (32 bits), and that a 16-bit or 8-bit oriented format should be 205 designed and used in its place. However, the argument of using an 206 existing Internet standards-track marshalling format for this purpose, 207 rather than inventing a new one, is a strong one; a new format should 208 only be defined if measurement of the overhead shows gross waste, or if 209 progress of the XDR specification slows unacceptably. Additionally, the 210 simplicity of the XDR specification should allow correct 211 implementations of it to be realized with a minimum of effort. 213 3.4. Session Context 214 ===================== 216 Unlike some previous protocols, this protocol is "session-oriented". 217 That means that individual messages are sent in the context of a 218 session, and are context-sensitive. This context-sensitivity allows 219 session-wide compression. However, to support various kinds of 220 marshalling architectures in implementations of this system, all 221 marshalling can be done in a context-insensitive fashion, at the 222 expense of sending additional bytes across the wire. However, 223 unmarshalling implementations must always be capable of tracking and 224 using context-sensitive information. 226 4. Utility types 227 **************** 229 The following data structures are defined in pseudo-C: 230 typedef enum { 231 False = 0, 232 True = 1 233 } Boolean; 235 typedef enum { 236 InitializeConnection = 0, 237 TerminateConnection = 1, 238 DefaultCharset = 2 239 } ControlMsgType; 241 typedef enum { 242 Success = 0, 243 UserException = 1, /* occurred during operation */ 244 SystemExceptionBefore = 2, /* occurred before beginning operation */ 245 SystemExceptionAfter = 3 /* occurred after beginning operation */ 246 } ReplyStatus; 248 typedef struct { 249 Boolean cached_disc : 1; /* True if cached object key */ 250 union { 251 struct { 252 Boolean cache_key : 1; /* True if both sides cache it */ 253 unsigned key_len : 13; /* length of key bytes */ 254 } uncached_key; 255 unsigned cache_index : 14; /* cache index if cached */ 256 } v; 257 } DiscriminantID; 259 typedef struct { 260 Boolean cached_op : 1; /* True if cached id */ 261 union { 262 struct { 263 Boolean cache_operation : 1; /* True if should be cached */ 264 unsigned method_id : 13; /* method index */ 265 } uncached_op_info; 266 unsigned cache_index : 14; /* cache index if "cached_op" set */ 267 } v; 268 } OperationID; 270 typedef enum { 271 MangledMessage = 0, /* bad protocol synchronization */ 272 ProcessFinished = 1, /* sending party has `exitted' */ 273 ResourceManagement = 2, /* transient close */ 274 WrongCallee = 3, /* bad object group ID received */ 275 MaxSerialNumber = 4 /* the maximum serial number was used */ 276 } TerminationCause; 278 typedef struct { 279 unsigned major : 4; 280 unsigned minor : 4; 281 } ProtocolVersion; 283 typedef unsigned Unused; 285 5. Messages 286 *********** 288 Only a few messages are defined. The `InitializeConnection' message 289 is used by the caller to verify that it has connected to the right 290 server, and that it is using the correct version of the wire protocol. 291 The `DefaultCharset' message allows both sides to independently define 292 a default value for string charsets. The `Request' message causes an 293 operation to be started on the remote server. The `Reply' message is 294 sent from the server to the client to inform it of the completion 295 status of the operation, and to convey any result values. The 296 `TerminateConnection' message allows either side to indicate graceful 297 shutdown of a connection. 299 5.1. Extension Headers 300 ======================= 302 This protocol uses a mechanism called an "extension header" to 303 provide for extensibility and tailorability. Features such as 304 transaction contexts or global thread identifiers may be implemented 305 via this mechanism. An extension header is name-value pair, where the 306 name is a UUID expressed as a URI, and the value is an HTTP-ng pickle 307 (see [HTTP-ng-arch]) value. This name-value pair is then expressed as 308 an XDR value of the type `ExtensionHeader' as described below. Each 309 request message and reply message may contain a sequence of extension 310 headers, expressed as a value of the XDR type `ExtensionHeaderList'. 311 /* XDR */ 312 struct { 313 string name<0xFFFF>; /* URI for extension header */ 314 opaque value<>; /* Pickle containing value of header */ 315 } ExtensionHeader; 316 typedef ExtensionHeader ExtensionHeaderList<>; 318 5.2. `Request' Message 319 ======================= 321 Request header (pseudo-C): 323 typedef struct { 324 Boolean control_msg : 1; /* == FALSE */ 325 Boolean ext_hdr_present : 1; /* True if ext hdr list present */ 326 OperationID operation_id : 15; /* identifies operation */ 327 DiscriminantID object_key : 15; /* identifies discriminant */ 328 } RequestMsgHeader /* 4 bytes total */ 330 The actual message consists of the following sections: 332 [ `RequestMsgHeader' ] 333 [ extension header list, if any ] 334 [ XDR `string' containing object type ID of object type defining 335 operation, if not cached ] 336 [ bytes of OBJECT_KEY, if not cached, padded to 4 byte boundary ] 337 [ explicit input parameter values, if any, padded to a 4 byte boundary ] 339 The OPERATION_ID contains either a connection-specific 14-bit cache 340 index, or a 13-bit method id (the zero-based ordinal position of the 341 method in the definition of the object type in which the operation is 342 defined) of the operation. If the method id is given, an additional 343 value, an XDR `string' value containing the object type ID of the 344 object type in which the operation is defined, is also passed. This 345 means that this protocol will not support interfaces in which object 346 types have more than 8192 methods directly defined. 348 The OBJECT_KEY is either a 14-bit connection-specific cache index, 349 or the length of a variable length octet sequence of 8192 or fewer 350 bytes containing the service-point-relative name for the object (the 351 INSTANCE-HANDLE of the URL). The object key value of `{ False, False, 352 0 }', normally a zero byte variable length object key, is reserved for 353 use by the protocol. The OBJECT_KEY is marshalled onto the transport 354 as an XDR value of type `fixed-length opaque data', where the length is 355 that specified in the `v.key_len' field of the OBJECT_KEY. 357 5.2.1 Operation and Object Memoizing 358 ------------------------------------ 360 Callers may reduce the size of messages by memoizing operation IDs 361 and object IDs that are passed in the connection. This is done by the 362 caller setting the `cache_key' (for object IDs) or `cache_operation' 363 (for operation IDs) bit in the `DiscriminantID' or `OperationID' struct 364 when the object key or operation ID is first sent. Each side must then 365 assign the next available index to that object or operation. The space 366 of operations is separate from the space of object ids, so that a total 367 of 16383 possible values is available for memoizing of discriminant 368 objects, and 16383 different possible values for memoizing of 369 operations. 371 Note that the index is passed implicitly, so both sides of the 372 connection must synchronize their use of indices. 374 A shared set of indices may be loaded into the connection by some 375 mechanism before any messages are sent. This specification does not 376 define a mechanism for doing so. 378 5.3. `Reply' Message 379 ===================== 381 Reply header (pseudo-C): 383 typedef struct { 384 Boolean control_msg : 1; /* == FALSE */ 385 Boolean ext_hdr_present : 1; /* True if ext hdr list present */ 386 ReplyStatus : 2; 387 Unused reply_1 : 4; 388 unsigned serial_no : 24; /* serial # from Request */ 389 } ReplyMsgHeader; /* 4 bytes total */ 391 The actual message consists of the following fields: 393 [ `ReplyMsgHeader' ] 394 [ extension header list, if any ] 395 [ exception ID (32-bit unsigned), if any ] 396 [ explicit output parameter values, if any, padded to 4 byte boundary ] 398 5.4. `InitializeConnection' Message 399 ==================================== 401 InitializeConnection header (pseudo-C): 403 typedef struct { 404 Boolean control_msg : 1; /* == TRUE */ 405 ControlMsgType msg_type : 3; /* == InitializeConnection */ 406 Unused verify_1 : 4; 407 ProtocolVersion version : 8; /* what version of the protocol? */ 408 unsigned objgroup_id_len : 16; /* length of object group ID */ 409 } InitializeConnectionMsgHeader; 411 The actual message consists of the following fields: 413 [ `InitializeConnectionMsgHeader' ] 414 [ `objgroup_id_len'-length object group ID for supposed callee, padded 415 to 4-byte boundary ] 416 This message is sent from caller to callee as the first message of the 417 connection. It is used to pass the object group ID of the connection 418 from client to server, so that both sides understand what the omitted 419 prefix portion of discriminant IDs is. If the object group ID received 420 by the callee is not the correct object group ID for the callee (i.e., 421 the callee has objects which do not have that prefix in their object 422 IDs), the callee should terminate the connection, with the appropriate 423 reason. The object group ID is passed as an XDR `fixed-length opaque 424 data' value of the length specified in `objgroup_id_len'. 426 5.5. `TerminateConnection' Message 427 =================================== 429 TerminateConnection header (pseudo-C): 431 typedef struct { 432 Boolean control_msg : 1; /* == TRUE */ 433 ControlMsgType msg_type : 3; /* == TerminateConnection */ 434 TerminationCause cause: 4; /* why connection terminated */ 435 unsigned serial_no : 24; /* last request processed/sent */ 436 } TerminateConnectionMsgHeader; 438 The actual message consists simply of the header; it provides for 439 graceful connection shutdown. It is sent either from the caller to the 440 callee, or from the callee to the caller, and informs the other party 441 that it is cancelling the connection, for one of these reasons: 442 1. A badly formatted message has arrived from the other party, and 443 protocol sychronization is believe lost, or, the caller has sent a 444 `InitializeConnection' message with the wrong major version for 445 the protocol; 447 2. This party (process, thread, whatever) is going away, and the 448 other party should not attempt to reconnect to it; 450 3. This connection is being terminated due to active resource 451 management; the other party should attempt to reconnect if it 452 needs to - this reason is typically only useful from callee to 453 caller; 455 4. The caller has sent a `InitializeConnection' message with the 456 wrong object group ID; 458 5. The caller has used the maximum serial number available for this 459 connection. 461 The `serial_no' field contains the serial number of the last message 462 completely processed by the caller (when `TerminateConnection' is sent 463 from caller to callee), or the serial number of the last message sent 464 by the callee (when sent from callee to caller). No further messages 465 should be sent on the connection by a sender of a `TerminateConnection' 466 message after it has been sent, or by a receiver of 467 `TerminateConnection' messsage after it has been received. 469 5.6. `DefaultCharset' Message 470 ============================== 472 DefaultCharset header (pseudo-C): 474 typedef struct { 475 Boolean control_msg : 1; /* == TRUE */ 476 ControlMsgType msg_type : 3; /* == DefaultCharset */ 477 Unused bits_12: 12; /* unused */ 478 unsigned charset_mibenum : 16; /* default charset */ 479 } DefaultCharsetMsgHeader; 481 This message is sent by either side of a connection to establish a 482 default charset for subsequent messages sent by that side of the 483 connection. The charset defines how string values are marshalled as 484 octet sequences. The default charset defines the default marshalling, 485 unless overridden by an explicit charset in a string value. Each side 486 of the connection may establish a default charset independently of the 487 other side of the connection; the default charset only applies to string 488 values in messages coming from that side. A new value of the default 489 charset may be established at any time by sending another 490 `DefaultCharset' message. 492 6. Data Marshalling 493 ******************** 495 This section defines how values of the type specified in the HTTP-ng 496 type system [HTTP-ng-arch] are marshalled into a Request or Reply 497 message. 499 The data value format used for parameters is the XDR format 500 specified in [RFC 1832]. However, we extend the XDR specification with 501 one additional type, called "flagged variable-length opaque data". It 502 is similar to XDR's regular variable-length opaque data, except that 503 the high-order bit of the length field is used as a flag bit, instead 504 of being part of the length. This means that flagged variable-length 505 opaque data can only carry opaque data of lengths less than or equal to 506 (2**31)-1. 507 0 1 2 3 4 5 ... 508 ++----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ 509 flag -->|| length n |byte0|byte1|...| n-1 | 0 |...| 0 | 510 bit ++----+-----+-----+-----+-----+-----+...+-----+-----+...+-----+ 511 ||<------31 bits------->|<------n bytes------>|<---r bytes--->| 512 |<----n+r (where (n+r) mod 4 = 0)---->| 513 FLAGGED VARIABLE-LENGTH OPAQUE 515 6.1. Boolean Type 516 ================== 518 Values of type `BOOLEAN' are passed as XDR `bool'. 520 6.2. Enumeration Types 521 ======================= 523 Values of enumeration types are passed as XDR `enum'. Each 524 enumeration value is assigned its ordinal value as it appears in the 525 declaration of the enumeration type, starting with the value `one'. 527 6.3. Numeric Types 528 =================== 530 7.3.1. Fixed-point Types 531 ------------------------- 533 Values of fixed-point types are passed by passing the value of the 534 numerator. We define a number of special cases for efficient 535 marshalling of common integer types, as well as a general case for 536 passing values of fixed-point types that are not covered by the special 537 cases. 539 Special cases: 540 * 32-bit integer: Fixed-point values with a minimum-numerator value 541 greater than or equal to -2147483648 and with a minimum numerator 542 value less than or equal to 2147483647 are passed as XDR `integer'. 544 * 32-bit unsigned integer: Fixed-point values with a 545 minimum-numerator value greater than or equal to 0 and with a 546 maximum numerator less than or equal to 4294967295 are passed as 547 XDR `unsigned integer'. 549 * 64-bit integer: Fixed-point values with a with a minimum 550 numerator value greater than or equal to -9223372036854775808 and 551 with a maximum numerator less than or equal to 552 9223372036854775807are passed as XDR `hyper integer'. 554 * 64-bit unsigned integer: Fixed-point values with a 555 minimum-numerator value greater than or equal to 0 and with a 556 maximum numerator value less than or equal to 18446744073709551615 557 are passed as XDR `unsigned hyper integer'. 559 General case: 561 The numerator of the value is passed as XDR `flagged variable-length 562 opaque data', with the bytes of the data containing the value expressed 563 as a base-256 number, in big-endian order; that is, with the most 564 significant digit of the value first. The flag bit is used to carry 565 the sign; the flag bit is 0 for a positive number or zero, and 1 for a 566 negative number. 568 7.3.2. Floating-point Types 569 ---------------------------- 571 We define a number of special cases for efficient marshalling of 572 common floating-point types, as well as a general case for passing 573 values of floating-point types that are not covered by the special 574 cases. 576 Special cases: 577 * IEEE single: floating point types matching the IEEE 32-bit 578 floating-point format (that is, with the parameters 579 significand-size=24, exponent-base=2, maximum-exponent-value=127, 580 minimum-exponent-value=-126, has-Not-A-Number=TRUE, 581 has-Infinity=TRUE, denormalized-value-allowed=TRUE, and 582 has-signed-zero=TRUE) are passed as XDR `floating-point'. 584 * IEEE double: floating point types matching the IEEE 64-bit 585 floating-point format (that is, with the parameters 586 significand-size=53, exponent-base=2, maximum-exponent-value=1023, 587 minimum-exponent-value=-1022, has-Not-A-Number=TRUE, 588 has-Infinity=TRUE, denormalized-value-allowed=TRUE, and 589 has-signed-zero=TRUE) are passed as XDR `double-precision 590 floating-point'. 592 * Intel extended double: floating point types matching the Intel 593 IEEE floating-point-compliant extended double floating-point 594 format (that is, with the parameters significand-size=64, 595 exponent-base=2, maximum-exponent-value=16383, 596 minimum-exponent-value=-16382, has-Not-A-Number=TRUE, 597 has-Infinity=TRUE, denormalized-value-allowed=TRUE, and 598 has-signed-zero=TRUE), are passed as a 12-byte value of XDR 599 `fixed-length opaque data', containing the floating-point value in 600 the format specified in the UNIX System V Application Binary 601 Interface Intel 386 Processor Supplement (Intel ABI) document: the 602 63 bits of the fraction occupy the first 7 bytes in little-endian 603 order plus the low seven bits of the eighth byte; the 1 bit 604 explicit leading significand bit occupies the high-order bit of 605 the eighth byte; the 15 bits of the exponent occupy the ninth byte 606 and the low-order bits of the tenth byte, in little-endian order; 607 the sign bit occupies the high-order bit of the tenth byte; the 608 eleventh and twelfth bytes are unused, and should contain zero 609 values. 611 * SPARC & PowerPC extended double: floating point types matching 612 the XDR quadruple-precision floating-point format (that is, with 613 the parameters significand-size=113, exponent-base=2, 614 maximum-exponent-value=16383, minimum-exponent-value=-16382, 615 has-Not-A-Number=TRUE, has-Infinity=TRUE, 616 denormalized-value-allowed=TRUE, and has-signed-zero=TRUE), which 617 is the form of extended double floating-point used by PowerPC and 618 SPARC processors, are passed as XDR `quadruple-precision 619 floating-point'. 621 General case: 623 Values of floating-point types not matching the special cases 624 identified above are passed as a value of the XDR struct type 625 `GeneralFloatingPointValue', which has the following definition: 626 /* XDR */ 627 enum { Normal = 1, NotANumber = 2, Infinity = 3 } FloatingPointValueType; 628 struct { 629 flagged opaque FixedPointSignAndSignificand<>; 630 flagged opaque FixedPointExponent<>; 631 } NormalFloatingPointValue; 632 union switch (FloatingPointValueType disc) { 633 case Normal: NormalFloatingPointValue value; 634 case NotANumber: void; 635 case Infinity: void; 636 } GeneralFloatingPointValue; 638 The two fields of the `NormalFloatingPointValue' struct each contain 639 an on-the-wire representation of a fixed-point value of the fixed-point 640 type (denominator=1, no-mininum-numerator, no-maximum-numerator). The 641 `FixedPointSignAndSignificand' field contains the sign of the 642 floating-point value as the sign, and the actual significand as the 643 absolute value of the fixed-point value. The `FixedPointExponent' field 644 contains the exponent of the floating-point value. 646 6.4. String Types 647 ================== 649 Each string value sent in this protocol has a "charset" [RFC 2278] 650 associated with it, identified by the charset's IANA-assigned MIBEnum 651 value. Each side of a session may establish a "default charset" by 652 sending the `DefaultCharset' message. String values that use the 653 default character set do not contain explicit charset information; 654 string values that use a charset other than the default charset contain 655 the MIBEnum value for the charset, along with the bytes of the string. 657 We send a string value as a value of XDR `flagged variable-length 658 opaque data'. If the flag bit is 1, the first two bytes of the string 659 value are the MIBEnum of the charset, high-order byte first; the 660 remaining bytes are the bytes of the string. If the flag bit is 0, the 661 bytes of opaque data simply contain the bytes of the string; the 662 charset is the default charset for the session. It is a marshalling 663 error to send a string value with a flag bit of 0 over a session for 664 which no default charset has been established. To avoid 665 context-sensitivity in marshalling a string, it is always valid to 666 marshal a string with an explicit charset value, even if the charset 667 value is the same as the default charset for the session. When 668 marshalling a string into a pickle, the charset should always be 669 explicitly included. 671 6.5. Sequence Types 672 ==================== 674 Values of sequence types are passed as XDR `variable-length arrays', 675 with one exception: Sequences of any fixed-point type with a minimum 676 numerator greater than or equal to 0, and a maximum numerator less than 677 or equal to 255, are passed as XDR `variable-length opaque data', with 678 one numerator value per octet. 680 6.6. Array Types 681 ================= 683 Values of array types are passed as XDR `fixed-length arrays', with 684 one exception: Arrays of any fixed-point type with a minimum numerator 685 greater than or equal to 0, and a maximum numerator less than or equal 686 to 255, are passed as XDR `fixed-length opaque data', with one 687 numerator value per octet. Values of array types are passed as XDR 688 `fixed-length arrays', with one exception: 690 6.7. Record Types 691 ================== 693 Values of record types are passed as XDR `struct'. 695 6.8. Union Types 696 ================= 698 Values of union types are passed as XDR `union', with the union 699 discriminant being the zero-based ordinal value for the encapsulated 700 value's type. 702 6.9. Pickle Type 703 ================= 705 A pickle is passed as an XDR `variable-length opaque data', 706 containing the type ID of the pickled value's type, followed by the 707 XDR-marshalled pickled value. To save pickle space for common value 708 types used in metadata, we define a packed format for the type ID 709 marshalling. A type ID is marshalled into a pickle as a 32-bit header, 710 in an XDR `unsigned integer', possibly followed by an XDR `fixed-length 711 opaque data', containing the string form of the type ID of the pickled 712 type. The header has the following internal structure: 713 /* Pseudo-C */ 714 typedef struct { 715 unsigned version : 8; 716 PickleTypeKind type_kind : 8; 717 unsigned type_id_len : 16; 718 } TypeIDHeader; 720 The `version' field gives the version number of the pickle format; the 721 `type_kind' field contains a value from the enum 722 /* Pseudo-C */ 723 typedef enum { 724 TypeKind_unconstrained = 0, /* anything not covered by other type kinds... */ 725 TypeKind_boolean = 1, /* BOOLEAN */ 726 TypeKind_s8 = 2, /* FIXED-POINT DENOM=1 MIN-NUM=-128 MAX-NUM=127 */ 727 TypeKind_s16 = 3, /* FIXED-POINT DENOM=1 MIN-NUM=-32768 MAX-NUM=32767 */ 728 TypeKind_s32 = 4, /* FIXED-POINT DENOM=1 MIN-NUM=-2147483648 MAX-NUM=2147483647 */ 729 TypeKind_s64 = 5, /* FIXED-POINT DENOM=1 MIN-NUM=-9223372036854775808 730 MAX-NUM=9223372036854775807 */ 731 TypeKind_u8 = 6, /* FIXED-POINT DENOM=1 MIN-NUM=0 MAX-NUM=255 */ 732 TypeKind_u16 = 7, /* FIXED-POINT DENOM=1 MIN-NUM=0 MAX-NUM=65535 */ 733 TypeKind_u32 = 8, /* FIXED-POINT DENOM=1 MIN-NUM=0 MAX-NUM=4294967296 */ 734 TypeKind_u64 = 9, /* FIXED-POINT DENOM=1 MIN-NUM=0 MAX-NUM=18446744073709551616 */ 735 TypeKind_ieee_float32 = 10, /* FLOATING-POINT SIGNIFICAND-SIZE=24 EXPONENT-BASE=2 736 MAXIMUM-EXPONENT-VALUE=127 MINIMUM-EXPONENT-VALUE=-126 737 HAS-NOT-A-NUMBER=TRUE HAS-INFINITY=TRUE 738 DENORMALIZED-VALUE-ALLOWED=TRUE HAS-SIGNED-ZERO=TRUE */ 739 TypeKind_ieee_float64 = 11, /* FLOATING-POINT SIGNIFICAND-SIZE=53 EXPONENT-BASE=2 740 MAXIMUM-EXPONENT-VALUE=1023 MINIMUM-EXPONENT-VALUE=-1022, 741 HAS-NOT-A-NUMBER=TRUE HAS-INFINITY=TRUE 742 DENORMALIZED-VALUE-ALLOWED=TRUE HAS-SIGNED-ZERO=TRUE */ 743 TypeKind_i_default_str = 12, /* STRING LANGUAGE="i-default" */ 744 TypeKind_object = 13, /* local or remote object */ 745 ... 746 /* other types like Date, etc, should be added here... */ 747 ... 748 } PickleTypeKind; 750 If the value of `type_kind' is `TypeKind_unconstrained', the value of 751 `type_kind_len' is the length of a value of XDR type `fixed-length 752 opaque data', containing the full string type ID of the type, which 753 immediately follows the header. Otherwise, no `opaque data' is 754 marshalled. 756 For the purposes of marshalling, pickles have no default charset; 757 this means that strings marshalled into a pickle should always contain 758 an explicit charset. Pickles should be considered a single "message" 759 for the purposes of marshalling aliased reference types. 761 6.10. Reference Types 762 ====================== 764 6.10.1. Optional Types 765 ----------------------- 767 Optional types are passed as XDR `optional-data'. 769 6.10.2. Aliased Types 770 ---------------------- 772 The scope of aliasing in this protocol is the message, as in Java 773 RMI, rather than the call, as in DCE RPC. That is, aliasing occurs 774 only within the context of a single invocation or result, rather than 775 across a full invocation-result pair. For the purposes of marshalling, 776 a pickle scope should be considered a single message scope. 778 Each unique value of an aliased type that is marshalled is assigned 779 a 32-bit unsigned integer value, unique in the scope of aliasing, 780 called its "aliased identifier". This identifier is marshalled as an 781 XDR `unsigned integer'. If the aliased value has not previously been 782 sent in this scope, its value is then marshalled as a value of its base 783 type would be. Note that this means that the full value of every 784 aliased type is sent only once in a scope; subsequent occurrences send 785 only the aliased identifier. 787 [ XXX - how to handle overflow of aliased value cache? ] 789 6.11. Object Types 790 =================== 792 An instance of an object type is passed as the state of the object 793 type, which also contains information about the actual type of the 794 value. For remote object types, this state is followed by the object 795 identifier, and optionally information about how the instance may be 796 contacted. 798 6.11.1. Parameter Type Versus Actual Type 799 ------------------------------------------ 801 When marshalling the state of an object, it's important to 802 distinguish two important types of the value: the "parameter type", 803 which is the type that both sides of the session expect the value to 804 have, and the "actual type" of the value, which is the most-derived 805 type of the object, and may be a subtype of the parameter type. If the 806 actual type is different from the parameter type, extra information 807 must be passed along with the value to allow the receiver to properly 808 distinguish the type and its associated data. However, if the actual 809 type is the same as the parameter type, some of this information can be 810 omitted. 812 6.11.2. Passing the Actual Type Information 813 -------------------------------------------- 815 We try to pass the type information of the object type as the type 816 ID of the most-derived-type of the object. However, for proper 817 unmarshalling of local object types, we also need to pass additional 818 type IDs. Type information is thus passed according to the following 819 rules: 820 1. If the parameter type of the object is sealed, both sides already 821 know the most-derived-type ID of the instance, and know that the 822 actual type must be the same as the parameter type. In this case, 823 the type ID is passed as XDR `void'. 825 2. Otherwise, type information is passed as a value of the following 826 XDR union type `GeneralTypeInformation': 827 /* XDR */ 828 enum { FormalType = 1, RemoteMSTID = 2, LocalTypeTree = 3 } 829 ObjectTypeInformation; 830 union switch (ObjectTypeInformation disc) { 831 case FormalType: void; /* passed implicitly */ 832 case RemoteMSTID: opaque<0xFFFF>; /* contains mdt type ID */ 833 case LocalTypeTree: VALUE OF HTTP-NG.TYPEIDTREENODEREF; 834 /* full inheritance tree */ 835 } GeneralTypeInformation; 837 That is: 838 1. If the actual type of the object is the same as the parameter 839 type, again both sides know it, and the type information is 840 passed implicitly. 842 2. If the object type inherits from `HTTP-ng.RemoteObjectBase', 843 the type ID of the most-derived type of the object is passed 844 as a value of XDR `variable-length opaque data' containing 845 the type ID. 847 3. If the object type does not inherit from 848 `HTTP-ng.RemoteObjectBase', and is thus a local object type, 849 the full type inheritance hierarchy of the type is passed as 850 a value of `HTTP-ng.TypeIDTreeNodeRef'. 852 6.11.3. Passing the State Attributes 853 ------------------------------------- 855 The state attributes are marshalled in one of two ways: 856 1. If the actual type of the instance is the same as the parameter 857 type, the state of each of the types of the object are passed by 858 walking the supertype inheritance tree of the instance in a 859 depth-first order, passing the value of each attribute of any 860 particular state in the order in which they are defined, as if 861 each state formed an XDR `structure' with the attributes as the 862 components of the structure. The value of each attribute is 863 marshalled directly according to the type of the attribute. 865 2. If the actual type of the instance is a subtype of the parameter 866 type, the receiver has to be able to handle state for types it has 867 no knowledge of. To allow for this, the state of each type is 868 passed as an encapsulation. That is, the state of the instance is 869 passed as a sequence of XDR `structure' values, each containing the 870 state for one of the types of the instance. Types of the instance 871 which have no associated state do not appear in this sequence. An 872 XDR expression of the sequence would be the following: 873 /* XDR */ 874 struct { 875 opaque type_id<0xFFFF>; 876 opaque state<>; 877 } TypeState; 878 typedef TypeState StateSequence<>; 880 The type_id field contains the type ID for that type of the the 881 object value. The variable-length opaque data field state 882 contains the values of the attributes of the state marshalled as 883 an XDR `structure', where the components of the structure are the 884 attributes of the state. 886 6.11.4. Passing the Object ID and Contact Info 887 ----------------------------------------------- 889 In the case of a remote object type, the object group ID, instance 890 handle and contact info for the value are passed as a value of the 891 following XDR structure type `RemoteObjectInfo': 892 /* XDR */ 893 typedef string ContactInfo<0xFFFF>; 894 struct { 895 opaque objgroup_id<>; 896 opaque instance_handle<>; 897 ContactInfo cinfos<>; 898 } RemoteObjectInfo; 900 where objgroup_id is a identifier for the server which supports the 901 desired object, and instance_handle is a server-relative name for the 902 object. The cinfos field contains zero or more pieces of information 903 about the way in which the object needs to be contacted, including 904 information such as whether various transport layers are involved. 906 6.11.5. Syntax of Cinfo Strings 907 -------------------------------- 909 [Note: this cinfo syntax is poorly defined. An extensible more 910 conventionally URI-based scheme should replace this at some point. ] 912 Each cinfo string has the form described below (where brackets 913 indicate optionality, an is an identifier composed of 914 ASCII lowercase alphabetic and numeric characters, beginning with a 915 lowercase alphabetic character, and a is any 916 string of ASCII characters not containing the underscore character '_'): 918 := '@' 920 := [ '_' ] 922 := 924 := [ '_' ] 926 := 928 := [ '=' ] 930 := [ '_' ] 932 * 6.11.5.1. Syntax of `w3ng' Pinfo 934 The current syntax of the pinfo string for the `w3ng' wire 935 protocol is 937 := 'w3ng' 939 := [ '.' ] 941 where `' and `' are numbers between 942 0 and 15. If the `' is not specified, it defaults 943 to 0. 945 * 6.11.5.2. Syntax of `w3mux' Tinfo 947 The current syntax of the tinfo string for the `w3mux' transport 948 layer is 950 := 'w3mux' 952 := '_' 954 where `' is a protocol ID number [MUX], and `' 955 is a UUID string for an endpoint. The size of the `' 956 string must be less than 1000 bytes. 958 * 6.11.5.3. Syntax of `tcp' Tinfo 960 The current syntax of the tinfo string for the `tcp' transport 961 layer is 963 := 'tcp' 965 := '_' 967 where `' is string of less than 1000 bytes indicating the IP 968 address or hostname of the remote machine, and `' is the TCP 969 port on which the host is listening. 971 7. Connection Exceptions 972 ************************* 974 We define a number of exceptions, as defined in [HTTP-ng-arch], 975 which may be signalled `across the wire' (between compatibility 976 domains) as a result of any operation invocation, and are called 977 "connection exceptions". Each connection exception has a specified 978 "exception code", and may also have output parameters associated with 979 it. This set of exceptions may not be the same as the set of system 980 exceptions built into any implementation of the HTTP-ng architecture; 981 the implementation is responsible for mapping from its internal set of 982 exceptions to that supported by the wire protocol. 984 7.1. `UnknownProblem' 985 ====================== 987 Exception code: 0 988 Output parameters: None 990 An unknown problem occurred. 992 7.2. `ImplementationLimit' 993 =========================== 995 Exception code: 1 996 Output parameters: None 998 The request could not be properly addressed because of some 999 implementation resource limit on the callee side. 1001 7.3. `SwitchConnectionCinfo' 1002 ============================= 1004 Exception code: 2 1005 Output parameters: NEW-CINFO : value of a string type with language 1006 "i-default" 1008 This exception requests the caller to upgrade the connection 1009 protocol and transport information to the cinfo specified as the 1010 argument, and re-try the call. This is the equivalent of the `UPGRADE' 1011 message in HTTP 1.1, and the `RELOCATE_REPLY' message in CORBA GIOP. 1013 7.4. `Marshal' 1014 =============== 1016 Exception code: 3 1017 Output parameters: None 1019 A marshalling problem was encountered. 1021 7.5. `NoSuchObjectType' 1022 ======================== 1024 Exception code: 4 1025 Output parameters: None 1027 The object type of the operation was unknown at the server. 1029 7.6. `NoSuchMethod' 1030 ==================== 1032 Exception code: 5 1033 Output parameters: None 1035 The object type of the operation was known at the server, but did 1036 not contain the indicated method. 1038 7.7. `NoSuchObject' 1039 ==================== 1041 Exception code: 6 1042 Output parameters: None 1044 The specified discriminant object was not available at the server. 1046 7.8. `InvalidType' 1047 =================== 1049 Exception code: 7 1050 Output parameters: None 1052 The object specified by the discriminant did not participate in the 1053 type specified in the operation. 1055 7.9. `Rejected' 1056 ================ 1058 Exception code: 8 1059 Output parameters: REASON : value of a string type with language 1060 "i-default" 1062 The server refused to process the request. It may return a string 1063 giving a reason for the rejection. 1065 7.10. `OperationOrDiscriminantCacheOverflow' 1066 ============================================= 1068 Exception code: 9 1069 Output parameters: None 1071 The request caused the receiver's cache of operations or 1072 discriminants to overflow. The sender may retry the request with 1073 uncached operation and discriminant values; subsequent requests should 1074 not cache any additional operation or discriminant values, but may 1075 continue to use previously successfully cached values. 1077 8. Security 1078 ************ 1080 This protocol assumes that security provisions are made either at 1081 some level above it, typically in the application interfaces, or at 1082 some level below it, typically by use of a secure transport mechanism. 1083 It contains no protocol-level mechanisms for providing or assuring any 1084 of the concerns normally related to security. 1086 9. References 1087 ************** 1089 [HTTP-ng-arch]: HTTP-ng Architecture Model. (See 1090 `http://www.w3.org/TR/WD-HTTP-NG-architecture'.) 1092 [HTTP-ng-goals]: HTTP-ng Short- and Long-term Goals. (See 1093 `http://www.w3.org/TR/WD-http-ng-goals'.) 1095 [HTTP-ng-webmux]: HTTP-ng WEBMUX Protocol Specification. (See 1096 `http://www.w3.org/TR/WD-mux'.) 1098 [RFC 1831]: RFC 1831, RPC: Remote Procedure Call Protocol 1099 Specification Version 2; R. Srinivasan, August 1995. (See 1100 `http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1831.txt'.) 1102 [RFC 1832]: RFC 1832, XDR: External Data Representation Standard; R. 1103 Srinivasan, August 1995. (See 1104 `http://info.internet.isi.edu:80/in-notes/rfc/files/rfc1832.txt'.) 1106 [RFC 2277] RFC 2277, IETF Policy on Character Sets and Languages; H. 1107 Alvestrand, January 1998. (See 1108 `http://info.internet.isi.edu:80/in-notes/rfc/files/rfc2277.txt'.) 1110 [RFC 2278] RFC 2278, IANA Charset Registration Procedures; N. Freed & 1111 J. Postel, January 1998. (See 1112 `http://info.internet.isi.edu:80/in-notes/rfc/files/rfc2278.txt'.) 1114 10. Address of Author 1115 ********************** 1117 Bill Janssen 1118 Mail: Xerox Palo Alto Research Center 1119 3333 Coyote Hill Rd 1120 Palo Alto, CA 94304 1121 Phone: (650) 812-4763 1122 FAX: (650) 812-4777 1123 Email: janssen@parc.xerox.com 1124 HTTP: http://www.parc.xerox.com/istl/members/janssen/