#lang at-exp racket/base
;; For legal info, see file "info.rkt".

(require (planet neil/mcfly)
         )

(doc (section "Introduction")

     @para{
         This is a simple implementation of a Flash cross-domain policy 
         server written in Racket. It can also be invoked from the command
         line.
         
         }
     
     @margin-note{
         Policy servers are used by Flash to determine which ports can
         be connected to by a Flash-based client application.
         
         }
     
     )

(doc (section "How to use it")
     
     (RACKETBLOCK0
      (run-flash-domain-policy-server aaf ...)
      )
     @para{ Where each aaf is a list of either 2 or 3 elements: }
     (RACKETBLOCK0
         (list  from-domain to-ports)
         (list  from-domain to-ports secure)
      )
     
     @para{Optional keyword arguments:}
           
     (RACKETBLOCK0
      #:notify-proc proc
      )
     @para{ Where proc is procedure with two arguments: }
     (RACKETBLOCK0
      (lambda (a b)
        (printf "~s ~s" a b))
      )
     
     (RACKETBLOCK0
      #:site-control ctrl
      )
     @para{ Where ctrl is one of: }
     (RACKETBLOCK0
        'none
        'master-only
        'by-content-type
        'by-ftp-filename
        'all
        )
        
     (RACKETBLOCK0
      #:http-reqs (list httpreqs ...)
      )
     @para{ Where each httpreqs is a list of either 2 or 3 elements: }
     (RACKETBLOCK0
        (list  from-domain headers)
        (list  from-domain headers secure)
        )
        
     (RACKETBLOCK0
      #:identities (list certs ...)
      )
     @para{ Where each certs is a list of 2 elements: }
     (RACKETBLOCK0
        (list  signature signature-algorithm)
      
      )
     
     @para{
      Parameters for tcp-listen:
      }
     
     (RACKETBLOCK0
      #:max-allow-wait number
      #:hostname string
      #:port port-number
      )
     )

(doc (section "Examples")
     
     @para{
      Runs a server that allow access from any domain (*)
      to port 2000, with the "master-only" site control:
      
      }
     
     (RACKETBLOCK0
      (run-flash-domain-policy-server
        #:site-control 'master-only
        #:notify-proc (lambda (a b) (printf "~s ~s" a b))
        '("*" 2000))
      )

     @para{
      Runs a server that allow access from *.example.com
      to three different ports:
      }
     
     (RACKETBLOCK0
      (run-flash-domain-policy-server '("*.example.com" (123 234 345)))
      )

     @para{
      Runs a server with everything:
      }
  
     (RACKETBLOCK0
      (run-flash-domain-policy-server
       #:notify-proc (lambda (a b) 
                       (printf "~a~n" b))
       #:site-control 'master-only
       #:http-reqs (list '("*" "Jack" #t))
       #:identities (list '("ABC" "DEF"))
       '("*" 2000 #t)
       '("*.example.com" (123 455 200) #t))
      )
     )

(doc history

     (#:planet 1:0 #:date "2012-11-16"
               "Initial release."))