View Original Text

Hide Table of Contents

"I choose to code it in BASH.... I choose to code it in BASH and other things in one week, not because it is easy, but because it is HARD!!!"

#lisíadas #DevOpLife
(modesto, eu, não?)

net.lisias.retro.file.mpd.WS

Documentação do W/S Repo Music Player Daemon (bleh... que nome dou pra isso?)

Não botei autenticação nem controle - logo, sim, o RPi está bem suscetível à um DoS. Testes empíricos demonstraram que o meu upstream doméstico é uma limitação, mas também um deterrance por efeito colateral. Um upstream decente, e o W/S efetivamente sufocaria o resto da máquina trabalhando nas responses. Não, não tem cache (isso vai ficar por conta do NGINX, quando isso subir pro retro.lisias.net - aliás, o QoS vai ficar por conta dele também).

Tudo roda num Raspberry Pi 2011.12 Model B. A idéia original era montar serviços que rodassem em computadores de recursos mínimos, daqueles que se leva para os Encontros de Retrocomputação para apoio ao evento. Usei um RPi porque era o que tinha na mão, mas isso vai rodar com certeza (talvez até melhor) naqueles Thin Client de segunda mão que tão pipocando na Sta Efigênia (tem de 50 a 100 reais).

O Mpd ainda é considerado α (alpha). Nenhuma funcionalidade está formalmente estabelecida, as interfaces podem mudar.

Serviço REST W/S

Implementado em Python 3 .

Uma fuçada rápida nas páginas já diz tudo o que precisa saber para usar o serviço, mas segue uma descrição rápida:

Dado o endereço base, que no momento é http_//home.lisias.net_8089/ (trocar _ por :), o request sempre segue a forma

/<algumacoisa>.<formatodesejado).

Não usar o <formatodesejado> implica numa response em text/plain (adequado para consultas manuais e debugging). Também reconhece .json e .jsonp (json com padding, para furar cross-domain scripting) e o format binário de serialização do Python, Pickle (protocolo 3). Os métodos HTTP reconhecidos são GET, PUT e DELETE, e os eventuais parâmetros da Query seguem a rfc3986 (ou pelo menos, é o que o Bottle me disse).

Se faz um request que existe mas com dados inconsistentes, recebe um 200 com um Response explicando o erro. Se você faz um request que não existe, recebe um 404. Se você faz um request que existe mas com dados inválidos, leva um 500 na orelha e fica por isso mesmo.

Toda resposta retorna um campo booleano chamado error. Se False, success_msg tem uma mensagem de confirmação (normalmente um contador) e os demais campos são o payload da Response - dependente de Request. Se houve um erro, error_msg dá a razão por extenso, e error_code um identificador único no sistema do erro, para automatizar tratamento de erro.

Uma resposta de sucesso pode retornar um campo timetaken_in_secs onde o tempo gasto, sem segundos, no processamento do request é informado num valor float. Responses com coleções podem ter este dado em cada item da coleção. Este campo é opcional, e pode ou não estar presente - incluindo entre um Request e outro do mesmo server.

Requests implementados:

GET /version.<fmt>

retorna a identificação da aplicação e a versão corrente. Bom para saber se o serviço tá de pé (ping). Retorna os formatos reconhecidos pelo W/S (bom para saber o que vc pode usar na hora, já que novos formatos virão).

GET /metadata.<fmt>

retorna os datasources reconhecidos pelo W/S (asimov, wos, etc). Na medida que novos datasources são adicionados, vai-se atualizando esta chamada.

GET /<datasource>/metadata.<fmt>

retorna as entidades reconhecidas por este datasource, bem como seus verbos de ação. Cada entidade vem numa tupla, com o singular e com o plural. Se o Request retorna UMA entidade, use o singular. Se o Request retorna uma coleção, use o plural. Os verbos também vêm em tuplas, com o seu nome e uma lista das entidades que reconhecem.

Entidades singleton (ver Protocolo Confederação) são listadas em seu próprio atributo. No nosso caso, todas elas. :)

Exemplo:

Estas duas chamadas serão importantes na Confederação, uma vez que cada W/S será capaz de explicar o que entende e como acessar, e o agregador poderá fazer o roteamento. Também é legal para fazer um cliente mais espertinho (ao contrário das minhas páginas de exemplo, que são burrinhas de dar dó).

No WebRadio, o conceito de "Entidade" foi levemente pervertido. Uma Entidade, neste serviço, é uma lista de "canais" alternativos para o mesmo audiostream, permitindo que o cliente possa se conectar ao stream mais próximo de seu terminal. Não há mais o requisito de ser apenas dois (singular e plural), até porque não faz sentido neste serviço.

Por convenção, o nome do canal é seguido por ":" seguido de um identificador de stream.

Verbos implementados

Uma vez escolhido o <datasource>, a mecânica é sempre a mesma:

/<datasource>/<entitiy_plural>/<verb>.<fmt>?<parms> (onde parms é rfc3986 )

PUT /<datasource>/playlist/play.<fmt>

Pega o Objeto FileData no corpo da mensagem, baixa o arquivo descrito do repositório, adiciona na playlist corrente no ponto atual e toca.

O formato FileData é essencialmente o retornado pelo search do net.lisias.retro.file.search.WS.

Retorna uma mensagem de sucesso, ou uma de erro.

PUT /<datasource>/playlist/next.<fmt>

Avança a playlist para a próxima música. Volta para a primeira se a corrente for a última.

Retorna uma mensagem de sucesso, ou uma de erro.

PUT /<datasource>/playlist/prev.<fmt>

Retrocede a playlist para a música anteriro. Pula para a última se a corrente for a primeira.

Retorna uma mensagem de sucesso, ou uma de erro.

GET /<datasource>/playlist/current.<fmt>

Retorna na mensagem de sucesso o nome da música, posição na fila e (se disponível) nome do artista numa string pronta para visualização.

Retorna uma mensagem de sucesso, ou uma de erro.

CORS

TODO

Requests "Confederados"

Para gerenciamento do Pool de Proxies (a "Confederação"), o seguinte request foi implementado.

É o único POST em todo o Serviço.

/announce.<fmt>

É usado por um proxy.WS para anunciar que este serviço foi incluído na sua Unidade Confederada.

Não é necessário tomar nenhuma atitude, mas espera-se que o Provider inclua o endereço mencionado no Referer na sua lista de proxies em que está registrado - para sair desregistrando durante o shutdown do serviço.

Datasources

Online

Datasources e seus repositórios. O Primeiro é o que está sendo servido no momento. As demais URLs serão servidas quando implementar suporte para mirrors. Dead repos são repositórios que não são mais atualizados, e portanto não precisam checar cache após a primeira carga - se o arquivo existe, já veio, se não existe, não adianta tentar de novo.

Endereço atual

http://search.lisias.net/retro/modland.html