From 88e255d5de9df416a74fd2b78cbb5028a2cb0c9a Mon Sep 17 00:00:00 2001 From: interp Date: Thu, 13 Mar 2003 11:36:49 +0000 Subject: [PATCH] + Restructuring: Now, we have a three (four) layer concept: Basic User, Advanced User, Administrative User + see file SURFLETS-STRUCTURES.TXT for details + Adapt example surflets to new structures. Only surflets that use extended features should need adaptations. --- scheme/httpd/surflets/packages.scm | 226 ++++++++++++------ scheme/httpd/surflets/surflets-structures.txt | 188 +++++++++++++++ .../web-server/root/surflets/add-html.scm | 1 + .../web-server/root/surflets/add-raw.scm | 2 +- .../root/surflets/admin-handler.scm | 4 +- .../root/surflets/admin-profiling.scm | 7 +- .../root/surflets/admin-surflets-cb.scm | 2 +- .../root/surflets/admin-surflets.scm | 4 +- 8 files changed, 347 insertions(+), 87 deletions(-) create mode 100644 scheme/httpd/surflets/surflets-structures.txt diff --git a/scheme/httpd/surflets/packages.scm b/scheme/httpd/surflets/packages.scm index 556bf54..54c6464 100644 --- a/scheme/httpd/surflets/packages.scm +++ b/scheme/httpd/surflets/packages.scm @@ -23,52 +23,143 @@ surflet-response-headers surflet-response-data)) +;; SUrflet-requests as expected from the surflet handler +(define-interface surflet-handler/requests-interface + (export make-surflet-request ;FIMXE? unusable for user + surflet-request? + surflet-request-request + surflet-request-input-port + surflet-request-method + surflet-request-uri + surflet-request-url + surflet-request-version + surflet-request-headers + surflet-request-socket)) + +(define-interface surflets/error-interface + (export send-error ;send error response + (status-code :syntax))) ;from httpd-responses + ;; Use for SUrflets -(define-interface surflet-handler/surflets-interface +(define-interface surflet-handler/primitives-interface (compound-interface surflet-handler/responses-interface + surflet-handler/requests-interface + surflets/error-interface (export send/suspend ;send and suspend send/finish ;send and finish send ;just send (no finish, no suspend) - send-error ;send error response - set-session-data! - get-session-data - adjust-timeout! ;adjusts timeout of current session ))) -;; Use for adminstration of the Surflet Handler -(define-interface surflet-handler/admin-interface - (export get-loaded-surflets - unload-surflet - options-session-lifetime - options-cache-surflets? - options-surflet-path - set-options-session-lifetime! - set-options-cache-surflets?! +;; Send HTML-Strings (for advanced user) +(define-interface surflets/send-html-string-interface + (export send-html-string/suspend + send-html-string/finish + send-html-string)) +;; Extensions/Exports to/from Olegs SSAX library +(define-interface surflets/sxml-interface + (export display-low-level-sxml + sxml->string + sxml->string/internal + sxml-attribute? + default-rule + text-rule + attribute-rule)) + +;; SUrflets' extensions to SXML +(define-interface surflets/surflet-sxml-interface + (export surflet-sxml->low-level-sxml + surflet-sxml-rules + surflet-form-rule + default-rules + plain-html-rule + url-rule)) + +;; Use for advanced users: make your own conversion rules. +(define-interface surflets/my-sxml-interface + (compound-interface + surflets/send-html-string-interface + surflets/sxml-interface + surflets/surflet-sxml-interface)) + +(define-interface surflets/continuations-interface + (export get-continuations + delete-continuation!)) + +;; Access to session-id and continuation-id +(define-interface surflets/ids-interface + (export my-session-id + my-continuation-id + my-ids + instance-session-id)) + +;; Use for advanced users: access to your sessions and continuations +;; and continuations (currently you get access to all sessions; this +;; should and will be restricted in the future) +(define-interface surflets/my-sessions-interface + (compound-interface + surflets/ids-interface + surflets/continuations-interface + (export get-session + ;; That would be too much: + ;; get-sessions + delete-session! + get-session-data + set-session-data! + instance-session-id + session-adjust-timeout! + adjust-timeout! + session-alive? + session-surflet-name + options-session-lifetime + options-cache-surflets?))) + +(define-interface surflets/sessions-interface + (export get-session get-sessions + delete-session! + get-session-data + set-session-data! + instance-session-id + session-adjust-timeout! + adjust-timeout! session-alive? session-surflet-name + ;; FIXME: This is too much and should be restricted: session-memo session-continuation-table session-continuation-table-lock - session-continuation-counter - delete-session! + session-continuation-counter)) - session-adjust-timeout! - adjust-timeout! +(define-interface surflet-handler/surflets-interface + (export get-loaded-surflets + unload-surflet)) - get-continuations - delete-continuation! +(define-interface surflet-handler/options-interface + (export options-session-lifetime + options-cache-surflets? + options-surflet-path + set-options-session-lifetime! + set-options-cache-surflets?!)) - instance-session-id - - resume-url? +(define-interface surflet-handler/resume-url-interface + (export resume-url? resume-url-ids resume-url-session-id resume-url-continuation-id)) +;; Use for adminstration of the Surflet Handler +(define-interface surflet-handler/admin-interface + (compound-interface + surflet-handler/surflets-interface + surflets/sessions-interface + surflets/continuations-interface + surflet-handler/resume-url-interface + surflet-handler/options-interface +)) + ;; THE interface that SUrflets use. (define-interface surflet-interface (export main)) ; MAIN gets one parameter, the REQUEST @@ -141,18 +232,7 @@ thread-safe-counter-next! thread-safe-counter?)) -;; SUrflet-requests as expected from the surflet handler -(define-interface surflet-requests-interface - (export make-surflet-request - surflet-request? - surflet-request-request - surflet-request-input-port - surflet-request-method - surflet-request-uri - surflet-request-url - surflet-request-version - surflet-request-headers - surflet-request-socket)) + ;; These two are from Martin Gasbichler: (define-interface rt-module-language-interface @@ -177,14 +257,7 @@ (export typed-optionals (optionals :syntax))) -;; Extensions/Exports to/from Olegs SSAX library -(define-interface surflets/sxml-interface - (export display-low-level-sxml - sxml->string - sxml-attribute? - default-rule - text-rule - attribute-rule)) + ;; Input-fields as Scheme objects (define-interface surflets/input-fields-interface @@ -213,22 +286,6 @@ (export *input-field-trigger* input-field-html-tree)) -;; SUrflets' extensions to SXML -(define-interface surflets/surflet-sxml-interface - (export surflet-sxml->low-level-sxml - surflet-sxml-rules - surflet-form-rule - default-rules - plain-html-rule - url-rule)) - -;; Access to session-id and continuation-id -(define-interface surflets/ids-interface - (export my-session-id - my-continuation-id - my-ids - instance-session-id)) - ;; Some utilities (define-interface surflets/utilities-interface (export form-query-list @@ -263,33 +320,39 @@ extract-bindings extract-single-binding)) -;; HTML-Extensions to send/suspend et al. +;; HTML-Extensions to send/suspend et al. (for basic user) (define-interface surflets/send-html-interface (export send-html/suspend send-html/finish send-html)) -;; Helping functions for surflets + +;; Helping functions for surflets (for basic user) (define-interface surflets-interface (compound-interface - surflet-handler/surflets-interface - surflets/sxml-interface - surflets/surflet-sxml-interface +; surflet-handler/surflets-interface; +; surflets/sxml-interface +; surflets/surflet-sxml-interface surflets/send-html-interface surflets/input-fields-interface surflets/addresses-interface surflets/returned-via-interface surflets/bindings-interface)) - ;;; Structures ;; structures from SUrflet Handler (define-structures ((surflet-handler surflet-handler-interface) (surflet-handler/surflets surflet-handler/surflets-interface) + (surflet-handler/options surflet-handler/options-interface) + (surflet-handler/resume-url surflet-handler/resume-url-interface) (surflet-handler/admin surflet-handler/admin-interface) - (surflet-handler/responses surflet-handler/responses-interface)) + (surflet-handler/primitives surflet-handler/primitives-interface) + (surflet-handler/responses surflet-handler/responses-interface) + (surflets/sessions surflets/sessions-interface) + (surflets/continuations surflets/continuations-interface) + (surflets/error surflets/error-interface)) (open define-record-types ;DEFINE-RECORD-TYPE handle-fatal ;WITH-FATAL-ERROR-HANDLER* et al. handle-fatal-error @@ -319,15 +382,19 @@ ;; SUrflets library of helping functions (define-structure surflets surflets-interface - (open surflet-handler/surflets - surflets/sxml - surflets/surflet-sxml - surflets/send-html + (open surflets/send-html surflets/input-fields surflets/addresses surflets/returned-via surflets/bindings)) +;; SUrflets library for advanced users: make and use your own +;; conversion rules. +(define-structure surflets/my-sxml surflets/my-sxml-interface + (open surflets/send-html-string + surflets/sxml + surflets/surflet-sxml)) + ;; Shift-Reset (define-structure shift-reset shift-reset-interface (open scheme @@ -371,8 +438,14 @@ define-record-types) (files thread-safe-counter)) -;; SUrflet-requests as expected from the SUrflet handler -(define-structure surflet-requests surflet-requests-interface +;; SUrflet-requests as expected from the SUrflet handler +;;; We have two names for the same thing to ease the use of structure +;;; names: requests seem to be part of the surflet-handler, but are +;;; actually seperate files. If you know everything about SUrflets, +;;; you use `surlfet-requests'. +(define-structures + ((surflet-handler/requests surflet-handler/requests-interface) + (surflet-requests surflet-handler/requests-interface)) (open scheme define-record-types httpd-requests) @@ -442,7 +515,7 @@ (define-structure surflets/utilities surflets/utilities-interface (open scheme parse-html-forms - (subset surflet-handler/surflets (send/suspend))) + (subset surflet-handler/primitives (send/suspend))) (files utilities)) @@ -482,10 +555,11 @@ (subset sunet-utilities (get-header))) (files bindings)) -(define-structure surflets/send-html surflets/send-html-interface +(define-structures + ((surflets/send-html surflets/send-html-interface) + (surflets/send-html-string surflets/send-html-string-interface)) (open scheme - (subset httpd-responses (status-code)) - surflet-handler/surflets + surflet-handler/primitives surflets/sxml surflets/surflet-sxml) (files send-html)) diff --git a/scheme/httpd/surflets/surflets-structures.txt b/scheme/httpd/surflets/surflets-structures.txt new file mode 100644 index 0000000..1ca7b11 --- /dev/null +++ b/scheme/httpd/surflets/surflets-structures.txt @@ -0,0 +1,188 @@ +We have three basic layers of structures: -*- Outline -*- + +* Overview +(a) Basic User surflets, simple-surflet-api +(b) Advanced User surflets/my-sxml, surflets/my-sessions, + surflet-handler/primitives +(c) Administrative User surflet-handler/admin, profiling + +The fourth layer: +(d) Various surflets/outdaters, surflets/utilities + +Finally, there is a HOWTO added, that describes how you can use your +own rules. + +* (a) Basic User +** structures: (1) surflets + provides: . sending of html represented by surflet-sxml + . using special tags in its surflet-sxml: + url, plain-html, surflet-form + . input-fields, input-field-value,... + . get-bindings, extract-bindings, ... + . make-address, make-annotated-address, ... + . returned-via?, case-returned-via, ... + surflets is splitted in several parts, that can + be loaded independently from each other. + +** structures: (2) simple-surflet-api + provides: . PLT like generation of simple web pages: + . single-query, form-query, inform-page, + final-page + . make-password, make-number... + + +* (b) Advanced User +** structures: (1) surflets/my-sxml + provides: . generating and sending of own sxml, + see HOWTO below + . send-html-string/suspend... + . sxml-rules... + . sxml->string + . surflet-sxml-rules... + . surflet-sxml->low-level-sxml + +** structures: (2) surflets/my-sessions + provides: . Everything needed to administrate your own + sessions and continuations. + (This represents the access to the sessions of + one surflet. However, you currently have + access to all sessions. This will be + restricted in the future.) + . my-session-id, my-continuation-id, + instance-session-id + . get-session, delete-session! + . get-continuation, delete-continuation! + . session-adjust-timeout!, adjust-timeout! + . session-alive?, session-surflet-name + . access to options: options-session-lifetime, + options-cache-surflets? +** structures: (3) surflet-handler/primitives + provides: . Access to the primitives of the + surflet handler: + . send/suspend, ... that send surflet responses + . send-error (sending Webserver error message) + . make-surflet-response, ... status-code: + surflet responses with own status-code, own + content-type, own headers and own content + (string or list of strings) + . surflet-requests... + + +* (c) Administrative User +** structures: (1) surflet-handler/admin + provides: . Access to all internal structures of the + handler + . surflets: get-loaded-surflets, unload-surflet + . sessions: get-session, get-sessions, + session-data, instance-session-id, + adjust-timeout..., session-record selectors + . continuations: get-continuations, + delete-continuations! + . resume-urls: resume-url?, resume-url-ids... + . options: options-session-lifetime... + set-options...! + surflet-handler/admin is splitted in several + parts, that can be loaded independently from + each other. + +** structures: (2) profiling + provides: . Access to memory usage of the whole scsh session + . profile-space, profile-results, + with-gnuplot-data-file, space-info-pair, + space-info-symbol... + + +* (d) Various +** structures: (1) surflets/outdaters + provides: . Data structure to prevent call for outdated + links. This is useful if in some places of your + session the user should not go back and recall + another continuation. + . make-outdater, if-outdated, show-outdated + +** structures: (2) surflets/utilities + provides: . Various utilities that didn't fit in another + package but were too small for an own one. + . form-query-list: url-query->alist + . rev-append + . make-callback enables you to place a callback + below a link. If the user clicks the link, an + arbitrary function is called. + . generate-unique-name generates name from a + prefix that are highest probable unique with + this prefix. For example this is used to + generate the names of the input fields. + + +* HOWTO use your own conversion rules: + +** (i) Create your own conversion rules: + + (trigger [*preorder*] . function) + + - TRIGGER is the symbol that trigger the rule + + - FUNCTION will get the trigger and the rest of the list, that + triggered the rule as arguments. Thus, if you know, you will + only get (at least x) arguments, FUNCTION must accept (at + least) x+1 arguments. FUNCTION must return a list + containing only characters or strings or, recursively, lists + of this type. (Well, there may be others also, but this is + too advanced.) + + - If *PREORDER* misses, the rules will be first applied to all + arguments, before the are passed to function. + + +*** Examples: + MY-HEAD will take no args and creates my heading: + + (define my-head-rule + `(my-head . (lambda (trigger) + (list "My Page" + title + "STRING/INTERNAL + MY-ATTRIBUTED-HEAD takes attributes as well. As we don't want + to reformat this on our own, we use SXML->STRING/INTERNAL, + assuming that MY-RULES contains *all* the rules we use for + this sublist. As we do everything for the rest of the tree + ourselves, we use *preorder*: + (define my-attributed-head + `(my-attributed-head *preorder* . + ,(lambda (trigger attributes title) + (sxml->string/internal `(head ,attributes (title ,title)) + my-rules)))) + +** (ii) Create your own rule set. + A rule set is a list of conversion rules. + +*** Example: + (define my-rules + (list default-rule + attribute-rule + text-rule + my-head-rule + my-title-head + my-attributed-head)) + +*** Note: + If you want to use SXML->STRING/INTERNAL with the same + rule set that entered the rule, you have to define them + either on top level with define or with letrec like + + (letrec ((my-rules + (cons my-attributed-head-rule default-rules)) + (my-attributed-head-rule + `(my-attributed-head *preorder* . + ,(lambda (trigger attributes title) + (sxml->string/internal `(head ,attributes (title ,title)) + my-rules))))) + my-rules) + diff --git a/scheme/httpd/surflets/web-server/root/surflets/add-html.scm b/scheme/httpd/surflets/web-server/root/surflets/add-html.scm index a0fd046..fe5353c 100644 --- a/scheme/httpd/surflets/web-server/root/surflets/add-html.scm +++ b/scheme/httpd/surflets/web-server/root/surflets/add-html.scm @@ -2,6 +2,7 @@ (open surflets surflets/utilities ;form-query-list surflet-requests + surflet-handler/primitives httpd-responses url scheme-with-scsh) diff --git a/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm b/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm index e98f2ba..c5d30d3 100644 --- a/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm +++ b/scheme/httpd/surflets/web-server/root/surflets/add-raw.scm @@ -5,7 +5,7 @@ url ; HTTP-url-SEARCH srfi-1 ; FILTER surflet-handler/surflets ; SEND/SUSPEND, SEND/FINISH - surflet-handler/responses ; MAKE-SURFLET-RESPONSE + surflet-handler/primitives ; MAKE-SURFLET-RESPONSE scheme-with-scsh) (begin diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm index c8cab58..905979b 100644 --- a/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm +++ b/scheme/httpd/surflets/web-server/root/surflets/admin-handler.scm @@ -3,8 +3,8 @@ handle-fatal-error let-opt surflets - surflet-handler/admin - httpd-responses + surflets/error + surflet-handler/options ) (begin diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm index 2a0f2a5..0563f23 100644 --- a/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm +++ b/scheme/httpd/surflets/web-server/root/surflets/admin-profiling.scm @@ -1,17 +1,16 @@ (define-structure surflet surflet-interface (open scheme-with-scsh surflets - surflet-handler/admin + surflets/sessions + surflets/error profiling handle-fatal-error - httpd-responses (subset srfi-1 (iota)) define-record-types locks let-opt receiving - primitives - handle-fatal-error + (subset primitives (add-finalizer!)) ) (begin diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm index 5bab20f..968a5d4 100644 --- a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm +++ b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets-cb.scm @@ -3,8 +3,8 @@ surflets surflets/utilities ;make-callback surflets/outdaters + surflets/error surflet-handler/admin - httpd-responses handle-fatal-error let-opt srfi-1 ;filter-map diff --git a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm index 18fbe7c..69285be 100644 --- a/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm +++ b/scheme/httpd/surflets/web-server/root/surflets/admin-surflets.scm @@ -4,10 +4,8 @@ surflets/utilities ;make-callback surflets/outdaters surflets/ids + surflets/error surflet-handler/admin - httpd-responses - surflet-requests - url handle-fatal-error let-opt srfi-1 ;filter-map, last