From b5a39d03e4ea59bb6a238759f7d6d9568324f04a Mon Sep 17 00:00:00 2001 From: Jay McCarthy Date: Sat, 4 Dec 2010 23:16:27 -0700 Subject: [PATCH] Discussing compatibility --- collects/tests/web-server/pr/compat0.rkt | 3 + collects/web-server/compat/0/README | 102 +++++++++--------- collects/web-server/compat/0/coerce.rkt | 6 ++ collects/web-server/compat/0/dispatch.rkt | 9 -- .../web-server/compat/0/dispatch/serve.rkt | 8 -- .../compat/0/dispatchers/dispatch-lift.rkt | 11 -- .../0/dispatchers/dispatch-pathprocedure.rkt | 11 -- collects/web-server/compat/0/http.rkt | 17 --- collects/web-server/compat/0/http/cookie.rkt | 9 +- .../compat/0/http/response-structs.rkt | 13 +-- .../web-server/compat/0/http/response.rkt | 14 --- .../web-server/compat/0/servlet-dispatch.rkt | 14 --- collects/web-server/compat/0/servlet-env.rkt | 13 --- collects/web-server/compat/0/servlet.rkt | 15 --- collects/web-server/compat/0/servlet/web.rkt | 42 -------- collects/web-server/compat/README | 7 +- collects/web-server/scribblings/http.scrbl | 3 +- 17 files changed, 68 insertions(+), 229 deletions(-) create mode 100644 collects/tests/web-server/pr/compat0.rkt create mode 100644 collects/web-server/compat/0/coerce.rkt delete mode 100644 collects/web-server/compat/0/dispatch.rkt delete mode 100644 collects/web-server/compat/0/dispatch/serve.rkt delete mode 100644 collects/web-server/compat/0/dispatchers/dispatch-lift.rkt delete mode 100644 collects/web-server/compat/0/dispatchers/dispatch-pathprocedure.rkt delete mode 100644 collects/web-server/compat/0/http.rkt delete mode 100644 collects/web-server/compat/0/http/response.rkt delete mode 100644 collects/web-server/compat/0/servlet-dispatch.rkt delete mode 100644 collects/web-server/compat/0/servlet-env.rkt delete mode 100644 collects/web-server/compat/0/servlet.rkt delete mode 100644 collects/web-server/compat/0/servlet/web.rkt diff --git a/collects/tests/web-server/pr/compat0.rkt b/collects/tests/web-server/pr/compat0.rkt new file mode 100644 index 0000000000..b7d92bb39d --- /dev/null +++ b/collects/tests/web-server/pr/compat0.rkt @@ -0,0 +1,3 @@ +#lang racket/base +(require web-server/http/response-structs + web-server/compat/0/http/response-structs) \ No newline at end of file diff --git a/collects/web-server/compat/0/README b/collects/web-server/compat/0/README index a316adb6ca..322736eb53 100644 --- a/collects/web-server/compat/0/README +++ b/collects/web-server/compat/0/README @@ -2,75 +2,73 @@ In Racket 5.0.99.4 and before, the Web Server supported implicit conversion of X-expressions and lists with the format (cons/c bytes? (listof (or/c string? bytes?))) into response data structures for output. -The compatibility binding for normalize-response is a coercion from -the OLD responses to the NEW response structure. +After 5.0.99.4, this implicit conversion has been generalized into +current-response/c and response/c. In the process, implicit conversion +has been completely removed from some internal plumbing AND the +response structures have been streamlined---primarily for efficiency. -For most applications, preserving compatibility is as simple as changing: +This document describes the incompatible changes and how to restore +the old behavior when that is possible. -(require web-server/servlet - web-server/servlet-env) +--- Coercion behavior --- -to +The old coercion behavior will be dynamically introduced by requiring +web-server/compat/0/coerce or parameterizing current-response/c to +(coerce/c normalize-response) after requiring +web-server/compat/0/http/response-structs. -(require web-server/compat/0/servlet - web-server/compat/0/servlet-env) +--- New response structures --- -However, for libraries and more complicated applications, more -detailed changes may be required. +The http/response-structs module has changed to be almost +unrecognizable. http/response-structs was provided through http and +servlet, so many Web applications implicitly rely on it. -Other incompatibilities introduced without compatibility bindings: +web-server/compat/0/http/response-structs provides a version that +implements the old behavior without interferring with new version +(i.e., they can both be required simultaneously.) [N.B. response/port +was only present for a few weeks, so it is not provided in the +compatibility library.] -send/formlet requires that the wrapper return an Xexpr +--- xexpr-response/cookies --- -Other incompatibilities introduced with compatibility bindings: +The http/cookie module provided xexpr-response/cookies, but that +functionality is now part of response/xexpr. The old function can be +required from web-server/compat/0/http/cookie (without interferring +with any other bindings from the new cookie module.) -http/response-structs: -response/basic was removed. -response/full was removed. -response/port was removed [1] -The response/incremental structure was removed. -response/c was removed. -make-xexpr-response was renamed response/xexpr and extended. -normalize-response was removed. +--- Internal APIs --- -http/cookie: -xexpr-response/cookies was removed and folded into response/xexpr. - -The following places are where old responses were accepted and no longer are: +Many internal APIs are restricted to receive only actual response? +structures: configuration-table responders authentication responder on dispatchers/dispatch-passwords -servlet-loading responder on dispatchers/dispatch-servlets -#lang web-server/insta [2] -lang/web --- make-stateless-servlet -private/servlet --- handler field -servlet-env --- serve/servlet's #:file-not-found-responder arg -serlet/servlet-structs --- response-generator/c, expiration-handler/c -servlet/setup --- make*servlet -servlet/web --- with-errors-to-browser - -The following places are where old responses were accepted and no -longer are, but compatible bindings are provided: - -dispatch/serve --- serve/dispatch dispatchers/dispatch-lift --- make dispatchers/dispatch-pathprocedure --- make http/response --- output-response and output-response/method + +No compatible interface is provided for these functions and data structures. + +--- External APIs --- + +Most external APIs now use the new response/c. Specifically: + +dispatch/serve --- serve/dispatch servlet-dispatch --- dispatch/servlet servlet-env --- serve/servlet -servlet/web --- send/* +servlet/web --- send/*, with-errors-to-browser +dispatchers/dispatch-servlets --- servlet-loading responder argument +#lang web-server/insta +lang/web --- make-stateless-servlet +private/servlet --- handler field +serlet/servlet-structs --- response-generator/c, expiration-handler/c +servlet/setup --- make*servlet -Here are some ideas that could be use to ease backwards compatibility: +These represent nearly every place where servlets typically interact +with the server. -* A new servlet version for module servlets that puts an old contract - on the return from start. - -Footnotes: - -1. response/port was present for a few weeks, so no compatibility is provided. - -2. If anyone can suggest a good way to provide a compatibility layer -without duplicating code, I'm interested. The problem is that -web-server/insta walks the module source to find the "start" function, -and we'd presumably want to overwrite that. Plus, web-server/insta -will import other bindings that now have imcompatibilities. +However, one function: send/formlet from formlets used to allow any +old response/c as a wrapper result, while the new version requires +that the wrapper returns an Xexpr. This changes is justified in that +formlets already bake in support for Xexpr as a fundamental part of +their syntax. diff --git a/collects/web-server/compat/0/coerce.rkt b/collects/web-server/compat/0/coerce.rkt new file mode 100644 index 0000000000..9f0909410b --- /dev/null +++ b/collects/web-server/compat/0/coerce.rkt @@ -0,0 +1,6 @@ +#lang racket/base +(require unstable/contract + "http/response-structs.rkt" + web-server/servlet/servlet-structs) + +(current-response/c (coerce/c normalize-response)) \ No newline at end of file diff --git a/collects/web-server/compat/0/dispatch.rkt b/collects/web-server/compat/0/dispatch.rkt deleted file mode 100644 index a4f196de0a..0000000000 --- a/collects/web-server/compat/0/dispatch.rkt +++ /dev/null @@ -1,9 +0,0 @@ -#lang racket/base -(require web-server/dispatch/syntax - "dispatch/serve.rkt" - web-server/dispatch/url-patterns - web-server/dispatch/container) -(provide (all-from-out web-server/dispatch/syntax - "dispatch/serve.rkt" - web-server/dispatch/url-patterns - web-server/dispatch/container)) diff --git a/collects/web-server/compat/0/dispatch/serve.rkt b/collects/web-server/compat/0/dispatch/serve.rkt deleted file mode 100644 index 477fc2a2ea..0000000000 --- a/collects/web-server/compat/0/dispatch/serve.rkt +++ /dev/null @@ -1,8 +0,0 @@ -#lang racket/base -(require (prefix-in new: web-server/dispatch/serve) - "../http/response-structs.rkt") - -(define (serve/dispatch d) - (new:serve/dispatch (λ (req) (normalize-response (d req))))) - -(provide (all-defined-out)) \ No newline at end of file diff --git a/collects/web-server/compat/0/dispatchers/dispatch-lift.rkt b/collects/web-server/compat/0/dispatchers/dispatch-lift.rkt deleted file mode 100644 index 4b9c7dbb62..0000000000 --- a/collects/web-server/compat/0/dispatchers/dispatch-lift.rkt +++ /dev/null @@ -1,11 +0,0 @@ -#lang racket/base -(require (prefix-in new: web-server/dispatchers/dispatch-lift) - "../http/response-structs.rkt") - -(define (make d) - (new:make (λ (req) (normalize-response (d req))))) - -(provide - (rename-out - [new:interface-version interface-version]) - (all-defined-out)) \ No newline at end of file diff --git a/collects/web-server/compat/0/dispatchers/dispatch-pathprocedure.rkt b/collects/web-server/compat/0/dispatchers/dispatch-pathprocedure.rkt deleted file mode 100644 index 7654bd996b..0000000000 --- a/collects/web-server/compat/0/dispatchers/dispatch-pathprocedure.rkt +++ /dev/null @@ -1,11 +0,0 @@ -#lang racket/base -(require (prefix-in new: web-server/dispatchers/dispatch-pathprocedure) - "../http/response-structs.rkt") - -(define (make p d) - (new:make p (λ (req) (normalize-response (d req))))) - -(provide - (rename-out - [new:interface-version interface-version]) - (all-defined-out)) \ No newline at end of file diff --git a/collects/web-server/compat/0/http.rkt b/collects/web-server/compat/0/http.rkt deleted file mode 100644 index 3d021d1d8c..0000000000 --- a/collects/web-server/compat/0/http.rkt +++ /dev/null @@ -1,17 +0,0 @@ -#lang racket/base -(require web-server/http/basic-auth - web-server/http/digest-auth - web-server/http/request-structs - "http/response-structs.rkt" - "http/cookie.rkt" - web-server/http/cookie-parse - web-server/http/redirect - web-server/http/xexpr) -(provide (all-from-out web-server/http/basic-auth - web-server/http/digest-auth - web-server/http/request-structs - "http/response-structs.rkt" - "http/cookie.rkt" - web-server/http/cookie-parse - web-server/http/redirect - web-server/http/xexpr)) diff --git a/collects/web-server/compat/0/http/cookie.rkt b/collects/web-server/compat/0/http/cookie.rkt index c409217a7f..834b08baaa 100644 --- a/collects/web-server/compat/0/http/cookie.rkt +++ b/collects/web-server/compat/0/http/cookie.rkt @@ -1,12 +1,7 @@ #lang racket/base -(require (prefix-in new: web-server/http/cookie) - web-server/http/xexpr) +(require web-server/http/xexpr) (define (xexpr-response/cookies cs xe) (response/xexpr xe #:cookies cs)) -(provide - (rename-out - [new:make-cookie make-cookie] - [new:cookie->header cookie->header]) - (all-from-out)) \ No newline at end of file +(provide (all-from-out)) \ No newline at end of file diff --git a/collects/web-server/compat/0/http/response-structs.rkt b/collects/web-server/compat/0/http/response-structs.rkt index cc324603a4..04a8a010b5 100644 --- a/collects/web-server/compat/0/http/response-structs.rkt +++ b/collects/web-server/compat/0/http/response-structs.rkt @@ -1,10 +1,7 @@ #lang racket/base -(require racket/contract - (prefix-in new: web-server/http/response-structs) - web-server/http/response-structs +(require web-server/http/response-structs web-server/http/xexpr - racket/list - xml) + racket/list) (define response/basic? response?) (define (make-response/basic c m s mime hs) @@ -48,11 +45,6 @@ (define (response/incremental-body r) (hash-ref GENS r)) -(define response/c - (or/c response/basic? - (cons/c bytes? (listof (or/c string? bytes?))) - xexpr/c)) - (define make-xexpr-response response/xexpr) (define (normalize-response r [close? #f]) @@ -67,7 +59,6 @@ (response/xexpr r)])) (provide - (rename-out [new:TEXT/HTML-MIME-TYPE TEXT/HTML-MIME-TYPE]) (except-out (all-defined-out) BODIES GENS)) \ No newline at end of file diff --git a/collects/web-server/compat/0/http/response.rkt b/collects/web-server/compat/0/http/response.rkt deleted file mode 100644 index aa85ab5fff..0000000000 --- a/collects/web-server/compat/0/http/response.rkt +++ /dev/null @@ -1,14 +0,0 @@ -#lang racket/base -(require (prefix-in new: web-server/http/response) - "../http/response-structs.rkt") - -(define (output-response conn r) - (new:output-response conn (normalize-response r))) -(define (output-response/method conn r meth) - (new:output-response/method conn (normalize-response r) meth)) - -(provide - (rename-out - [new:print-headers print-headers] - [new:output-file output-file]) - (all-defined-out)) \ No newline at end of file diff --git a/collects/web-server/compat/0/servlet-dispatch.rkt b/collects/web-server/compat/0/servlet-dispatch.rkt deleted file mode 100644 index e7b349abc8..0000000000 --- a/collects/web-server/compat/0/servlet-dispatch.rkt +++ /dev/null @@ -1,14 +0,0 @@ -#lang racket/base -(require (prefix-in new: web-server/servlet-dispatch) - "http/response-structs.rkt") - -(define dispatch/servlet - (make-keyword-procedure - (lambda (kws kw-args gen) - (keyword-apply new:dispatch/servlet - kws - kw-args - (λ (req) (normalize-response (gen req))))))) - -(provide (rename-out [new:serve/launch/wait serve/launch/wait]) - (all-defined-out)) \ No newline at end of file diff --git a/collects/web-server/compat/0/servlet-env.rkt b/collects/web-server/compat/0/servlet-env.rkt deleted file mode 100644 index 3152b8871a..0000000000 --- a/collects/web-server/compat/0/servlet-env.rkt +++ /dev/null @@ -1,13 +0,0 @@ -#lang racket/base -(require (prefix-in new: web-server/servlet-env) - "http/response-structs.rkt") - -(define serve/servlet - (make-keyword-procedure - (lambda (kws kw-args gen) - (keyword-apply new:serve/servlet - kws - kw-args - (λ (req) (normalize-response (gen req))))))) - -(provide (all-defined-out)) \ No newline at end of file diff --git a/collects/web-server/compat/0/servlet.rkt b/collects/web-server/compat/0/servlet.rkt deleted file mode 100644 index 95ee5c2d73..0000000000 --- a/collects/web-server/compat/0/servlet.rkt +++ /dev/null @@ -1,15 +0,0 @@ -#lang racket/base -(require net/url - web-server/servlet/web-cells - web-server/http/bindings - "http.rkt" - "dispatch.rkt" - web-server/servlet/servlet-structs - "servlet/web.rkt") -(provide (all-from-out net/url - web-server/servlet/web-cells - web-server/http/bindings - "http.rkt" - "dispatch.rkt" - web-server/servlet/servlet-structs - "servlet/web.rkt")) diff --git a/collects/web-server/compat/0/servlet/web.rkt b/collects/web-server/compat/0/servlet/web.rkt deleted file mode 100644 index 268c243a4d..0000000000 --- a/collects/web-server/compat/0/servlet/web.rkt +++ /dev/null @@ -1,42 +0,0 @@ -#lang racket/base -(require (prefix-in new: web-server/servlet/web) - "../http/response-structs.rkt") - -(define-syntax-rule (define-send/back-like new:send/back send/back) - (define (send/back r) - (new:send/back (normalize-response r)))) - -(define-send/back-like new:send/back send/back) -(define-send/back-like new:send/finish send/finish) - -(define-syntax-rule (define-send/forward-like new:send/forward send/forward) - (define (send/forward generator) - (new:send/forward - (λ (k-url) - (normalize-response (generator k-url)))))) - -(define-send/forward-like new:send/forward send/forward) -(define-send/forward-like new:send/suspend send/suspend) -(define-send/forward-like new:send/suspend/url send/suspend/url) - -(define-syntax-rule (define-ssd-like new:send/suspend/dispatch send/suspend/dispatch) - (define (send/suspend/dispatch generator) - (new:send/suspend/dispatch - (λ (embed/url) - (normalize-response - (generator embed/url)))))) - -(define-ssd-like new:send/suspend/dispatch send/suspend/dispatch) -(define-ssd-like new:send/suspend/url/dispatch send/suspend/url/dispatch) - -(provide - (rename-out [new:servlet-prompt servlet-prompt] - [new:continuation-url? continuation-url?] - [new:current-servlet-continuation-expiration-handler - current-servlet-continuation-expiration-handler] - [new:redirect/get redirect/get] - [new:redirect/get/forget redirect/get/forget] - [new:adjust-timeout! adjust-timeout!] - [new:clear-continuation-table! clear-continuation-table!] - [new:with-errors-to-browser with-errors-to-browser]) - (all-defined-out)) \ No newline at end of file diff --git a/collects/web-server/compat/README b/collects/web-server/compat/README index b1edf5986d..e940f2c59c 100644 --- a/collects/web-server/compat/README +++ b/collects/web-server/compat/README @@ -1,7 +1,6 @@ -Each directory contains a mirror of the Web Server top-level as it was before a backwards incompatible change. +Each directory contains a README describing backwards incompatible changes to the Web Server and instructions for using the compatibility interface in newer versions. -For example, to get the version of web-server/servlet/web before backwards incompatible change 0, require web-server/compat/0/servlet/web. +Most compatibility interfaces mirror the structure of the Web Server collection. For example, to require the version of web-server/http/cookie before backwards incompatible change 0, require web-server/compat/0/http/cookie. -Each directory also contains a README describing the changes and the compatibility interface. +These compatibility interfaces are not documented in the manual to discourage new programs from using the old interface. -These are not documented in the manual to discourage new programs written to the old interface. diff --git a/collects/web-server/scribblings/http.scrbl b/collects/web-server/scribblings/http.scrbl index 0c3e7868cb..d39c366a90 100644 --- a/collects/web-server/scribblings/http.scrbl +++ b/collects/web-server/scribblings/http.scrbl @@ -474,7 +474,8 @@ web-server/insta @defthing[xexpr-response/c contract?]{ A contract for use with @racket[current-response/c] that coerces -X-expressions into @racket[response?] structures using @racket[response/xexpr].} +X-expressions into @racket[response?] structures using @racket[response/xexpr] +and passes @racket[response?] structures untouched.} @defproc[(response/xexpr [xexpr xexpr/c] [#:code code number? 200]