Re: [Tcllib-devel] A proposed new package ... Asking for comments.

[Andreas K. <and...@ac...>]

> Hi Andreas,
>
> Thanks for the clarifications. Your original proposal looks good to me.
> You should try to document its internal working somewhere.

Not sure about that.

> Few minor comments: The name "exeip" looks confusing because of the "ip"
> string in it. How about calling it  "exe_interp" instead.

Done.

> Also, is this
> a separate package or part of current comm package --

Yes.

> do I have to call
> "package require comm::interp" to use it my script

Yes.

> or does it get
> automatically loaded when I do "package require comm".

No.

> I would prefer
> the latter.

I prefer the former actually, keep comm itself focused on the communication
aspects, and use the proposed package for the linkage to useful execution
environments.


Back to the issue of naming, you disliked 'comm::interp'.

Based on what the package does, or provides possible names could be

	comm::link		(does linkage of comm to interps)
and	comm::safe		(provides safe execution environments).


Below is an updated manpage in text format. Changes:

	Fixed the comm::comm typo
	exeip -> exe_interp
	ip -> interp
	Factored description of options into separate section
	Updated the information about command results.
		Impl. actually returns [list $comm $interp],
		not $interp alone. Found that I need both
		so that I can delete them when I am done with
		them. [**]



[**] I wonder if we should try to extend comm channels with client data instead.
Would allow us to stash the created interps with the channel, could be
configured to be deleted on channel destruction with some callback. Then we
would have only one result for the commands above.

________________________________________________________________________________
____

comm::interp(n) 0.1 comm "Remote communication"

NAME
====

comm::interp - Linking communication channels to interpreters

SYNOPSIS
========

package require Tcl 8.4
package require comm ?4.3?
package require comm::interp ?0.1?

::comm::interp::protocol ?-option val...? cmds ?exe_interp?
::comm::interp::safeBasic ?-option val...?
::comm::interp::safe ?-option val...?
::comm::interp::link comm interp

DESCRIPTION
===========

The package *comm::interp* is a supplement to the package *comm* providing
facilities to easily link comm channels to (restricted) Tcl interpreters. By
default the scripts received by a comm channel are executed in the main
interpreter of the receiving process, making for a very insecure model of
execution. Something to be used only in a very secure and/or trusted
environment. For everyone else this package was written, allowing the easy
compartmentalization of execution, restriction to a safe environment, to
specific commands, etc. Together with the ability of *comm* to create multiple
channels, non-listening channels, local channels, etc. it is possible to handle
a very wide range of security requirements.

Note and remember that the communication channels provided by the package *comm*
are objects, i.e. commands, and not Tcl channels. whenever we talk about
channels we talk about objects, except where explicitly noted otherwise.

API
===

    ::comm::interp::protocol ?-option val...? cmds ?exe_interp?

        This command creates a new communication channel which understands
        exactly the commands listed as the keys of the dictionary cmds. The
        associated values are the actual commands executed in their lieu, in the
        existing interpreter exe_interp. This interpreter defaults to the
        current interpreter invoking the command. For any other interpreter it
        is the callers responsibility to create it.

        The command returns a 2-element list containing, in the given order, the
        fully qualified name of the communication channel, and the path of an
        internal interpreter used to connect comm channel and execution
        interpreter. This enables the caller to perform additional
        intializations of the internal interpreter, but is primarily done to
        allow proper deletion of both comm channel and interpreter when we are
        done. Regarding initializations, using an empty mapping for cmds for
        example will leave us with an empty interpreter to be initialized at
        will.

        The internal interpreter is set up such that it is empty of any and all
        commands, save for a set of aliases for the commands in the mapping
        cmds. As the script execution of the comm channel is directed into this
        interpreter this enforces the restriction of the protocol to the set of
        defined commands.

        For the options understood by this command see the section -> OPTIONS.

    ::comm::interp::safeBasic ?-option val...?

        This command creates a new communication channel which understands all
        the commands of a basic safe interpreter. The safe interpreter used for
        the execution of the received scripts is created by the command.

        The term _basic_ means that the created interpreter is the plain result
        of invoking interp create -safe.

        The command returns a 2-element list containing, in the given order, the
        fully qualified name of the communication channel, and the path of the
        created safe interpreter. This enables the caller to perform additional
        intializations of the safe interpreter, but is primarily done to allow
        proper deletion of both comm channel and interpreter when we are done.

        For the options understood by this command see the section -> OPTIONS.

    ::comm::interp::safe ?-option val...?

        This command a new communication channel which understands all the
        commands of a safe interpreter crated by the *safe* package of the Tcl
        core. The safe interpreter used for the execution of the received
        scripts is created by the command using the builtin command
        ::safe::interpCreate.

        The command returns a 2-element list containing, in the given order, the
        fully qualified name of the communication channel, and the path of the
        created safe interpreter. This enables the caller to perform additional
        intializations of the safe interpreter, but is primarily done to allow
        proper deletion of both comm channel and interpreter when we are done.

        For the options understood by this command see the section -> OPTIONS.

    ::comm::interp::link comm interp

        This command takes an existing communication channel comm as created by
        the package *comm*, and an existing interpreter interp and links them
        together. Afterward all scripts received by the channel are executed
        within the context of interp.

        This is the core functionality of this package, used by all preceding
        commands. It allows the most flexibility as both communication channel
        and the interpreter executing the received scripts can be created and
        configured at will. Thereas for the preceding commands the communication
        channel is created and restricted to be a listener, and the interpreters
        are various forms of safe environments, from the highly restricted
        protocol to the more open basic and extended safe interpreters.

OPTIONS
=======

All commands provided by this package taking any options understand the same set
of options.

They are -port, -local, and -silent, with the same meaning as explained in the
documentation for the package *comm*. The option -listen is not recognized, as
the new communication channels created by the commands (with the exception of
::comm::interp::link) are configured to always listen for incoming scripts, this
cannot be deactivated.

The options are always delegated to and processed by the new communication
channel.

SEE ALSO
========

comm

KEYWORDS
========

communication, ipc, message, remote communication, rpc, socket

COPYRIGHT
=========

Copyright (c) 2006 Andreas Kupries.


--
	Andreas Kupries <and...@Ac...>
	Developer @ http://www.ActiveState.com
	Tel: +1 778-786-1122