Acesso web via recursos

From Multi Theft Auto: Wiki

O Multi Theft Auto disponibiliza uma interface web a ser usada pelos recursos de diferentes formas. A proposta deste artigo é descrever-las e explicar sua utilização.

Introdução

Há dois componentes chaves desse ecossistema. O primeiro é um servidor web comum, o qual permite os navegadores demandarem páginas e arquivos presentes no recurso. O segundo é um componente que gerencia chamadas realizadas pelos navegadores à funções exportadas de seu recurso.

Páginas

Especificando componentes no arquivo meta

É possível definir certos arquivos acessíveis via servidor web em seu recurso. Para fazer isso é só adicionar:

<html src="nome-do-arquivo.ext" />

Você pode acessar esse arquivo ao digitar o link: http://host:port/nome-do-recurso/nome-do-arquivo.ext
Um exemplo seria um servidor local usando a porta http padrão e com o webmap iniciado: http://127.0.0.1:22005/webmap/map.htm

Arquivos binários

Tirando a possibilidade de você errar o nome, os arquivos usando a tag html podem ser de qualquer tipo. Se eles forem binários (como imagens, .zip), será necessário especificar isso na tag usando raw=true. Isso significa que ele não será pre-processado antes de serem enviado ao servidor web.

Um exemplo:

<html src="image.gif" raw="true" />

Arquivos Processados

Se um arquivo não for binário, então terá de ser pré-processado antes de ser retornado ao cliente. Esse processamento funciona de um jeito muito parecido com PHP ou ASP, mas usa o método do LUA. Você pode inserir scripts do MTA em uma página HTML, controlando sua saída. Quase todas as funções funcionam, incluindo determinadas Funções HTTP, como httpWrite; o qual escreve um texto no buffer.

Por exemplo:

<html>
    <body>
        Esse recurso é chamado de <* httpWrite( getResourceName(getThisResource()) ) *>
    </body>
<html>

Há também uma maneira mais simples (muito utilizada no PHP e ASP) de se escrever o código acima:

<html>
    <body>
        Esse recurso é chamado de <* = getResourceName(getThisResource()) *>
    </body>
<html>

Junto com as funções HTTP, o Lua trabalha com variáveis específicas que contém informações sobre a página demandada:

  • table requestHeaders: É uma tabela contendo todas as headers requisitadas junto com a página. Você pode definir quais serão retornadas com httpSetResponseHeader.
  • table form: Essa tabela abriga todos os dados enviados à página usando HTTP POST seguidos de quaisquer variáveis enviadas à querystring usando HTTP GET.
  • table cookies: Essa contém todos os cookies. É possível altera-los usando httpSetResponseCookie.
  • string hostname: É uma string contendo o endereço de IP ou o nome do host da página requisitada.
  • string url: É a URL da página.
  • account user: Retorna a conta do usuário atual.

É importante lembrar que os arquivos estão em uma máquina virtual separada do resto do seu recurso. Como também, se desejar chamar alguma função presente no script dele, ela terá de ser exportada, e mais tarde, usando-a chamando o call na página criada.

Calls

É possível definir certas funções a serem chamadas via HTTP. Todos os SDKs (listados abaixo) lhe permitem fazer isso remotamente.

Para fazer isto, é só adicionar a linha abaixo em seu meta.xml:

<export function='functionName' http='true' />

A sua função pode ser escrita normalmente e retornar quantas variáveis for preciso; incluindo tabelas, recursos, e o mais importante: elementos. Em contrapartida, não é possível retornar qualquer variável do tipo userdata, como xmlnodes ou funções.

Protocolos

[[{{{image}}}|link=]] Vale Lembrar: Não é preciso aprender isso, a não ser que você esteja escrevendo seu próprio código de HTTP request. Se desejar, use uma das SDKs listadas abaixo.

Chamadas são feitas ao se utilizar http://<IP>:<porta>/<recurso>/call/<função-exportada>' usando HTTP POST. O corpo do comando pode ser uma array JSON contendo argumentos a serem enviados à função.

A resposta HTTP também será uma array JSON contendo valor(es) retornados pela função.

O servidor suporta autenticação HTTP básica e você poderá configurar-la via ACL e pelo sistema padrão de contas.

Chamadas via interface web HTTP

Chamadas são praticamente a coisa mais fácil a ser feita pela interface web.

Primeiro, adicione esta linha no meta:

<include resource="ajax" />

Segundo, adicione o código a seguir dentro de <head> na página da qual deseja chamar a função:

<* = exports.ajax:start(getResourceName(getThisResource())) *>

E a partir de agora, é só digitar um bloco em javascript e chamar as funções quase como se fossem locais. A única diferença é que as chamadas são assíncronas. Não se esqueça de especificar uma função a qual receberá o retorno HTTP no último argumento.

Aí vai um exemplo:

meta.xml

<meta>
   <include resource="ajax" />
   <script src='code.lua' />
   <html src='page.htm' default='true' />
   <export function='showChatMessage' http='true' />
</meta>

code.lua

function showChatMessage ( message )
    outputChatBox ( message )
    return 5;
end

page.htm

<html>
    <head>
        <* = exports.ajax:start(getResourceName(getThisResource())) *>
        <script type='text/javascript'>
            function say() {
                var message = document.getElementById('message')
                showChatMessage ( message.value, 
                    function ( number ) {
                        // the function has been called and returned something
                        message.value = "The function returned " + number;
                    }
                );
            }
        </script>
    </head>
    <body>
        <input type='text' id='message' /><input type='button' value='say' onclick='say();' />
    </body>
</html>

É possível ver alguns exemplos um pouco complexos de como se utiliza esse método nos recursosresourcebrowser, resourcemanager e webadmin.

Garantindo segurança na interface web

O ACL contém um certo número de permissões que podem afetar a maneira como os arquivos são acessados.

Isso funciona para outras permissões do ACL também, ou seja, é possível habilitar-la só a administradores ou um grupo específico.

SDK

Há alguns dos tão conhecidos SDKs disponíveis para interagir com o servidor a partir de outras linguagens de programação. Com isso, é possível (em teoria) escrever gamemodes completos. Na prática, é uma má ideia, porém útil para estatísticas e administração. O SDK de PHP é o mais desenvolvido. Sinta-se a vontade de modificar ou criar seu próprio SDK - não se esqueça de nos mandar uma cópia, por favor!

Veja mais

callRemote - Permite a chamada de funções em páginas PHP (com o SDK próprio) e incluise em outros servidores.