From 14b63ae11e0a7c3d028ec4ff6e4532705a800157 Mon Sep 17 00:00:00 2001 From: Anders Svensson Date: Fri, 20 May 2011 12:34:22 +0200 Subject: Various documentation fixes and improvements. Added an introductory chapter to the User's Guide as well as more detailed release notes. --- lib/diameter/doc/src/diameter.xml | 121 +++++++++++------- lib/diameter/doc/src/diameter_app.xml | 182 ++++++++++++++++------------ lib/diameter/doc/src/diameter_dict.xml | 67 +++++----- lib/diameter/doc/src/diameter_examples.xml | 5 + lib/diameter/doc/src/diameter_intro.xml | 58 ++++++++- lib/diameter/doc/src/diameter_transport.xml | 2 +- lib/diameter/doc/src/diameter_using.xml | 3 + lib/diameter/doc/src/notes.xml | 59 ++++++++- 8 files changed, 338 insertions(+), 159 deletions(-) (limited to 'lib') diff --git a/lib/diameter/doc/src/diameter.xml b/lib/diameter/doc/src/diameter.xml index 9774183a2a..36b6cbf0cf 100644 --- a/lib/diameter/doc/src/diameter.xml +++ b/lib/diameter/doc/src/diameter.xml @@ -415,6 +415,12 @@ eval(F) -> Evaluating an evaluable() E on an argument list A is meant in the sense of eval([E|A]).

+

+Beware of using local funs (that is, fun expressions not of the +form fun Module:Name/Arity) in situations in which the fun is +not short-lived and code is to be upgraded at runtime since any +processes retaining such a fun will have a reference to old code.

+ @@ -712,7 +718,7 @@ transport.

Unrecognized options are silently ignored but are returned unmodified by service_info/1,2 and can be referred to +marker="#service_info">service_info/2 and can be referred to in predicate functions passed to remove_transport/2.

@@ -739,7 +745,9 @@ marker="#remove_transport">remove_transport/2.

-Add transport capability to a service. +Add transport capability to a service.

+ +

The service will start a transport process(es) in order to establish a connection with the peer, either by connecting to the peer (connect) or by accepting incoming connection requests @@ -761,10 +769,8 @@ handling of DWR/DWA and required by RFC 3539 as well as for DPR/DPA.

The returned reference uniquely identifies the transport within the scope of the service. -Not that the function returns before a transport connection has been -established.

- -

+Note that the function returns before a transport connection has been +established. It is not an error to add a transport to a service that has not yet been configured: a service can be started after configuring transports.

@@ -776,7 +782,7 @@ transports.

-call(SvcName, App, Request, Options) -> Answer | {error, Reason} +call(SvcName, App, Request, Options) -> ok | Answer | {error, Reason} Send a Diameter request message. SvcName = service_name() @@ -794,15 +800,19 @@ Send a Diameter request message and possibly return the answer or error.

defined and callbacks to the corresponding callback module will follow as described below and in diameter_app(3). -The call returns either when an answer message is received from the -peer or an error occurs, unless the detach option has been -specified. -If detach is not specified then the form of an Answer is -as returned from a handle_answer/4 or +Unless the detach option has been specified to cause an earlier +return, the call returns either when an answer message is received +from the peer or an error occurs. +In the case of an answer, the return value is as returned by a handle_answer/4 +callback. +In the case of an error, whether or not the error is returned directly +by diameter or from a handle_error/4 -callback.

+callback depends on whether or not the outgoing request is +successfully encoded for transmission from the peer, the cases being +documented below.

If there are no suitable peers, or if @@ -888,7 +898,8 @@ attempt to send the request over the transport.

Note that {error, encode} is the only return value which -guarantees that the request has not been sent over the transport.

+guarantees that the request has not been sent over the +transport.

 @@ -902,9 +913,11 @@ guarantees that the request has not been sent over the transport.

Return a reasonable value for use as Origin-State-Id in -outgoing messages. -The value returned is the number of seconds since 19680120T031408Z -(the first value that can be encoded as a Time()) +outgoing messages.

+ +

+The value returned is the number of seconds since 19680120T031408Z, +the first value that can be encoded as a Diameter Time(), at the time the diameter application was started.

@@ -959,25 +972,7 @@ DPA or timeout.

- - - - - - - -service_info(SvcName) -> Info -Return information about a started service. - -SvcName = service_name() -Info = [{Item, Value}] - - -

-Return information about a started service. -Equivalent to service_info(SvcName, all).

- - + @@ -992,7 +987,7 @@ Equivalent to service_info(SvcName, all).

-Return specific information about a started service.

+Return information about a started service.

 @@ -1018,17 +1013,36 @@ Return the list of started services.

session_id(Ident) -> OctetString() -Return a value for a Session-Id AVP +Return a value for a Session-Id AVP. Ident = DiameterIdentity()

-Return a value for a Session-Id AVP. +Return a value for a Session-Id AVP.

+ +

The value has the form required by section 8.8 of RFC 3588. Ident should be the Origin-Host of the peer from which the message containing the returned value will be sent.

+ + + + + + +start() -> ok | {error, Reason} +Start the diameter application. + +

+Start the diameter application.

+ +

+The diameter application must be started before starting a service. +In a production system this will typically be accomplished by a boot +file, not by calling start/0 explicitly.

+ @@ -1036,7 +1050,7 @@ the message containing the returned value will be sent.

start_service(SvcName, Options) -> ok | {error, Reason} -Start a Diameter service +Start a Diameter service. SvcName = service_name() Options = [service_opt()] @@ -1044,7 +1058,9 @@ the message containing the returned value will be sent.

-Start a diameter service. +Start a diameter service.

+ +

A service defines a locally-implemented Diameter peer, specifying the capabilities of the peer to be used during capabilities exchange and the Diameter applications that it supports. @@ -1055,10 +1071,25 @@ marker="#add_transport">add_transport/2.

 + + +stop() -> ok | {error, Reason} +Stop the diameter application. + +

+Stop the diameter application.

+ +

+

+ + + + + stop_service(SvcName) -> ok | {error, Reason} -Stops a Diameter service. +Stop a Diameter service. SvcName = service_name() Reason = term() @@ -1075,7 +1106,7 @@ Stop a diameter service.

subscribe(SvcName) -> true -Subscribe to event messages from a service. +Subscribe to event messages. SvcName = service_name() @@ -1095,7 +1126,7 @@ that does not yet exist.

unsubscribe(SvcName) -> true - +Unsubscribe to event messages. SvcName = service_name() diff --git a/lib/diameter/doc/src/diameter_app.xml b/lib/diameter/doc/src/diameter_app.xml index d78882c18d..fc359b9d1d 100644 --- a/lib/diameter/doc/src/diameter_app.xml +++ b/lib/diameter/doc/src/diameter_app.xml @@ -47,23 +47,12 @@ configures one of more Diameter applications, each of whose configuration specifies a callback that handles messages specific to its application. The messages and AVPs of the Diameter application are defined in a -specification file whose format is documented in +dictionary file whose format is documented in diameter_dict(4) while the callback module is documented here. The callback module implements the Diameter application-specific functionality of a service.

- -

-The arities of the callback functions below assume no extra arguments. -All functions will also be passed any extra arguments configured with -the callback module itself when calling diameter:start_service/2 -and, except for peer_up, peer_down and handle_request, any extra -arguments passed to diameter:call/4.

- -

A callback module must export all of the functions documented below. The functions themselves are of three distinct flavours:

@@ -72,8 +61,8 @@ The functions themselves are of three distinct flavours:

peer_up/3 and -peer_down/3 signal the attainment -or loss of communicativity with a Diameter peer.

+peer_down/3 signal the +attainment or loss of connectivity with a Diameter peer.

 @@ -98,6 +87,17 @@ is called in response to an incoming Diameter request message.

+ +

+The arities given for the the callback functions here assume no extra +arguments. +All functions will also be passed any extra arguments configured with +the callback module itself when calling diameter:start_service/2 +and, for the call-specific callbacks, any extra arguments passed to +diameter:call/4.

+ + @@ -131,8 +131,8 @@ a message as defined in a dictionary file is encoded as a record with one field for each component AVP. Equivalently, a message can also be encoded as a list whose head is the atom-valued message name (the record name minus any -prefix in the dictionary file) and whose tail is a list of -{FieldName, FieldValue} pairs.

+prefix specified in the relevant dictionary file) and whose tail is a +list of {FieldName, FieldValue} pairs.

A third representation allows a message to be specified as a list @@ -144,7 +144,8 @@ as directed by the return value of a callback. It differs from the other other two in that it bypasses the checks for messages that do not agree with their definitions in the dictionary in -question: messages are sent exactly as specified.

+question (since relays agents must handle arbitrary request): messages +are sent exactly as specified.

 @@ -153,8 +154,8 @@ question: messages are sent exactly as specified.

A container for incoming and outgoing Diameters message that's passed through encode/decode and transport. -Defined in diameter.hrl. -Fields should not be altered except as documented.

+Fields of a packet() record should not be set in return values except +as documented.

peer_ref() = term() @@ -243,11 +244,11 @@ call to peer_up/3.

 -Mod:pick_peer(Cands, Reserved, SvcName, State) +Mod:pick_peer(Candidates, Reserved, SvcName, State) -> {ok, Peer} | {Peer, NewState} | false Select a target peer for an outgoing request. -Cands = [Peer] +Candidates = [peer()] Peer = peer() | false SvcName = service_name() State = NewState = state() @@ -266,11 +267,9 @@ marker="diameter#start_service">diameter:start_service/2.

The candidate peers list will only include those which are selected by any filter option specified in the call to -diameter:call/4.

- +diameter:call/4, and only +those which have indicated support for the Diameter application in +question.

The return values false and {false, State} are @@ -326,13 +325,14 @@ A returned packet() should set the request to be encoded in its to pass information to the transport module. Extra arguments passed to diameter:call/4 can be used to -communicate transport data to the callback.

- -

-Any returned packet() can set the header field to a +communicate transport data to the callback. +A returned packet() can also set the header field to a diameter_header record in order to specify values that should -be preserved in the outgoing request. -A specified message_length is ignored.

+be preserved in the outgoing request, although this should typically +not be necessary and allows the callback to set header values +inappropriately. +A returned length, cmd_code or application_id is +ignored.

Returning {discard, Reason} causes the request to be aborted @@ -361,7 +361,7 @@ Invoked to return a request for encoding and retransmission. Has the same role as prepare_request/3 in the case that a peer connection is lost an an alternate peer selected but the -Packet passed to prepare_retransmit/3 is as returned by +argument packet() is as returned by the initial prepare_request/3.

@@ -391,10 +391,12 @@ discarded}.

Invoked when an answer message is received from a peer. The return value is returned from the call to diameter:call/4 for which the -callback takes place.

+callback takes place unless the detach option was +specified.

-The decoded answer record is in the msg field of Packet, +The decoded answer record is in the msg field of the argument +packet(), the undecoded binary in the packet field. Request is the outgoing request message as was returned from prepare_request/3 or @@ -414,8 +416,10 @@ By default, an incoming answer message that cannot be successfully decoded causes the request process in question to fail, causing the relevant call to diameter:call/4 -to return {error, failure}. -There is no handle_error/4 callback in this case. +to return {error, failure} (unless the detach option was +specified). +In particular, there is no handle_error/4 callback in this +case. Application configuration may change this behaviour as described for diameter:start_service/2.

@@ -440,7 +444,8 @@ Invoked when an error occurs before an answer message is received from a peer in response to an outgoing request. The return value is returned from the call to diameter:call/4 for which the -callback takes place.

+callback takes place (unless the detach option was +specified).

Reason timeout indicates that an answer message has not been @@ -449,8 +454,7 @@ Reason failover indicates that the transport connection to the peer to which the request has been sent has been lost but that not alternate node was available, possibly because a pick_peer/4 -callback returned false. -

+callback returned false.

@@ -463,40 +467,33 @@ callback returned false. Packet = packet() SvcName = term() Peer = peer() -Action = Reply | NoReply | Relay | {eval, Action, ContF} +Action = Reply | {relay, Opts} | discard | {eval, Action, ContF} Reply = {reply, message()} - | {protocol_error, ResultCode} -NoReply = discard -Relay = {relay, Opts} -Opts = list() + | {protocol_error, 3000..3999} +Opts = diameter:call_opts() ContF = diameter:evaluable() -ResultCode = 3000..3999

-Invoked when a request message is received from a peer.

- -

+Invoked when a request message is received from a peer. The application in which the callback takes place (that is, the callback module as configured with diameter:start_service/2) is determined by the Application Identifier in the header of the -incoming Diameter request message, the selected module being the one +incoming request message, the selected module being the one whose corresponding dictionary declares -itself as defining the application in question, or the RFC 3588 relay -application if the specific application is unsupported but the relay -application has been advertised.

+itself as defining either the application in question or the Relay +application.

-The packet() in which the incoming request is communicated has the -following signature.

+The argument packet() has the following signature.

#diameter_packet{header = #diameter_header{}, avps = [#diameter_avp{}], msg = record() | undefined, - errors = [integer() | {integer(), #diameter_avp{}}], + errors = ['Unsigned32'() | {'Unsigned32'(), #diameter_avp{}}], bin = binary(), transport_data = term()} @@ -509,12 +506,16 @@ in diameter_dict(4).

-The errors field specifies any non-protocol errors that were -encountered in decoding the request and can be returned in a -reply tuple to have diameter set the Result-Code and Failed-AVP -AVP's appropriately. -The list is empty if the request has been received in the relay -application.

+The errors field specifies any Result-Code's identifying errors +that were encountered in decoding the request. +In this case diameter will set both Result-Code and +Failed-AVP AVP's in a returned +answer message() before sending it to the peer: +the returned message() need only set any other required AVP's. +Note that the errors detected by diameter are all of the 5xxx series +(Permanent Failures). +The errors list is empty if the request has been received in +the relay application.

The transport_data field contains an arbitrary term passed into @@ -525,34 +526,59 @@ sent back to the transport process unless another value is explicitly specified.

-The semantics of each of the possible return values are as follows. -(TODO: more.)

+The semantics of each of the possible return values are as follows.

-{reply, Answer} +{reply, message()}

Send the specified answer message to the peer.

 -{relay, Opts} +{protocol_error, 3000..3999}

-Relay a request to another peer.

- - -{protocol_error, ResultCode} - +Send an answer message to the peer containing the specified +protocol error. +Equivalent to

+ +{reply, ['answer-message' | Avps] +

-Send an answer message to the peer containing the specified 3xxx -protocol error.

+where Avps sets the Origin-Host, Origin-Realm, the specified +Result-Code and (if the request sent one) Session-Id AVP's.

-RFC 3588 mandates that only answers with a 3xxx series +Note that RFC 3588 mandates that only answers with a 3xxx series Result-Code (protocol errors) may set the E bit. -Returning a non-3xxx value in a {protocol_error, ResultCode} -tuple will cause the request process in question to fail.

+Returning a non-3xxx value in a protocol_error tuple +will cause the request process in question to fail.

+ + +{relay, Opts} + +

+Relay a request to another peer. +The appropriate Route-Record AVP will be added to the relayed request +by diameter and pick_peer/4 +and prepare_request/3 +callback will take place just as if diameter:call/4 had been called +explicitly. +However, returning a relay tuple also causes the End-to-End +Identifier to be preserved in the header of the relayed request as +required by RFC 3588.

+ +

+The returned Opts should not specify detach and +the handle_answer/4 +callback following from a relayed request must return its first +argument, the diameter_packet record containing the answer +message. +Note that the extra option can be specified to supply arguments +that can distinguish the relay case from others if so desired, +although the form of the request message may be sufficient.

 discard @@ -565,14 +591,14 @@ Discard the request.

Handle the request as if Action has been returned and then -evaluate the evaluable() ContF in the request process.

+evaluate ContF in the request process.

Note that diameter will respond to protocol errors in an incoming -request without invoking the a handle_request/3 callback.

+request without invoking handle_request/3.

 diff --git a/lib/diameter/doc/src/diameter_dict.xml b/lib/diameter/doc/src/diameter_dict.xml index 166c7a8c9d..a87f59bad5 100644 --- a/lib/diameter/doc/src/diameter_dict.xml +++ b/lib/diameter/doc/src/diameter_dict.xml @@ -48,37 +48,41 @@ to encode and decode its messages and AVP's. The dictionary module is in turn generated from a file that defines these messages and AVP's. The format of such a file is defined in -FILE FORMAT below.

+FILE FORMAT below. +Users add support for their specific applications by creating +dictionary files, compiling them to Erlang modules using +diameterc and configuring the +resulting dictionaries modules on a service.

-The codec generation also results in an hrl that defines records +The codec generation also results in a hrl file that defines records for the messages and grouped AVP's defined for the application, these -records being what a user of the diameter application sends and -receives. +records being what a user of the diameter application sends and receives. +(Modulo other available formats as discussed in diameter_app(3).) These records and the underlying Erlang data types corresponding to Diameter data formats are discussed in MESSAGE RECORDS and DATA TYPES respectively.

- - - - -

-The diameter application defines the base application of RFC 3588 in -the file diameter_gen_base_rfc3588.dia, and -this is the only application that diameter itself has any specific -knowledge of. -Other applications are callback modules configured for an application -as far as diameter is concerned.

- -

-A generated hrl also contains defines for the values of defined for +marker="#DATA_TYPES">DATA TYPES respectively. +The generated hrl also contains defines for the possible values of AVPs of type Enumerated.

-See diameterc for a -utility that transforms dictionary files into codec modules needed -at runtime.

+The diameter application includes three dictionary modules +corresponding to applications defined in section 2.4 of RFC 3588: +diameter_gen_base_rfc3588 for the Diameter Common Messages +application with application identifier 0, +diameter_gen_accounting for the Diameter Base Accounting +application with application identifier 3 and +diameter_gen_relaythe Relay application with application +identifier 0xFFFFFFFF. +The Common Message and Relay applications are the only applications +that diameter itself has any specific knowledge of. +The Common Message application is used for messages that diameter +itself handles: CER/CEA, DWR/DWA and DPR/DPA. +The Relay application is given special treatment with regard to +encode/decode since the messages and AVP's it handles are not specifically +defined.

@@ -89,7 +93,7 @@ at runtime.

FILE FORMAT

-A specification file consists of distinct sections. +A dictionary file consists of distinct sections. Each section starts with a line consisting of a tag followed by zero or more arguments. Each section ends at the the start of the next section or end of file. @@ -223,7 +227,7 @@ The section content is empty.

Can occur 0 or more times (with different values of Mod) but all dictionaries should typically inherit RFC3588 AVPs from -diameter_gen_base_rfc3588.

+diameter_gen_base_rfc3588.

Example:

@@ -263,7 +267,8 @@ Requested-Information 353 Enumerated V

Note that the P flag has been deprecated by the Diameter Maintenance -and Extensions Working Group of the IETF.

+and Extensions Working Group of the IETF: diameter will set the P flag +to 0 as mandated by the current draft standard.

@@ -446,7 +451,7 @@ as values of the types defined here. Values are passed to diameter:call/4 in a request record when sending a request, returned in a resulting -answer record and passed to a diameter_app(3) handle_request callback upon reception of an incoming request.

@@ -476,8 +481,8 @@ Grouped() = record()

On encode, an OctetString() can be specified as an iolist(), excessively large floats (in absolute value) are equivalent to -infinity or '-infinity' and excessively large integers result in -encode failure. +infinity or '-infinity' and excessively large integers +result in encode failure. The records for grouped AVPs are as discussed in the previous section.

@@ -583,7 +588,7 @@ QoSFilterRule() = OctetString()

-Values of these types are not parsed by diameter.

+Values of these types are not currently parsed by diameter.

@@ -594,7 +599,9 @@ Values of these types are not parsed by diameter.

SEE ALSO

-diameterc(1)

+diameterc(1), +diameter(3), +diameter_app(3)

diff --git a/lib/diameter/doc/src/diameter_examples.xml b/lib/diameter/doc/src/diameter_examples.xml index 344b237866..966d1f1eee 100644 --- a/lib/diameter/doc/src/diameter_examples.xml +++ b/lib/diameter/doc/src/diameter_examples.xml @@ -36,5 +36,10 @@ under the License. +

+To be written. +Example code can be found in the diameter application's +examples subdirectory.

+ diff --git a/lib/diameter/doc/src/diameter_intro.xml b/lib/diameter/doc/src/diameter_intro.xml index 0009b2b77d..ef08002a8b 100644 --- a/lib/diameter/doc/src/diameter_intro.xml +++ b/lib/diameter/doc/src/diameter_intro.xml @@ -36,10 +36,60 @@ under the License.

The diameter application is an implementation of the Diameter protocol as defined by RFC 3588. -It supports arbitrary Diameter applications by allowing a client to -specify the commands and AVP's to be supported and has support for -implementing all roles defined in the RFC: client, server and agent. -

+It supports arbitrary Diameter applications by way of a +dictionary interface that allows messages and AVP's to be +defined and input into diameter as configuration. +It has support for all roles defined in the RFC: client, server and +agent. +This chapter provides a short overview of the application.

+ +

+A Diameter peer is implemented by configuring a service and +one or more transports using the interface module +diameter. +The service configuration defines the Diameter applications to be +supported by the peer and, typically, the capabilities that it should +send to remote peers at capabilities exchange upon the establishment +of transport connections. +A transport is configured on a service and provides protocol-specific +send/receive functionality by way of a transport interface defined by +diameter and implemented by a transport module. +The diameter application provides two transport modules: diameter_tcp and diameter_sctp for transport over TCP +(using gen_tcp) and SCTP (using gen_sctp) respectively. +Other transports can be provided by any module that implements +diameter's transport +interface.

+ +

+While a service typically implements a single Diameter peer (as +identified by an Origin-Host AVP), transports can themselves be +associated with capabilities AVP's so that a single service be used to +implement more than one Diameter peer.

+ +

+Each Diameter application defined on a service is configured with a +callback module that implements the application interface through which +diameter communicates the connectivity of remote peers, requests peer +selection for outgoing requests, and communicates the reception of +incoming Diameter request and answer messages. +An application using diameter implements these application callback +modules to provide the functionality of the Diameter peer(s) it +implements.

+ +

+Each Diameter application is also configured with one or more +dictionary modules +that provide encode/decode functionality for outgoing/incoming +Diameter messages. +A module is generated from a specification file using the diameterc utility. +Dictionaries for the RFC 3588 Diameter Common Messages, Base +Accounting and Relay applications are provided by the diameter +application.

diff --git a/lib/diameter/doc/src/diameter_transport.xml b/lib/diameter/doc/src/diameter_transport.xml index be1bb2c56e..37cc871e75 100644 --- a/lib/diameter/doc/src/diameter_transport.xml +++ b/lib/diameter/doc/src/diameter_transport.xml @@ -33,7 +33,7 @@ under the License. diameter_transport -Diameter transport behaviour. +Diameter transport interface. diff --git a/lib/diameter/doc/src/diameter_using.xml b/lib/diameter/doc/src/diameter_using.xml index 737a0a3941..809b76bdf3 100644 --- a/lib/diameter/doc/src/diameter_using.xml +++ b/lib/diameter/doc/src/diameter_using.xml @@ -35,6 +35,9 @@ under the License. +

+To be written.

+ diff --git a/lib/diameter/doc/src/notes.xml b/lib/diameter/doc/src/notes.xml index 8fdb88749e..eafddd7d1e 100644 --- a/lib/diameter/doc/src/notes.xml +++ b/lib/diameter/doc/src/notes.xml @@ -40,8 +40,65 @@ first.

diameter 0.9

-First OTP release.

+Initial release of the diameter application.

+

+Known issues or limitations:

+ + + + +

+Some agent-related functionality is not entirely complete. +In particular, support for proxy agents, that advertise specific +Diameter applications but otherwise relay messages in much the same +way as relay agents (for which a handle_request/3 +callback can return a relay tuple), will be completed in an +upcoming release. +There may also be more explicit support for redirect agents, although +redirect behaviour can be implemented with the current +functionality.

+ + + + +

+There is some asymmetry in the treatment of messages sent as +diameter_header/avp records and those sent in the "normal" +fashion, and not all of this is documented. +This is related to the previous point since this form of sending a +message was introduced specifically to handle relay agent behaviour +using the same callback interface as for client/server behaviour.

+ + + +

+The User's Guide is currently quite thin. +The introductory chapter followed by the examples (in the application +examples subdirectory) may be sufficient +for those having some familiarity with the Diameter protocol but the +intention is to provide more introductory text. +The reference documentation is quite complete, although some points +could likely be expanded upon.

+ + + +

+The function diameter:service_info/2 +can be used to retrieve information about a started service +(statistics, information about connected peers, etc) but +this is not yet documented and both the input and output may change +in the next release.

+ + + + + +

+See Standards Compliance for +standards-related issues.

-- cgit v1.2.3