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?
|
conversion of X-expressions and lists with the format (cons/c bytes?
|
||||||
(listof (or/c string? bytes?))) into response data structures for output.
|
(listof (or/c string? bytes?))) into response data structures for output.
|
||||||
|
|
||||||
The compatibility binding for normalize-response is a coercion from
|
After 5.0.99.4, this implicit conversion has been generalized into
|
||||||
the OLD responses to the NEW response structure.
|
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
|
--- Coercion behavior ---
|
||||||
web-server/servlet-env)
|
|
||||||
|
|
||||||
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
|
--- New response structures ---
|
||||||
web-server/compat/0/servlet-env)
|
|
||||||
|
|
||||||
However, for libraries and more complicated applications, more
|
The http/response-structs module has changed to be almost
|
||||||
detailed changes may be required.
|
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:
|
--- Internal APIs ---
|
||||||
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.
|
|
||||||
|
|
||||||
http/cookie:
|
Many internal APIs are restricted to receive only actual response?
|
||||||
xexpr-response/cookies was removed and folded into response/xexpr.
|
structures:
|
||||||
|
|
||||||
The following places are where old responses were accepted and no longer are:
|
|
||||||
|
|
||||||
configuration-table responders
|
configuration-table responders
|
||||||
authentication responder on dispatchers/dispatch-passwords
|
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-lift --- make
|
||||||
dispatchers/dispatch-pathprocedure --- make
|
dispatchers/dispatch-pathprocedure --- make
|
||||||
http/response --- output-response and output-response/method
|
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-dispatch --- dispatch/servlet
|
||||||
servlet-env --- serve/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
|
However, one function: send/formlet from formlets used to allow any
|
||||||
on the return from start.
|
old response/c as a wrapper result, while the new version requires
|
||||||
|
that the wrapper returns an Xexpr. This changes is justified in that
|
||||||
Footnotes:
|
formlets already bake in support for Xexpr as a fundamental part of
|
||||||
|
their syntax.
|
||||||
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.
|
|
||||||
|
|
|
||||||
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
|
#lang racket/base
|
||||||
(require (prefix-in new: web-server/http/cookie)
|
(require web-server/http/xexpr)
|
||||||
web-server/http/xexpr)
|
|
||||||
|
|
||||||
(define (xexpr-response/cookies cs xe)
|
(define (xexpr-response/cookies cs xe)
|
||||||
(response/xexpr xe #:cookies cs))
|
(response/xexpr xe #:cookies cs))
|
||||||
|
|
||||||
(provide
|
(provide (all-from-out))
|
||||||
(rename-out
|
|
||||||
[new:make-cookie make-cookie]
|
|
||||||
[new:cookie->header cookie->header])
|
|
||||||
(all-from-out))
|
|
||||||
|
|
@ -1,10 +1,7 @@
|
||||||
#lang racket/base
|
#lang racket/base
|
||||||
(require racket/contract
|
(require web-server/http/response-structs
|
||||||
(prefix-in new: web-server/http/response-structs)
|
|
||||||
web-server/http/response-structs
|
|
||||||
web-server/http/xexpr
|
web-server/http/xexpr
|
||||||
racket/list
|
racket/list)
|
||||||
xml)
|
|
||||||
|
|
||||||
(define response/basic? response?)
|
(define response/basic? response?)
|
||||||
(define (make-response/basic c m s mime hs)
|
(define (make-response/basic c m s mime hs)
|
||||||
|
|
@ -48,11 +45,6 @@
|
||||||
(define (response/incremental-body r)
|
(define (response/incremental-body r)
|
||||||
(hash-ref GENS 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 make-xexpr-response response/xexpr)
|
||||||
|
|
||||||
(define (normalize-response r [close? #f])
|
(define (normalize-response r [close? #f])
|
||||||
|
|
@ -67,7 +59,6 @@
|
||||||
(response/xexpr r)]))
|
(response/xexpr r)]))
|
||||||
|
|
||||||
(provide
|
(provide
|
||||||
(rename-out [new:TEXT/HTML-MIME-TYPE TEXT/HTML-MIME-TYPE])
|
|
||||||
(except-out (all-defined-out)
|
(except-out (all-defined-out)
|
||||||
BODIES
|
BODIES
|
||||||
GENS))
|
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?]{
|
@defthing[xexpr-response/c contract?]{
|
||||||
A contract for use with @racket[current-response/c] that coerces
|
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]
|
@defproc[(response/xexpr [xexpr xexpr/c]
|
||||||
[#:code code number? 200]
|
[#:code code number? 200]
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue
Block a user