Discussing compatibility
This commit is contained in:
Jay McCarthy
parent
e7c71921bb
commit
b5a39d03e4
3
collects/tests/web-server/pr/compat0.rkt
Normal file
3
collects/tests/web-server/pr/compat0.rkt
Normal file
|
|
@ -0,0 +1,3 @@
|
|||
#lang racket/base
|
||||
(require web-server/http/response-structs
|
||||
web-server/compat/0/http/response-structs)
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
6
collects/web-server/compat/0/coerce.rkt
Normal file
6
collects/web-server/compat/0/coerce.rkt
Normal file
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
(provide (all-from-out))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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"))
|
||||
|
|
@ -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))
|
||||
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
|
|
|
|||
Loading…
Reference in New Issue
Block a user